dojo Creating Template Widget

簡介

dojo 除了提供一系列豐富的圖形介面的元件，也允許程師設計師自行建構圖形介面元件以符合應用的特殊需求。dijit/_WidgetBase 是所有圖形介面元件的基礎，所有的圖形介面元件都繼承自 dijit/_WidgetBase。要能夠在 dojo 中自行開發圖形介面元件，深入瞭解 dijit/_WidgetBase 是絕對必須的。

首先，dijit/_WidgetBase 預先定義了一些每個圖形介面元件都會繼承的共同屬性：

id:: 用來辨識圖形介面元件的唯一名稱，型態為字串。可以自行指定或由 dijit 自行產生。
lang:: 指定取代 dojo 預設使用的語言，這個屬性很少用到。
dir:: 如果指定語言是從右至左，就用這個屬性來指定。
domNode:: 圖形介面主要的 DOM 元素(Element)，多數的圖形介面元件都會修改 HTML 的結構，這個屬性可以參考到組成圖形介面最終的 HTML 元素及節點。
class:: 圖形介面元件 domNode 之 HTML 的 class 屬性。
style:: 圖形介面元件 domNode 之 HTML 的 style 屬性。
title:: 圖形介面元件 domNode 之 HTML 的 title 屬性。
baseClass:: 圖形介面元件在 CSS 中的基本 class 屬性。
srcNodeRef:: 圖形介面元件在 DOM 中的原始掛載點，某些圖形介面在建構時，這個掛載點會被重設或清除。

另外，dijit/_WidgetBase 定義了數個函式，藉以掌控整個圖形介面元件的生命週期，各函式名稱依執行先後次序列示如下：

constructor() // common to all prototypes, called when instantiated
postScript()

postMixInProperties()
buildRendering()
postCreate()

startup()

以下介紹各函式的作用：

constructor(): 是所有類別都具備的函式，在實體化物件時，會被呼叫一次。
postScript()
: 會先呼叫 create() 函式，在 create() 函式中又會依次呼叫 postMixInProperties(), buildRendering(), 及 postCreate() 三個函式。
postMixInPorperties(): 作用在將建立元件時所傳入的屬性參數或函式融入 (mixin) 到既有的屬性及函式中。
buildRendering(): 作用在建構所有介面的 HTML 元素，並設定 domNode 的值，這個函式執行完畢時，圖形介面的 HTML 元素都己建構並設定完畢，但尚未將這些元素加入到 HTML 主文件中。
postCreate(): 這個算是最重要的函式了，在所有的屬性都定義完畢，而且圖形介面相關的 HTML 段落都己建置完成，且加入 HTML 主文件之後，(將 HTML 段落加到 HTML 主文件的動作，在呼叫完 buildRendering() 和呼叫 postCreate() 兩函式之間完成），才會執行這個函式。但要注意的是，如果此元件有子元件時，子元件在此刻未必己經加到主元件中，因此，在此階段還不能進行元件最終尺寸的計算。
startup(): 是第二重要的函式了，在圖形介面相關的 HTML 段落加入主文件後，同時所有的子圖形介面都己完成之後，這個函式才會執行。用程式法建立圖形介面元件時，最好在建立完畢後呼叫 startup() 函式，以確保所有的動作都完成。

另一個非常重要的工具是 dijit/_TamplatedMixin。有些複雜的圖形介面元件，其 HTML 段落非常的複雜，如果要靠 API 一步一步組成最終的 HTML 碼，實在是曠日費時，而且容易出錯。如果能直接寫成最終的 HTML 碼，直接掛載到預定的位置，那就容易多了。而 dijit/_TemplatedMixin 就職司此項工作；它可以讀取一個含有 HTML 段落的檔案，將其內容處理後掛載到 HTML 主文件上的指定掛載點，更進一步的還提供了參數取代的功能，可直接將屬性的定義以參數取代的方式代入 HTML 碼中。

在 HTML 的模版 (template) 中置入 ${propName} 字串，dijit/_TemplatedMixin 便會用名為 propName 的屬性值，來取代這個字串。

在模版中，還可以定義兩個屬性：

data-dojo-attach-point="nameNode": 會在 widget 中建立一個名為 nameNode 的屬性，其值可以直接參考到這個 DOM 元素。
data-dojoattach-event="onClick:handler": 用在將這個 DOM 元素連接到觸發的事件 (click)，並呼叫事件的處理函式 handler()。

除此之外，dijit/_TemplaedMixin 還會為 widget 預設建立兩個屬性值：

domNode:: 這個屬性值可以直接參考到 widget 中最主要的 DOM 元素。
containerNode:: 如果這個 widget 有包含其它的子圖形介面元件，用這個屬性可以直接參考到子元件的 DOM 元素。

如果在 HTML 的模板 (template)中又包含了其它的 dijit，此時，必須另外 require 另一個名為 "dijit/_WidgetsInTemplateMixin" 的模組，同時，用到的 dijit 模組也必須 require 進來。當使用用外部定義的 HTML 檔案時，要藉著 dojo/text 這個插件 (plug-in) 將檔案內容讀進來。

範例

範例中，自定一個圖形介面元件，元件的作用是計數器，每點一下元件，其中的數字便會加 1。這個範例設計的並不是很完善，主要的作用是在解釋如何建立一個自定的圖形介面而己。例如：如果不改變元件的大小，元件只能容納 2 位數。如果改變元件的大小，字形不會跟著變化，位置也不會保持在中間等等。

CSS

<style>
html{
     width:100%;
     height:100%;
}
body {
     margin:0 auto;
     width:1000px;
     height:100%;
     padding-top: 20px;
}
</style>

屬性都在 widget 中定義了，所以 CSS 中沒有什麼要寫的。

HTML

<body class="claro">
My Counter
     
     
</body>

HTML 中要設定一個掛載點，注意 data-dojo-type 屬性的值。

HTML

首先，先根據圖形介面所要求的外觀，建一個新檔，由網頁所在位置起始，檔案的相對路徑位置名為 "js/app/widgets/templates/MyCounter.html"。因為用 SyntaxHighlighter 在處理 ${baseClass} 時會變成 ${baseClass}=""，所以這一段程式碼不用 SyntaxHighLighter 處理。內容如下：


<div ${baseClass}
    data-dojo-attach-point="buttonNode"
    data-dojo-attach-event="onClick:_increment">
    <div
        data-dojo-attach-point="counterNode"
        style="padding:10px 0px; font-size:48px; text-align:center}"></div>
</div>

在模版中，定義了兩個 data-dojo-attach-point，一個名為 "buttonNode"，另一個名為 "counterNode"，這樣在程式中比較好操作。此外，定義了一個 data-attach-event，在元件觸發點按事件時，呼叫 _increment() 處理函式。另有一個屬性變數 ${baseClass} ，但程式中並沒有針對 baseClass 屬性定值，所以並不會在最終的 HTML 裡，產生任何 class="someClasses" 的設定。

其次，建立一個新檔，由網頁所在位置起始，檔案的相對路徑為 "js/app/widgets/MyCounter.js"。

define([
    "dojo/_base/declare",
    "dijit/_WidgetBase",
    "dijit/_TemplatedMixin",
    "dojo/text!./templates/MyCounter.html",
    "dojo/dom-style"
    ],
function(
    declare,
    _WidgetBase,
    _TemplatedMixin,
    template,
    style
){
    return declare("MyCounter", [_WidgetBase, _TemplatedMixin], {
        // counter
        value: 0,
        baseClass:"",
        width:"64px",
        height:"64px",
        backgroundColor:"yellow",
        border:"10px solid blue",
        borderRadius:"10px",
        templateString:template,
        constructor: function(){
            this.inherited(arguments);
        },
        postscript:function(){
            this.inherited(arguments);
        },
        // minin with the parameters passed in
        postMixInProperties:function(){
            this.inherited(arguments);
        },    
        // create the DOM for this widget
        buildRendering: function(){
            this.inherited(arguments);
        },
        // setup the style of DOM node      
        postCreate: function(){
            var bNode = this.buttonNode;
            style.set(bNode, "width", this.width);
            style.set(bNode, "height", this.height);
            style.set(bNode, "background-color", this.backgroundColor);
            style.set(bNode, "border", this.border);
            style.set(bNode, "border-radius", this.borderRadius);
            style.set(bNode, "text-align","center"); 
            var cNode = this.counterNode;
            cNode.innerHTML = 0;
            this.inherited(arguments);
        },
        startup:function(){
         this.inherited(arguments);
        },
        // every time the user clicks the button, increment the counter
        _increment: function(){
            this.counterNode.innerHTML = ++this.value;
        },
        _getValuerAttr:function(){
            return this.value;
        },
        _setValueAttr:function(number){
            this.value = number;
            this.counterNode.innerHTML = this.value;
        }
    });
});

第 5 行用 dojo/text 從相對路徑為名為 "./templates/MyCounter.html" 檔案中讀入 HTML 段落的內容。放在 template 變數中，然後在第 24 行將其設定成 templateString 屬性的值。
第 17~24 行設定各屬性值。
第 41~49 行設定 domNode 的各項外觀的屬性。
第 56~58 行定義事件處理器。
第 59~65 行定義兩個供外部使用的函式，一個用來讀取屬性 value 的值，有就是計數器的值，另一個用來設定。要注意的是這兩個函式的命名方式，都是 _get${PropName}Attr() 及 _set${PropName}Attr()，其中 ${PropName} 字串，用屬性的名稱來取代。

最後，則是主網頁中的內容。

建立好自定的 widget 之後，用法就和 dijit 中的圖形介面元件的用法一樣，唯一要注意的是元件的路徑名，必須正確。
第 18~25 行在主控台中印出各個和 DOM node 有關之屬性的值，記得到主控台去檢查印出值，必詳細思考一下。建立 widget 的步驟還算複雜，最好多多修改範例程式，並檢查結果，以充分瞭解其中的細節。

熊伯的外接硬碟

2015年10月28日星期三