Dojo 1.6 official tutorial translation: Create a template-based widget (Widget) - 1.6, based, creation, dojo, official, part, Template, translation, tutorial, Widget

Create a template-based widget (Widget)

Author: Tom Trenka

Original link: http://dojotoolkit.org/documentation/tutorials/1.6/templated/

In this tutorial, you will learn an important part of Dijit’s template system: Dijit._Templated and how to use it模板来快速创建自己的小部件

难度: 中等，使用Dojo 版本： 1.6

Dijit （Dojo的小部件库）提供的_Widget 和_WidgetBase The base class provides a complete base class for developing widgets, but the template system introduced by the _Templated base class makes Dijit more powerful and flexible.

使用_Templated ，你可以快速的创建出易于维护，方便修改的小部件。

_Templated 的原理非常简单：它允许开发者创建一小段HTML片段，片段在运行时会被作为字符串加载（或者在build过程中直接内联入代码内）并被所有该小Instances of components are reused.

接下来我们将会解读_Templated 提供了哪些功能，并且动手开发一个使用_Templated 的小部件。

注意：_Templated 应当被当作混入代码使用（mixin)，而不是被直接继承。用面向对象的观点来看，_Templated 更接近一个接口而不是一个类（虽然在JavaScript中，并没有办法明确区分二者）

_Templated 提供了哪些方法和属性

对使用_Templated 的程序员来说或，将_Templated 混入一个小部件将会给这个小部件的类带来下列的新属性：

templateString, // a string representing the HTML of the template
templatePath, // a URL pointing at a file to be used as a template
widgetsInTemplate // a Boolean indicating whether or not child widgets
are defined in the template

注意：templatePath 现在已经基本不使用了，只是为了向后兼容而保留。下面的章节中我们会展示如何搭配使用dojo.cache 和 templateString

这些新属性看起来如此简单，那么多强大的功能仅凭这几个属性就能实现么？ The real answer lies in the other content that _Templated adds to your widget definition.

_Templated覆写的方法

除了上述几个属性之外， _Templated覆写了Dijit Widget架构中的三个基础方法:buildRendering, destroyRendering, 和startup.这三个方法分别负责：解析并填充模板（buildRendering），正确销毁Widget DOM树(destroyRendering), 并保障模板中包含的子Widget能够正确的被启动(startup)

Note: Because the above three methods are necessary for using templates, if you further override these methods in your own code, please be sure to override the code in your Add this.inherited(arguments) to call the method of the parent class to ensure that the template can be processed correctly.

使用_Templated

你只需要在创建Widget的类声明中的第二个参数数组中加入“dijit._Templated” ，就可以让你的Widget 支持模板. 例如，下面的代码就声明了一个支持模板的名为SomeWidget的Widget

dojo.declare(" example.SomeWidget", [dijit._Widget, dijit._Templated ], {templateString: dojo.cache("example", "templates/SomeWidget.html") // your custom code goes here});

Dijit 组件库中的组件都遵循在当前Javascript目录中创建一个单独的名为templates的目录来保存模板的编码习惯。 We recommend that you follow the same approach.

注意：在上述声明中，我们搭配使用了dojo.cache 和templateString 属性，dojo.cache方法会从其缓存Or get the resource from the url.这是最新版dojo中推荐的用来获取资源（例如这里的模板文件）的做法，它确保了使用尽量少的HTTP请求来获取资源.

现在我们Now that there is a declaration of a widget that can support the template, we will write a template for it and explain what functions the template can contain.

创建模板

一个模板就是一个HTML代码片段，你可以在其中定义DOM结构，也可以注入一些特殊的内容. Let’s start with a simple example.

In this simple template, 3 important functions of the Dijit template are demonstrated: variable substitution, attach point, and DOM event binding. Next, we will explain these three functions in turn.
Note: There can only be one root node in each template HTML. A template containing multiple root nodes is illegal.

变量的替换：

模板中可以引用小部件中定义的变量的值。语法很简单

${property}

上述例子中，我们在模板的根节点的class属性里引用了变量baseClass的值（该变量适用于所有Widget）. 如果该If the variable itself is an object, you can further refer to the property value of the object. At this time, you need to add one before the attribute name!

如：
${!propertyObject.property}

注意:从Dijit 1.5 开始，模板中使用变量Value substitution is limited to those attributes that will not change during the entire life cycle of the widget. If you want to be able to modify the value of an attribute during the life cycle, we recommend that you set it by calling the set method in the postCreate method.

附着点(Attache Points)

Dijit 模板系统会在你定义的模板中寻找一个特殊的属性（称为attach point)-Use HTML5 data attribute (data-*) syntax. A connection point tells the template rendering engine: If a data-dojo-attach-point attribute is defined on a DOM node in the template, the reference of the node will be set to the corresponding attribute in the Widget. For example, the SomeWidget template in the above example defines 2 DOM nodes. The main node (the outer div) can be referenced as focusNode in the Widget code, and the inner span node can be referenced through the containerNode property of the Widget.

注意：通常即使你在模板中不设置任何attach point ，模板的根节点可以在widget中通过domNode来引用. So most of the time you don’t need to use this attribute explicitly.

containerNode 容器节点

Dijit定义了一个特殊的附着点叫做”containerNode” . 从名字可以理解，containerNode就是一个容器节点， It provides a place to place additional markup fragments for widgets created using declarative methods. For example:

 This is arbitrary content!
 More arbitrary content !

这个片段使用声明的方式创建了我们前面定义的SomeWidget的实例，在Dojo解释器解析这个段落时，它会实例A SomeWidget is instantiated, and the HTML fragments contained in Div here will be added to the container node defined by SomeWidget at the same time as it is instantiated. So when this Widget is created, the structure of the DOM tree will be:

         This is arbitrary content!
        More arbitrary content!

Note: In the above example, we have omitted some custom HTML5 attributes for the sake of simplicity of the tutorial.

类似的，如果你在Widget声明中嵌入其他的Widget，那么子Widget也将被添加到你的容器节点中去（前提是你的Widget定义了一个Container node). For example:

 This is arbitrary content!
 My Button
    More arbitrary content!

Event binding

In addition to attachment points, the Dijit template system also allows binding native DOM events to custom methods of Widget. This is done through another HTML5 custom data attribute: data-dojo-attach-event. The attribute value is a set of key-value pairs separated by commas (keys are separated by colons), the keys are native DOM events, and the values are custom methods in the Widget to which this event is bound.
例如：

data-dojo-attach-event="onmouseenter:_onHover,onmouseleave:_onUnhover,ondijitclick:_onClick"

< br>

这个例子里我们定义的ondijitclick事件是一个Dijit自己定义的稍有改动onclick处理方法，在Dijit里通常可以使用onclick 的地方都可以是用ondijitclick 代替。

当Widget被实例化时，Diji模板系统会自动遍历所有的事件绑定属性，并使用connect 将这些事件和Widget中的方法绑定起来。当DOM事件被触发时，你的事件处理函数将能获得跟原生DOM事件同样多的参数，因此你可以完全的控制你的Widget.

查看示例

widgetsInTemplate attribute

Finally, the Dijit template system allows you to use the widgetsInTemplate attribute to create composite controls from templates.顾名思义，widgetsInTemplate 指明了你的模板中是否包含其他的Widget(默认值为false).

让我们对我们前面的例子稍作修改，来让它始终包含一个dijit.button

// Modified Widget definition dojo.declare("example.SomeWidget", [dijit._Widget, dijit._Templated ], {templateString: dojo.cache( "example", "templates/SomeWidget.html"), widgetsInTemplate: true // your code}); // template definition  My Button

请注意在修改后的模板中, We defined a connection point buttonWidget on the div node of dijit.form.Button. After that, we can directly use myWidget.buttonWidget to directly reference the widget of the embedded button (instead of just referencing the DOM node). Use this Method, you can use some simple widgets to build a combined widget, such as a widget that can view mailing lists, or a toolbar control that contains a series of buttons.

注意：使用widgetsInTemplate 时可能会有额外的开销，可能会影响你的widget的性能，甚至整个页面的性能。如果你不是非常清楚的了解这个属性的作用，最好还是将它设为false.

结论

在这篇教程中，我们学习Dijit’s powerful template system, the use of mixed-in _Templated, and how you can use templates to quickly build custom Widgets. We also introduced how to use attachment points in templates, how to bind DOM events, and how to build other widgets Methods of combining Widgets.