在ASP.NET Atlas中建立自訂的Transformer

English Version: http://dflying.dflying.net/1/archive/110_build_your_own_transformers_in_aspnet_atlas.html

ASP.NET Atlas中的綁定（binding）是一種將兩個對象串連起來的強大方法。（您可以參考http://dflying.cnblogs.com/archive/2006/04/04/366900.html得到更多關於綁定的資訊。）Atlas綁定會自動將來源物件上變化了的屬性應用到目標對象的指定屬性上。但有時候您會希望在應用到目標對象之前對這個屬性進行一些修改。比如，當顯示一個有索引的列表時，您可能希望這個索引從1開始遞增，而不是JavaScript中預設的從0開始。這時候您就需要使用Atlas Transformer了。Atlas中的Transformer是一種類似管道的東西，它將插入到由來源物件的屬性向目標對象的屬性賦值的過程中，以期對將要賦值的屬性進行必要的過濾/裝飾/轉換（在這裡是將源屬性加1），然後再賦值給目標屬性。

Atlas提供一些內建的transformer，例如Add，Multiply，Compare等。然而在實際開發中，大多數情況下我們都需要定義自己的transformer。讓我們通過開發一個CustomBooleanTransformer的例子來熟悉如何書寫自訂的transformer。

CustomBooleanTransformer用來將布爾值轉換為我們自訂的格式，例如Yes/No或者Completed/InProgress。如果我們選擇使用綁定來將一個布爾值顯示給使用者，那麼這個transformer將會是十分有用的，它帶給使用者更加友好的使用者體驗。

大體上，建立一個transformer將有如下四個步驟：

1. 取得從源綁定對象中傳入的將被轉換的值。這裡我們首先調用get_value()取得傳入的值，並將其轉換為布爾型。
2. 取得transformer的參數。這裡的參數是一個可以被逗號（，）分成兩部分的字串。布爾值true將被轉換為第一部分，false將被轉換為第二部分。如果傳入的參數為空白，則用預設的字串true/false代替。
3. 進行轉換。在這個步驟應當通過您自己的邏輯把傳入的值轉換成將要傳出的值（一般會用到上一步驟中取得的transformer的參數）。這裡我們首先用逗號（，）將參數分成兩個部分，然後用第一部分代替true，用第二部分代替false。如果參數不能被分成兩個部分，那麼使用true/false代替。
4. 將轉換後的值輸出，調用方法set_value()來實現。

下面是CustomBooleanTransformer的JavaScript代碼，將其儲存為CustomBooleanTransformer.js。

Sys.BindingBase.Transformers.CustomBoolean = function(sender, eventArgs) {
    // step 1, get input value.
    var value = eventArgs.get_value();
    if (typeof(value) != 'boolean') {
        value = Boolean.parse(value);
    }
    
    // step 2, get arguments will be used in trasforming.
    var customString = eventArgs.get_transformerArgument();
    if (customString == null || customString == '') {
        customString = 'true,false';
    }
    
    // step 3, do the transformation.
    var customValues = customString.split(',');
    if (customValues.length != 2)
    {
        customValues[0] = 'true';
        customValues[1] = 'false';
    }
    var newValue = value ? customValues[0] : customValues[1];
    
    // step 4, set the transformed value as output.
    eventArgs.set_value(newValue);
}

 

OK，現在讓我們測試一下這個CustomBooleanTransformer。在頁面上添加一個checkbox和一個textbox並將他們綁定起來。當checkbox被選中/取消選中時，textbox中會顯示相應的被轉換後的布爾值。

下面是ASPX檔案中的HTML定義。不要忘記在ScriptManager中添加對CustomBooleanTransformer.js檔案的引用。

<atlas:ScriptManager ID="sm1" runat="server">
    <Scripts>
        <atlas:ScriptReference Path="CustomBooleanTransformer.js" />
    </Scripts>
</atlas:ScriptManager>
<input id="myCheckbox" type="checkbox" />
<input id="myTextbox" type="text" />

 

下面是Atlas指令碼定義。這裡指定tranformerArgument為‘Yes,No’，以期讓布爾值true轉化為Yes，false轉化為No。

<page xmlns:script="http://schemas.microsoft.com/xml-script/2005">
    <references>
    </references>
    <components>
        <checkBox id="myCheckbox" />
        <textBox id="myTextBox">
            <bindings>
                <binding dataContext="myCheckbox" dataPath="checked"  
                property="text" transform="CustomBoolean" transformerArgument="Yes,No" />
            </bindings>
        </textBox>
    </components>
</page>

瀏覽器中的實際結果：