# Dijit-Specific 视图助手

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

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

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

  - `$id`: 容器名或 DOM ID。

  - `$content`: 在布局容器里封装的内容。

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

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

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

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

  - `$id`: 容器名或 DOM ID。

  - `$attribs` （可选）：任何用于解析容器 div 的附加的 HTML 属性。

  - `$content` （可选）：要封装到表单的内容。如果没有，将使用空的字符串。

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

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

  - `$id`: 元素名或 DOM ID。

  - `$value` （可选）：元素的当前值。

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

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

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

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

## 注册 Dojo 视图助手前缀路径

    $view->addHelperPath('Zend/Dojo/View/Helper', 'Zend_Dojo_View_Helper');

## Dijit 布局元素

dijit.layout 元素家族用来生成定制的、可预计的布局。任何关于用法的问题 请阅读 Dojo 手册。

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

- AccordionContainer：dijit.layout.AccordionContainer。 垂直堆放所有的 pane ，点击一个 pane 的 titlebar 就会展开并显示特定的 pane。

      <?= $view->accordionContainer(
          'foo',
          $content,
          array(
              'duration' => 200,
          ),
          array(
              'style' => 'width: 200px; height: 300px;',
          ),
      ); ?>

- AccordionPane: dijit.layout.AccordionPane. 在 AccordionContainer 内使用。

      <?= $view->accordionPane(
          'foo',
          $content,
          array(
              'title' => 'Pane Title',
          ),
          array(
              'style' => 'background-color: lightgray;',
          ),
      ); ?>

- BorderContainer：dijit.layout.BorderContainer。 用象传统程序中的可改变尺寸的 pane 来完成布局。

      <?= $view->borderContainer(
          'foo',
          $content,
          array(
              'design' => 'headline',
          ),
          array(
              'style' => 'width: 100%; height: 100%',
          ),
      ); ?>

- ContentPane: dijit.layout.ContentPane。 用在除了 AccordionContainer 以外的任何容器内部。

      <?= $view->contentPane(
          'foo',
          $content,
          array(
              'title'  => 'Pane Title',
              'region' => 'left',
          ),
          array(
              'style' => 'width: 120px; background-color: lightgray;',
          ),
      ); ?>

- SplitContainer：dijit.layout.SplitContainer。 允许可变尺寸的内容 pane；在 Dojo 里废除转而使用 BorderContainer。

      <?= $view->splitContainer(
          'foo',
          $content,
          array(
              'orientation'  => 'horizontal',
              'sizerWidth'   => 7,
              'activeSizing' => true,
          ),
          array(
              'style' => 'width: 400px; height: 500px;',
          ),
      ); ?>

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

      <?= $view->stackContainer(
          'foo',
          $content,
          array(),
          array(
              'style' => 'width: 400px; height: 500px; border: 1px;',
          ),
      ); ?>

- TabContainer：dijit.layout.TabContainer。 所有在 TabContainer 里的 pane 放在一个堆栈里，并带有 tab 的位置，用于切换。

      <?= $view->stackContainer(
          'foo',
          $content,
          array(),
          array(
              'style' => 'width: 400px; height: 500px; border: 1px;',
          ),
      ); ?>

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

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

  只要 ids 没有重复 ，容器在抓取的时候可以嵌套。

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

### BorderContainer 布局 dijit 范例

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

    $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');

## Dijit 表单元素

Dojo 的表单校验和输入 dijit 在 dijit.form 树中。 更多关于这些元素的一般用法和可接受的参数，请 访问 dijit.form 文档.

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

- Button: dijit.form.Button. 显示一个表单按钮

      <?= $view->button(
          'foo',
          'Show Me!',
          array('iconClass' => 'myButtons'),
      ); ?>

- CheckBox：dijit.form.CheckBox. 显示一个 checkbox。接受可选的第五个参数，`$checkedOptions` 数组， 包含：

  - 按顺序带两个值的索引数组，一个选中的值和一个未选中的值；或者

  - 带键 'checkedValue' 和 'unCheckedValue'的联合数组。

  如果没有提供 `$checkedOptions` 就假定为 1 和 0 。

      <?= $view->checkBox(
          'foo',
          'bar',
          array(),
          array(),
          array('checkedValue' => 'foo', 'unCheckedValue' => 'bar')
      ); ?>

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

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

  为了指定数据存储，请提供下列 `$params` 键组合之一：

  - 键 'store'，带有一个数组值；数组应包含下列键：

    - store：表示数据存储的 javascript 变量名 （this could be the name you would like for it to use）。

    - type：数据存储类型；例如：'dojo.data.ItemFileReadStore'。

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

  - 键：

    - store：表示数据存储名的字符串。

    - storeType：表示数据存储 dojo.data 类型的字符传（例如 'dojo.data.ItemFileReadStore'）。

    - storeParams：一个键/值对联合数组，用于配置数据存储。

      // 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'),
          ),
      );

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

      echo $view->currencyTextBox(
          'foo',
          '$25.00',
          array('currency' => 'USD'),
          array('maxlength' => 20)
      );

  ### Issues with Builds

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

      $view->headMeta()->appendHttpEquiv('Content-Type', 'text/html; charset=utf-8');
      ?>

  这当然意味着你需要确保 `headMeta()` 占位符在布局脚本中。

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

      echo $view->dateTextBox(
          'foo',
          '2008-07-11',
          array('required' => true)
      );

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

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

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

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

  - 'intermediateChanges' 用来表明当 handle 被拖的时候是否需要发出 onChange 事件。

  - 'clickSelect' 用来允许在滑尺上点击来设置其值。

  - 'pageIncrement' 通过 pageUp 和 pageDown 来增加/减少值。

  - 'showButtons' 设置来允许在滑尺的一端显示按钮来操作数值。

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

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

  - container：容器名称。

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

  - dijit （可选）： HorizontalRule、HorizontalRuleLabels、 VerticalRule 或 VerticalRuleLabels 中的一个，缺省为尺子 dijits 之一。

  - params （可选）： 配置尺子 dijit 的 dijit 参数，参数规范包括：

    - container （可选）： 尺子容器的属性和参数的数组。

    - labels （可选）： 标签列表容器的属性和参数的数组。

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

      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;',
                      ),
                  ),
              ),
          )
      );

- NumberSpinner：dijit.form.NumberSpinner。 数字输入文本框，按钮用来增减值。

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

      echo $view->numberSpinner(
          'foo',
          5,
          array(
              'min'    => -10,
              'max'    => 10,
              'places' => 2,
          ),
          array(
              'maxlenth' => 3,
          )
      );

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

      echo $view->numberTextBox(
          'foo',
          5,
          array(
              'places' => 4,
              'type'   => 'percent',
          ),
          array(
              'maxlength' => 20,
          )
      );

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

      echo $view->passwordTextBox(
          'foo',
          '',
          array(
              'required' => true,
          ),
          array(
              'maxlength' => 20,
          )
      );

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

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

      echo $view->radioButton(
          'foo',
          'bar',
          array(),
          array(),
          array(
              'foo' => 'Foo',
              'bar' => 'Bar',
              'baz' => 'Baz',
          )
      );

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

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

      echo $view->textarea(
          'foo',
          'Start writing here...',
          array(),
          array('style' => 'width: 300px;')
      );

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

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

      echo $view->textBox(
          'foo',
          'some text',
          array(
              'trim'       => true,
              'propercase' => true,
              'maxLength'  => 20,
          ),
          array(
              'size' => 20,
          )
      );

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

      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,
          )
      );

- ValidationTextBox：dijit.form.ValidateTextBox。 为文本元素提供客户端校验。从 TextBox 继承。

  普通的 dijit 参数包括：

  - invalidMessage：当检测到一个无效的输入，就显示一条消息。

  - promptMessage：工具提示帮助信息。

  - regExp：用于校验文本的正则表达式，不需要边界记号。

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

      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,
          )
      );