repo_zf1/documentation/manual/zh/module_specs/Zend_Dojo-View-Helpers.xml

<sect2 id="zend.dojo.view.dijit">
    <title>Dijit-Specific 视图助手 </title>

    <para>
        引用一下 Dojo 手册：“Dijit 是基于 dojo 之上的一个小部件系统”，Dijit 有
        许多布局和表单小部件，用来提供访问、本地化和标准化（和可主题化）的观感。
    </para>

    <para>
        Zend Framework 带有许多视图助手让你在视图脚本里解析和使用 dijits。有三个基本类型：
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <emphasis>布局容器</emphasis>:
                这些设计上在视图脚本理使用或由表单装饰器用于表单、子表单和显示组。
                它们封装了 dijit.layout 提供的各种类。每个 dijit 布局视图助手有下面的参数：
            </para>

            <itemizedlist>
                <listitem><para>
                        <code>$id</code>: 容器名或 DOM ID。
                </para></listitem>

                <listitem><para>
                        <code>$content</code>: 在布局容器里封装的内容。
                </para></listitem>

                <listitem><para>
                        <code>$params</code> (optional): dijit-specific 参数。
                        基本上是任何非 HTML 属性，可用于配置 dijit 布局容器。
                </para></listitem>

                <listitem><para>
                        <code>$attribs</code> （可选）：任何用于解析容器 div 的附加的 HTML 属性。
                        如果在这个数组里传递了键 'id'，它将被用于表单元素 DOM id，并且 <code>$id</code>
                        将用于它的名字。
                </para></listitem>
            </itemizedlist>

            <para>
                如果不传递参数给 dijit 布局视图助手，那么助手将返回自己。
                它允许你抓取内容，通常是更容易的传递内容给布局容器的方法。
                本章的后面将用范例来示范这个功能。
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>Form Dijit</emphasis>: dijit.form.Form dijit，虽然对于使用 dijit
                表单元素不是完全必要，但是它可以确保如果提交没有根据客户端校验而校验的表单时，
                提交就被终止并且产生校验错误消息。该表单 dijit 视图助手可带有下列参数：
            </para>

            <itemizedlist>
                <listitem><para>
                        <code>$id</code>: 容器名或 DOM ID。
                </para></listitem>

                <listitem><para>
                        <code>$attribs</code> （可选）：任何用于解析容器 div 的附加的 HTML 属性。
                </para></listitem>

                <listitem><para>
                        <code>$content</code> （可选）：要封装到表单的内容。如果没有，将使用空的字符串。
                </para></listitem>
            </itemizedlist>

            <para>
                为了和标准的 <code>form()</code> 视图助手保持兼容，参数顺序和其它 dijit 有些不同。
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis> 表单元素 </emphasis>：设计上和 <code>Zend_Form</code> 一起使用，但也
                可以在视图脚本中独立使用。每个 dijit 元素视图助手可以使用下列参数：
            </para>

            <itemizedlist>
                <listitem><para>
                        <code>$id</code>: 元素名或 DOM ID。
                </para></listitem>

                <listitem><para>
                        <code>$value</code> （可选）：元素的当前值。
                </para></listitem>

                <listitem><para>
                        <code>$params</code> （可选）： dijit-specific 参数。
                        基本上是任何用于配置 dijit 的非 HTML 属性。
                </para></listitem>

                <listitem><para>
                        <code>$attribs</code> （可选）：任何用于解析 dijit的附加的 HTML 属性。
                        如果键 'id' 在这个数组中传递，它将被用于表单元素的 DOM id，
                        并且 <code>$id</code> 将被用于它的名字。
                </para></listitem>
            </itemizedlist>

            <para>
                一些元素要求更多的参数，将在个别元素助手的描述中注明。
            </para>
        </listitem>
    </itemizedlist>

    <para>
        为了使用这些视图助手，你需要用视图对象来注册路径给 dojo 视图助手。
    </para>

    <example id="zend.dojo.view.dijit.prefixpath">
        <title> 注册 Dojo 视图助手前缀路径 </title>

        <programlisting role="php"><![CDATA[
$view->addHelperPath('Zend/Dojo/View/Helper', 'Zend_Dojo_View_Helper');
]]></programlisting>
    </example>

    <sect3 id="zend.dojo.view.dijit.layout">
        <title>Dijit 布局元素 </title>

        <para>
            dijit.layout 元素家族用来生成定制的、可预计的布局。任何关于用法的问题
            <ulink
                url="http://dojotoolkit.org/book/dojo-book-0-9/part-2-dijit/layout">
            请阅读 Dojo 手册</ulink>。
        </para>

        <para>
            所有的 dijit 布局元素都有签名 <code>string ($id = null, $content = '', array $params =
                array(), array $attribs = array())</code>。
            对于所有情况，如果不传递参数，就返回助手对象自己。
            访问 <code>captureStart()</code> 和 <code>captureEnd()</code> 方法，它让你
            抓取内容而不是传递它给布局容器。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>AccordionContainer</emphasis>：dijit.layout.AccordionContainer。
                    垂直堆放所有的 pane ，点击一个 pane 的 titlebar 就会展开并显示特定的 pane。
                </para>

                <programlisting role="php"><![CDATA[
<?= $view->accordionContainer(
    'foo',
    $content,
    array(
        'duration' => 200,
    ),
    array(
        'style' => 'width: 200px; height: 300px;',
    ),
); ?>
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>AccordionPane</emphasis>: dijit.layout.AccordionPane.
                    在 AccordionContainer 内使用。
                </para>

                <programlisting role="php"><![CDATA[
<?= $view->accordionPane(
    'foo',
    $content,
    array(
        'title' => 'Pane Title',
    ),
    array(
        'style' => 'background-color: lightgray;',
    ),
); ?>
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>BorderContainer</emphasis>：dijit.layout.BorderContainer。
                    用象传统程序中的可改变尺寸的 pane 来完成布局。
                </para>

                <programlisting role="php"><![CDATA[
<?= $view->borderContainer(
    'foo',
    $content,
    array(
        'design' => 'headline',
    ),
    array(
        'style' => 'width: 100%; height: 100%',
    ),
); ?>
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>ContentPane</emphasis>: dijit.layout.ContentPane。
                    用在除了 AccordionContainer 以外的任何容器内部。
                </para>

                <programlisting role="php"><![CDATA[
<?= $view->contentPane(
    'foo',
    $content,
    array(
        'title'  => 'Pane Title',
        'region' => 'left',
    ),
    array(
        'style' => 'width: 120px; background-color: lightgray;',
    ),
); ?>
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>SplitContainer</emphasis>：dijit.layout.SplitContainer。
                    允许可变尺寸的内容 pane；在 Dojo 里废除转而使用 BorderContainer。
                </para>

                <programlisting role="php"><![CDATA[
<?= $view->splitContainer(
    'foo',
    $content,
    array(
        'orientation'  => 'horizontal',
        'sizerWidth'   => 7,
        'activeSizing' => true,
    ),
    array(
        'style' => 'width: 400px; height: 500px;',
    ),
); ?>
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>StackContainer</emphasis>：dijit.layout.StackContainer。
                    所有在 StackContainer 里的 pane 放在一个堆栈里，生成按钮或功能一次显示一个。
                </para>

                <programlisting role="php"><![CDATA[
<?= $view->stackContainer(
    'foo',
    $content,
    array(),
    array(
        'style' => 'width: 400px; height: 500px; border: 1px;',
    ),
); ?>
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>TabContainer</emphasis>：dijit.layout.TabContainer。
                    所有在 TabContainer 里的 pane 放在一个堆栈里，并带有 tab 的位置，用于切换。
                </para>

                <programlisting role="php"><![CDATA[
<?= $view->stackContainer(
    'foo',
    $content,
    array(),
    array(
        'style' => 'width: 400px; height: 500px; border: 1px;',
    ),
); ?>
]]></programlisting>
            </listitem>
        </itemizedlist>

        <para>
            下列的抓取方法对所有的布局容器都可用：
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>captureStart($id, array $params = array(), array $attribs = array())</code>：
                    开始抓取内容到容器。<code>$params</code> 是和容器一起使用的 dijit 参数，
                    <code>$attribs</code> 指的是任何一般的 HTML 属性。
                </para>

                <para>
                    <emphasis> 只要 ids 没有重复 </emphasis>，容器在抓取的时候可以嵌套。
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>captureEnd($id)</code>：
                    完成抓取内容到容器。<code>$id</code> 是指先前和  <code>captureStart()</code>
                    调用一起使用的 id。返回一个字符串表示容器和它的内容，就好像传递内容给助手自己。
                </para>
            </listitem>
        </itemizedlist>

        <example id="zend.dojo.view.dijit.layout.borderexample">
            <title>BorderContainer 布局 dijit 范例</title>

            <para>
                BorderContainers, 特别是当和抓取内容耦合时，对复杂的布局效果特别有用。
            </para>

            <programlisting role="php"><![CDATA[
$view->borderContainer()->captureStart('masterLayout', array('design' => 'headline'));

echo $view->contentPane(
    'menuPane',
    'This is the menu pane',
    array('region' => 'top'),
    array('style' => 'background-color: darkblue;')
);

echo  $view->contentPane(
    'navPane',
    'This is the navigation pane',
    array('region' => 'left'),
    array('style' => 'width: 200px; background-color: lightblue;')
);

echo $view->contentPane(
    'mainPane',
    'This is the main content pane area',
    array('region' => 'center'),
    array('style' => 'background-color: white;')
);

echo $view->contentPane(
    'statusPane',
    'Status area',
    array('region' => 'bottom'),
    array('style' => 'background-color: lightgray;')
);

echo $view->borderContainer()->captureEnd('masterLayout');
]]></programlisting>
        </example>
    </sect3>

    <sect3 id="zend.dojo.view.dijit.form">
        <title>Dijit 表单元素 </title>

        <para>
            Dojo 的表单校验和输入 dijit 在 dijit.form 树中。
            更多关于这些元素的一般用法和可接受的参数，请
            <ulink
                url="http://dojotoolkit.org/book/dojo-book-0-9/part-2-dijit/form-validation-specialized-input">访问
                dijit.form 文档</ulink>.
        </para>

        <para>
            下列 dijit 表单元素在 Zend Framework 里可用。
            除非注明，都有签名 <code>string ($id,
                $value = '', array $params = array(), array $attribs =
                array())</code>.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>Button</emphasis>: dijit.form.Button. 显示一个表单按钮
                </para>

                <programlisting role="php"><![CDATA[
<?= $view->button(
    'foo',
    'Show Me!',
    array('iconClass' => 'myButtons'),
); ?>
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>CheckBox</emphasis>：dijit.form.CheckBox.
                    显示一个 checkbox。接受可选的第五个参数，<code>$checkedOptions</code> 数组，
                    包含：
                </para>

                <itemizedlist>
                    <listitem><para>
                            按顺序带两个值的索引数组，一个选中的值和一个未选中的值；或者
                    </para></listitem>

                    <listitem><para>
                            带键 'checkedValue' 和 'unCheckedValue'的联合数组。
                    </para></listitem>
                </itemizedlist>

                <para>
                    如果没有提供 <code>$checkedOptions</code> 就假定为 1 和 0 。
                </para>

                <programlisting role="php"><![CDATA[
<?= $view->checkBox(
    'foo',
    'bar',
    array(),
    array(),
    array('checkedValue' => 'foo', 'unCheckedValue' => 'bar')
); ?>
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>ComboBox</emphasis>：dijit.layout.ComboBox.
                    组合框是一个混合体，包括选择框和带有自动完成的文字框。
                    关键是在列表里没有相应的选项的时候可以手工输入，而且是有效的。
                    它接受可选的第五个参数：联合数组 <code>$options</code>；如果提供
                    了该参数，ComboBox 就当作 <code>select</code> 被解析。也要注意
                    <code>$options</code> 数组的 <emphasis>标签值</emphasis> 在表单中返回，
                    而不选项值自己。
                </para>

                <para>
                    另外，也可以传递关于和元素一起使用的 dojo.data 数据存储的信息。
                    如果提供该参数，ComboBox 就当作 <code>input</code> 被解析，
                    并且将通过那个数据存储来取出它的选项。
                </para>

                <para>
                    为了指定数据存储，请提供下列 <code>$params</code> 键组合之一：
                </para>

                <itemizedlist>
                    <listitem>
                        <para>
                            键 'store'，带有一个数组值；数组应包含下列键：
                        </para>

                        <itemizedlist>
                            <listitem><para>
                                <emphasis>store</emphasis>：表示数据存储的 javascript 变量名
                                （this could be the name you would like for it to use）。
                            </para></listitem>

                            <listitem><para>
                                <emphasis>type</emphasis>：数据存储类型；例如：'dojo.data.ItemFileReadStore'。
                            </para></listitem>

                            <listitem><para>
                                <emphasis>params</emphasis> （可选）：一个键/值对的联合数组，用来配置数据存储。
                                'url' 参数是个典型的例子。
                            </para></listitem>
                        </itemizedlist>
                    </listitem>

                    <listitem>
                        <para>
                            键：
                        </para>

                        <itemizedlist>
                            <listitem><para>
                                <emphasis>store</emphasis>：表示数据存储名的字符串。
                            </para></listitem>

                            <listitem><para>
                                <emphasis>storeType</emphasis>：表示数据存储 dojo.data 类型的字符传（例如 'dojo.data.ItemFileReadStore'）。
                            </para></listitem>

                            <listitem><para>
                                <emphasis>storeParams</emphasis>：一个键/值对联合数组，用于配置数据存储。
                            </para></listitem>
                        </itemizedlist>
                    </listitem>
                </itemizedlist>

                <programlisting role="php"><![CDATA[
// As a select element:
echo $view->comboBox(
    'foo',
    'bar',
    array(
        'autocomplete' => false,
    ),
    array(),
    array(
        'foo' => 'Foo',
        'bar' => 'Bar',
        'baz' => 'Baz',
    )
);

// As a dojo.data-enabled element:
echo $view->comboBox(
    'foo',
    'bar',
    array(
        'autocomplete' => false,
        'store'        => 'stateStore',
        'storeType'    => 'dojo.data.ItemFileReadStore',
        'storeParams'  => array('url' => '/js/states.json'),
    ),
);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>CurrencyTextBox</emphasis>：dijit.form.CurrencyTextBox。
                    从 ValidationTextBox 继承，并提供货币的客户端校验。
                    它期望 dijit 参数 'currency' 的值是适当的三字符货币代码。
                    可以为 ValidationTextBox 和 TextBox 指定任何有效的 dijit 参数。
                </para>

                <programlisting role="php"><![CDATA[
echo $view->currencyTextBox(
    'foo',
    '$25.00',
    array('currency' => 'USD'),
    array('maxlength' => 20)
);
]]></programlisting>

                <note>
                    <title>Issues with Builds</title>

                    <para>
                        目前有这些 <ulink
                            url="http://trac.dojotoolkit.org/ticket/7183">
                        和 build 层一起使用的 CurrencyTextBox 的已知问题
                        </ulink>.
                        一个解决办法是确保文档的 Content-Type http-equiv meta tag 把字符集设置为 utf-8，
                        可通过调用下列方法来完成：
                    </para>

                    <programlisting role="php"><![CDATA[
$view->headMeta()->appendHttpEquiv('Content-Type', 'text/html; charset=utf-8');
?>]]></programlisting>

                    <para>
                        这当然意味着你需要确保 <code>headMeta()</code> 占位符在布局脚本中。
                    </para>
                </note>
            </listitem>

            <listitem>
                <para>
                    <emphasis>DateTextBox</emphasis>：dijit.form.DateTextBox.
                    从 ValidationTextBox 继承，提供客户端的日期校验和下拉式日历。
                    你可以指定任何 dijit 可用的参数给 ValidationTextBox 或 TextBox。
                </para>

                <programlisting role="php"><![CDATA[
echo $view->dateTextBox(
    'foo',
    '2008-07-11',
    array('required' => true)
);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>FilteringSelect</emphasis>：dijit.form.FilteringSelect。
                    和 ComboBox 类似，这是个选择/文字混合体，它可以从提供的选项列表
                    里读取或者从 dojo.data 数据存储里抓取。和 ComboBox 不一样的地方是
                    FilteringSelect 不允许输入不在列表里的选项。另外，它的操作和标准选择
                    一样，从选项值里选择而不是从标签里选择，当表单提交时返回它们。
                </para>

                <para>
                    请参考上述关于 ComboBox 范例和定义数据存储的可用选项的信息。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>HorizontalSlider</emphasis> 和
                    <emphasis>VerticalSlider</emphasis>：
                    dijit.form.HorizontalSlider 和 dijit.form.VerticalSlider.
                    滑尺是 UI 小部件，用来在给定范围内选择数值的，这两个一个是水平的，一个是垂直的。
                </para>

                <para>
                    至少，它们需要 dijit 参数
                    'minimum'、 'maximum' 和 'discreteValues'，来定义值的范围。
                    其它通用的选项有：
                </para>

                <itemizedlist>
                    <listitem><para>
                        'intermediateChanges' 用来表明当 handle 被拖的时候是否需要发出 onChange 事件。
                    </para></listitem>

                    <listitem><para>
                        'clickSelect' 用来允许在滑尺上点击来设置其值。
                    </para></listitem>

                    <listitem><para>
                        'pageIncrement' 通过 pageUp 和 pageDown 来增加/减少值。
                    </para></listitem>

                    <listitem><para>
                        'showButtons' 设置来允许在滑尺的一端显示按钮来操作数值。
                    </para></listitem>
                </itemizedlist>

                <para>
                    Zend Framework 实现生成一个隐藏的元素来存储滑尺的数值。
                </para>

                <para>
                    你可以可选地为滑尺显示尺子或标签，可通过分配一个或多个 dijit 参数
                    'topDecoration' 和/或 'bottomDecoration'(水平滑尺） 或 'leftDecoration' 和/或
                    'rightDecoration' （垂直滑尺）来完成。它们有下列选项：
                </para>

                <itemizedlist>
                    <listitem><para>
                        <emphasis>container</emphasis>：容器名称。
                    </para></listitem>

                    <listitem><para>
                        <emphasis>labels</emphasis> （可选）：标签数组。
                        在滑尺的一端使用空字符串只为内部值提供标签。
                        当指定一个 'Labels' dijit 变量时必需。
                    </para></listitem>

                    <listitem><para>
                        <emphasis>dijit</emphasis> （可选）：
                        HorizontalRule、HorizontalRuleLabels、 VerticalRule 或
                        VerticalRuleLabels 中的一个，缺省为尺子 dijits 之一。
                    </para></listitem>

                    <listitem>
                        <para>
                            <emphasis>params</emphasis> （可选）：
                            配置尺子 dijit 的 dijit 参数，参数规范包括：
                        </para>

                        <itemizedlist>
                            <listitem><para>
                                <emphasis>container</emphasis> （可选）：
                                尺子容器的属性和参数的数组。
                            </para></listitem>

                            <listitem><para>
                                <emphasis>labels</emphasis> （可选）：
                                标签列表容器的属性和参数的数组。
                            </para></listitem>
                        </itemizedlist>
                    </listitem>

                    <listitem><para>
                        <emphasis>attribs</emphasis> （可选）：
                        和尺子/标签一起使用的 HTML 属性，遵循  <code>params</code> 选项格式并
                        且是一个带有键 'container' 和 'labels'  的联合数组。
                    </para></listitem>
                </itemizedlist>

                <programlisting role="php"><![CDATA[
echo $view->horizontalSlider(
    'foo',
    1,
    array(
        'minimum'             => -10,
        'maximum'             => 10,
        'discreteValues'      => 11,
        'intermediateChanges' => true,
        'showButtons'         => true,
        'topDecoration'       => array(
            'container' => 'topContainer'
            'dijit'     => 'HorizontalRuleLabels',
            'labels'    => array(
                ' ',
                '20%',
                '40%',
                '60%',
                '80%',
                ' ',
            ),
            'params' => array(
                'container' => array(
                    'style' => 'height:1.2em; font-size=75%;color:gray;',
                ),
                'labels' => array(
                    'style' => 'height:1em; font-size=75%;color:gray;',
                ),
            ),
        ),
        'bottomDecoration'    => array(
            'container' => 'bottomContainer'
            'labels'    => array(
                '0%',
                '50%',
                '100%',
            ),
            'params' => array(
                'container' => array(
                    'style' => 'height:1.2em; font-size=75%;color:gray;',
                ),
                'labels' => array(
                    'style' => 'height:1em; font-size=75%;color:gray;',
                ),
            ),
        ),
    )
);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>NumberSpinner</emphasis>：dijit.form.NumberSpinner。
                    数字输入文本框，按钮用来增减值。
                </para>

                <para>
                    期望用于 dijit 参数 'constraints' 的联合数值或者键 'min'、'max' 和 'places'
                    （这些也期望 constraints 参数的条目）。
                    'places' 可用于指示微调数的增加和减少的数值。
                </para>

                <programlisting role="php"><![CDATA[
echo $view->numberSpinner(
    'foo',
    5,
    array(
        'min'    => -10,
        'max'    => 10,
        'places' => 2,
    ),
    array(
        'maxlenth' => 3,
    )
);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>NumberTextBox</emphasis>：dijit.form.NumberTextBox。
                    NumberTextBox 可选地依靠给定的限制以本地化方式格式化和显示数字条目，同时也校验数字条目。
                </para>

                <programlisting role="php"><![CDATA[
echo $view->numberTextBox(
    'foo',
    5,
    array(
        'places' => 4,
        'type'   => 'percent',
    ),
    array(
        'maxlength' => 20,
    )
);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>PasswordTextBox</emphasis>：
                    和密码输入相关的 dijit.form.ValidationTextBox。
                    PasswordTextBox 生成密码输入，并和当前的 dijit 主题匹配，同时也做客户端校验。
                </para>

                <programlisting role="php"><![CDATA[
echo $view->passwordTextBox(
    'foo',
    '',
    array(
        'required' => true,
    ),
    array(
        'maxlength' => 20,
    )
);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>RadioButton</emphasis>：dijit.form.RadioButton。
                     一组选项，但只能选一个，除了视觉上和其它 dijits 保持一致，
                     其它方面都和普通的单选（radio，也叫无线电按钮）元素一样。
                </para>

                <para>
                    RadioButton 接受可选的第五个参数，<code>$options</code>，
                    是个联合数组，值/标签对用作radio选项。
                    你可以以 <code>$attribs</code> 键 <code>options</code> 来传递。
                </para>

                <programlisting role="php"><![CDATA[
echo $view->radioButton(
    'foo',
    'bar',
    array(),
    array(),
    array(
        'foo' => 'Foo',
        'bar' => 'Bar',
        'baz' => 'Baz',
    )
);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>SubmitButton</emphasis>：和提交元素相关的 dijit.form.Button。
                     参见按钮视图助手有更多的细节。主要的区别是这个按钮可以提交一个表单。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Textarea</emphasis>：dijit.form.Textarea.
                    除了有很多行以外，和普通的文本区域一样，它们按照用户类型来扩展。
                    宽度通过风格来设定。
                </para>

                <programlisting role="php"><![CDATA[
echo $view->textarea(
    'foo',
    'Start writing here...',
    array(),
    array('style' => 'width: 300px;')
);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>TextBox</emphasis>：dijit.form.TextBox。
                    该元素主要用来在不同的 dijit 元素之间提供一个通用的外观，
                    并对其它 TextBox 派生的类 （ValidationTextBox、 NumberTextBox、 CurrencyTextBox、
                    DateTextBox 和 TimeTextBox）提供基本功能。
                </para>

                <para>
                    普通的 dijit 参数标志包括 'lowercase' （转换成小写）、
                    'uppercase' （转换成大写）、
                    'propercase' （转换成合适的大小写）和 trim （修剪引导和拖尾的空白字符）；
                    它们都接受布尔值。另外，你可以指定参数 'size' 和 'maxLength'。
                </para>

                <programlisting role="php"><![CDATA[
echo $view->textBox(
    'foo',
    'some text',
    array(
        'trim'       => true,
        'propercase' => true,
        'maxLength'  => 20,
    ),
    array(
        'size' => 20,
    )
);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>TimeTextBox</emphasis>： dijit.form.TimeTextBox。
                    也包含在 TextBox 家族，TimeTextBox 提供一个下拉式时间选择器。
                    Dijit 参数让你指定可用的时间增量以及有效的时间的可见范围。
                </para>

                <programlisting role="php"><![CDATA[
echo $view->timeTextBox(
    'foo',
    '',
    array(
        'am.pm'            => true,
        'visibleIncrement' => 'T00:05:00', // 5-minute increments
        'visibleRange'     => 'T02:00:00', // show 2 hours of increments
    ),
    array(
        'size' => 20,
    )
);

]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>ValidationTextBox</emphasis>：dijit.form.ValidateTextBox。
                    为文本元素提供客户端校验。从 TextBox 继承。
                </para>

                <para>
                    普通的 dijit 参数包括：
                </para>

                <itemizedlist>
                    <listitem><para>
                        <emphasis>invalidMessage</emphasis>：当检测到一个无效的输入，就显示一条消息。
                    </para></listitem>

                    <listitem><para>
                        <emphasis>promptMessage</emphasis>：工具提示帮助信息。
                    </para></listitem>

                    <listitem><para>
                        <emphasis>regExp</emphasis>：用于校验文本的正则表达式，不需要边界记号。
                    </para></listitem>

                    <listitem><para>
                        <emphasis>required</emphasis>：确定元素是否必需。如果需要就把元素嵌入
                         dijit.form.Form，它将被标记为无效并防止提交。
                    </para></listitem>
                </itemizedlist>

                <programlisting role="php"><![CDATA[
echo $view->validationTextBox(
    'foo',
    '',
    array(
        'required' => true,
        'regExp'   => '[\w]+',
        'invalidMessage' => 'No spaces or non-word characters allowed',
        'promptMessage'  => 'Single word consisting of alphanumeric characters and underscores only',
    ),
    array(
        'maxlength' => 20,
    )
);
]]></programlisting>
            </listitem>
        </itemizedlist>
    </sect3>
</sect2>
<!--
vim:se ts=4 sw=4 et:
-->