Moodle 中文API之全局输出API（一）

叁歲伎倆 2022-08-06 07:14 399阅读 0赞

# Output API 全局输出API #

（注：此API官方更新少，部分内容可能过时。）

1. 组件

1.1 moodle\_html\_component  html组件

1.2 低级HTML 组件

1.2.1 html\_label

1.2.2 html\_field

1.2.3 html\_button

1.2.4 action\_link

1.2.5 html\_img

1.2.6 html\_form

1.2.7 html\_list

1.2.8 html\_list\_item

1.2.9 html\_table

1.2.10 html\_table\_row

1.2.11 html\_table\_cell

1.2.12 html\_select

1.2.12.1 基础例子

1.2.12.2 嵌套菜单

1.2.12.3 是/否 选择菜单

1.2.12.4 日期/时间 选择

1.2.12.5 弹出表单

1.2.13 html\_select\_option

1.2.14 html\_select\_optgroup

1.3 moodle 组件

1.3.1 moodle\_paging\_bar 分页条

1.3.2 moodle\_user\_picture 用户头像

1.3.3 moodle\_action\_icon 活动图标

1.3.4 moodle\_help\_inco 帮助图标

1. 组件

组件在 Output API中代表输出的元素. 他们不包含任何输出的代码, 但它们包含媒体数据输出的渲染.这里列出一些组件的关键环节:

· 组件没有定义带有参数的构造函数。传递参数的默认构造函数不会做任何有用的事.

· 有些组件是专门用于实例化对象的成员变量构造.

· 组件主要包括具有合理的默认值的变量，并事先使用一个prepare()方法进行渲染.

· 这个prepare() 方法总是以同样的方式操作，不管是哪个渲染器使用。这保证了组件的变量的一致性.

· 额外的“捷径”方法有时加入到提供更高层次的API给开发者.

1.1 moodle\_html\_component

· 这个是组件输出的最基本的类. 它不声明为抽象的，因为你可以用它来实例化一个基本组成部分。然而，几乎所有的渲染功能将期待一个子类这一类作为参数，所以实例就不太可能是非常有用的.

· 此类基本上保持数据和有用的功能，可以适用于任何组件，如 id, classes, style, alt 和title (HTML 的任何严格标准属性).  它还处理收集和设置component\_actions，这将在下文中描述的。请参阅类的PHP文档有关变量和函数的详细信息.

· 此类还定义了一个函数为HTML组件生成唯一的id，并且拥有一个静态数组处理生成的ID，以防止重复.

· 一个 set\_label($text, $for=null)方法是被定义的, 第一个参数接受一个字符串或一个 html\_label 组件, 之后的第二个参数是被忽略的. 如果这个组间没有一个 $id 值, 那么将会生成并且分配给 label的 $for 值除非 html\_label 对象被给作为这个$text 参数. 基于这个理由, 如果你精确的设置一个组件的 $id 值, 确保set\_label() 被调用在你设置这个值之后.

1.2 低级HTML 组件

此组件列表复制基本的HTML元素。它们的前缀为html\_，要清楚自己是输出API的基本组成部分。

1.2.1 html\_label

· 许多HTML 元素可能会有一个 label (input fields, 下拉列表 等.). 一些渲染函数查找此标签并相应地对他进行渲染.

· html\_label 需要一个 $text 值, 而且应该被给一个 $for 值来被访问. 他最终通过 $OUTPUT->label(html\_label $label) 来呈现.

1.2.2 html\_field

· 表示一个 HTML 输入框. 能够指定文本的类型, 虽然它的一些变量的仅适用于某些类型的输入 (如. maxlength 仅仅适用于 text inputs).

· 他有一个快捷方法与处理文本输入框:

make_text($name, $value, $alt, $maxlength).

1.2.3 html\_button

· 表示一个HTML 按钮, 有多重渲染方式，一般被默认渲染成input 类型的 "button".

· 需要一个 $text 值 (即 HTML "value" 属性)

1.2.4 action\_link

表示一个链接, 默认渲染通过 $OUTPUT->link() 函数 结果如下:

1.2.5 html\_img

· 简单的表示一个图像, 通过函数 $OUTPUT->image() 渲染.

· $alt 变量的默认设置是 HTML\_ATTR\_EMPTY. 就是一个空字符串. 如果您使用的是实际的空字符串，该属性将不输出任何东西，这将打破XHTML严格的<img/>标签定义。

1.2.6 html\_form

· 这个组件表示了一个带可选按钮的表单对象. 你可以使用 $OUTPUT->form($form, $contents) 去输出任何你想放在里面的HTML.

· T这个对象需要一个 $url 值, 可以是一个字符串或是一个 moodle\_url 对象. 在 prepare() 方法里, 这个变量将会转换成一个 moodle\_url.

· 如果 $method "post" 被使用, 那么sesskey 将会被自动添加。

· 你能使用 $params 数组来使用隐藏inputs,但是他将会忽略如果你给一个 moodle\_url作为$url值 (因为 moodle\_urls 包含了查询参数).

· 这个对象也被使用通过 $OUTPUT->button($formwithbutton) 和$OUTPUT->confirm($message, $formcontinue, $formcancel) 方法.

1.2.7 html\_list

· 代表一个HTML嵌套列表.

· 有一个 load\_data($tree, $level=0) 递归方法，它需要一个嵌套的数组并存储实例html\_list\_item对象在$items数组里.

· CSS 类被自动添加到每个元素中的列表中，以允许自定义风格.

· 他被渲染通过 $OUTPUT->htmllist($list) 以一个 <ul> 或 <ol> 元素显示, 但可以通过目前未写入输出方法被用来输出导航菜单等.

· 使用 $type 变量设置是有序还是无序列表.

1.2.8 html\_list\_item

· 表示一个序列item 使用通过 html\_list 组件. 仅仅有一个 $value 变量,

1.2.9 html\_table

· 表示一个包含数据的table

· 旨在取代旧flexible\_table类

· 这个$ data数组要么拥有一个关联数组的二维数组代表行和每个单元格，也可以通过设置html\_table\_row和html\_table\_cell对象，以便更好地控制表格单元格的外观和布局。

· 在html\_writer::table($table) 方法中,  $data 数组的内容是被转换成 html\_table\_row 和 html\_table\_cell 对象 如果他们不是上面所说的类型.

1.2.10 html\_table\_row

· 一个简单的组件处理一个html\_table\_cell对象数组.

1.2.11 html\_table\_cell

· 表示表格的一个单元格, 并且通过一个html\_table\_row 对象聚合, 他自身通过 html\_table组合.

· 这个组件自身对应于 XHTML <td>或 <th> 元素 (通过$header bool 值来选择哪一个)

1.2.12 html\_select

· 这个对象是Moodle中目前最复杂的HTML组件。它代表提出了一个选择用户的任何元素。这包括:

1. 一个下拉菜单 (<select> 标签), 可选自动重定向的选项

2. 一系列的radio 按钮集合 (<input type="radio" /> 标签)

3. 一系列的 checkboxes 的集合(<input type="checkbox" /> 标签)

· 然而, 我们要知道HTML上面讲的是渲染成html\_select对象. 这个对象要操作如此多的数据它可以以不同的方式多次渲染，不一定使用这些传统的HTML标签。

· 这个类有一个特殊的方法 initialise\_options() 能将 $options 转换成 html\_select\_optgroup 和 html\_select\_option 对象. 这允许你重写这些选项的默认值和风格(style), 类(classes)和 component\_action 对象 在对象被渲染之前.

· 一些例子如下:

1.2.12.1 基础例子

下面的例子输出一个基本的下拉菜单:

$select = html_select::make(array('1' => 'Value 1', '2' => 'Value 2'), 'choice1', '2'));
    echo $OUTPUT->select($select);

**输出****:**

<select id="menuchoice1" class="menuchoice1 select" name="choice1">
      <option value="0">Choose...</option>
      <option value="1">Value 1</option>
      <option selected="selected" value="2">Value 2</option>
    </select>

**注意有一个默认值为0的**** "Choose..."****选项会自动被添加****. ****如果要移除它****, ****在输出之前加上下面这段代码****:**

$select->nothinglabel = false;

他将完整的移除默认的选项.

1.2.12.2 嵌套菜单

你也可以渲染一种嵌套式的级别菜单,渲染使用optgroups组方式. 你仅仅需要做两件事就可以实现:

1. 设置 $select->nested = true

2. 或:

o $select->load\_data($flatarray), 这就需要用双破折号optgroups一个相当隐秘语法

o $select->load\_data($nestedarray), 第一级的关键字是optgroups的名字，他们的数组选项的关键字=>值对.

o 直接准备好数据作为 html\_select\_optgroup 和 html\_select\_option 对象. 这种方法需要更多的代码，但更少的调试，因为它是很多比基于字符串的语法更不易碎，并且它允许更多定制 classes, JS 动作等. 对每个单独的选项.

优选的方法是在第二个，在大多数情况下，因为它很容易安装和调试。应避免第一种方法，也不会在这里展示.

// 第二种方法:
    $options = array('Group1' => array('value1' => 'Option 1', 'value2' => 'Option 2'), 'Group2' => array('value3' => 'Option 3', 'value4' => 'Option 4'));
    $select = html_select::make($options, 'choice1', 'value1');
    $select->nested = true;
    echo $OUTPUT->select($select);
     
    // 第三种方法:
    $optgroup1 = new html_select_optgroup();
    $optgroup2 = new html_select_optgroup();
    $optgroup1->text = 'Group1';
    $optgroup2->text = 'Group2';
     
    $option1 = new html_select_option();
    $option2 = new html_select_option();
    $option3 = new html_select_option();
    $option4 = new html_select_option();
     
    $option1->text = 'Option 1';
    $option1->value = 'value1';
    $option2->text = 'Option 2';
    $option2->value = 'value2';
    $option3->text = 'Option 3';
    $option3->value = 'value3';
    $option4->text = 'Option 4';
    $option4->value = 'value4';
     
    $optgroup1->options = array($option1, $option2);
    $optgroup2->options = array($option3, $option4);
     
    $select = html_select::make(array($optgroup1, $optgroup2), 'choice1', 'value1');
    $select->nested = true;
    echo $OUTPUT->select($select);

**上面两种都会输出****:**

<select id="menuchoice1" class="menuchoice1 select" name="choice1">
      <optgroup label="Group1">
        <option selected="selected" value="value1">Option 1</option>
        <option value="value2">Option 2</option>
      </optgroup>
      <optgroup label="Group2">
        <option value="value3">Option 3</option>
        <option value="value4">Option 4</option>
      </optgroup>
    </select>

虽然最后的方法看起来非常的代码密集，但是显然会使用foreach循环减少，这使得组件更定制。

1.2.12.3 是/否 选择菜单

一种普遍的使用情况是 打印 Yes/No 菜单. 这可能会输出两个 radio按钮, 但是他有时会输出成一个菜单. 下面分别是两个这样的例子:

$select = html_select::make_yes_no('choice1', 1);
    $select->nothinglabel = false; // 别忘了加上这句, 否则会自动添加默认的0值得选择项
    echo $OUTPUT->select($select);

**输出****:**

**Radio ****按钮****:**

$select->rendertype = 'radio';
    echo $OUTPUT->select($select);

输出:

然而, 大多数情况下我们更倾向于使用一个复选框选或不选来决定 是/否 所以使用 $OUTPUT->checkbox().

1.2.12.4 日期/时间 选择

注意: 这部分API正在审查

html\_select能被用来输出日期或时间选择器. 一个简短的方法能达到这个目的:

make_time_selector($type, $currenttime, $step);

为了更精准的控制你可以使用更高级的方法

make_time_selectors($selectors, $currentime, $step);

$dayselector = html_select::make_time_selector('days', 'myday', '120308000');
    $monthselector = html_select::make_time_selector('months', 'mymonth', '120308000');
    $yearselector = html_select::make_time_selector('years', 'myyear', '120308000');
    $hourselector = html_select::make_time_selector('hours', 'myhour', '120308000');
    $minuteselector = html_select::make_time_selector('minutes', 'myminute', '120308000', 5);
    echo $OUTPUT->select($dayselector);
    echo $OUTPUT->select($monthselector);
    echo $OUTPUT->select($yearselector);
    echo $OUTPUT->select($hourselector);
    echo $OUTPUT->select($minuteselector);
     
    // 或者
    $selectors = html_select::make_time_selectors(array('days' => 'myday', 'months' => 'mymonth', 'years' => 'myyear', 'hours' => 'myhour', 'minutes' => 'myminute'), '120308000', 5);
    foreach ($selectors as $select) {
        echo $OUTPUT->select($select);
    }

1.2.12.5 弹出表单

· 这是一个非常糟糕的名称将用户重定向下拉菜单当选择一个选项.

· html\_select::make\_popup\_form() 是一种快捷的方法返回一个对象，准备渲染通过 $OUTPUT->select()

· 一个“弹出表单”的基本前提是，每个选项都有其值的URL，而当选择该选项的用户应该被重定向

· 为简化这个过程, make\_popup\_form() 携带了一个 URL 作为她的第一个参数, 和查询参数的名字作为第二个参数. 据预计，该选项值表示将被分配到这个值 "variable" 参数.

$options = array(1 => 'Page 1', 2 => 'Page 2', 3 => 'Page 3');
    $select = html_select::make_popup_form('http://domain.com/index.php', 'id', $options, 'myform');
    echo $OUTPUT->select($select);

**输出****:**

<form id="myform" class="popupform" action="http://enterprise/cvs_moodle_head/course/jumpto.php" method="get">
      <div>
        <input type="hidden" value="JEgniUhzzx" name="sesskey"/>
        <select id="myform_jump" class="menujump select" name="jump">
          <option value="0">Choose...</option>
          <option value="http://domain.com/index.php?id=1">Page 1</option>
          <option value="http://domain.com/index.php?id=2">Page 2</option>
          <option value="http://domain.com/index.php?id=3">Page 3</option>
        </select>
        <div id="noscriptmyform" style="display: none;">
          <input class="singlebutton" type="submit" value="Go"/>
        </div>
      </div>
    </form>

**有时候你需要一些网址有不同的基础，或有更多的参数选项之间进行切换。实现这一目标的最好办法是在这里证明:**

$options = array('http://domain.com/index.php?id=1' => 'Page 1', 
                     'http://domain.com/otherpage/index.php?modid=1' => 'Page 2', 
                     'http://domain.com/index.php?id=1&othervar=2' => 'Page 3');
    $select = html_select::make_popup_form('', '', $options, 'myform');
    $select->override_option_values($options);
    echo $OUTPUT->select($select);

**输出****:**

<form id="myform" class="popupform" action="http://enterprise/cvs_moodle_head/course/jumpto.php" method="get">
      <div>
        <input type="hidden" value="JEgniUhzzx" name="sesskey"/>
        <select id="myform_jump" class="menujump select" name="jump">
          <option value="0">Choose...</option>
          <option value="http://domain.com/index.php?id=1">Page 1</option>
          <option value="http://domain.com/otherpage/index.php?modid=1">Page 2</option>
          <option value="http://domain.com/index.php?id=1&othervar=2">Page 3</option>
        </select>
        <div id="noscriptmyform" style="display: none;">
          <input class="singlebutton" type="submit" value="Go"/>
        </div>
      </div>
    </form>

1.2.13 html\_select\_option

· 这个组件表示一个选项

· 它不仅可以渲染成一个 <option> 标签, 而且可以渲染成一个 radio或者是一个checkbox

· 塔内被组合起来通过html\_select 和 html\_select\_optgroup,或者单独使用在 $OUTPUT->checkbox($option, $name)

· 他有一个快捷的方法输出成 checkbox:

make_checkbox($value, $selected, $label, $alt);

$checkbox = html_select_option::make_checkbox('1', false, get_string('donotask'));
    echo $OUTPUT->checkbox($checkbox, 'donotask');

**输出****:**

在即使没有component\_action中加入这种情况下，产生一个ID。这是该checkbox（）方法的默认行为。

1.2.14 html\_select\_optgroup

· 这代表了一个选项组, 仅仅只能通过 html\_select对象去组合选项在一起. 它本身并不从聚集做任何特别有用的分开 html\_select\_option 对象且有一个文本值.

· 它有利于从所有moodle\_html\_component变量和方法。