标签：moodle   api   

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() 函数 结果如下:

<a href="$url">$text</a>

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

输出:

<select id="menuchoice1" class="menuchoice1 select" name="choice1">
  <option value="0">No</option>
  <option selected="selected" value="1">Yes</option>
</select>

Radio 按钮:

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

输出:

<span class="radiogroup choice1 rb0">
  <label for="html_select_option-b4d4bd">No</label>
  <input id="html_select_option-b4d4bd" type="radio" name="choice1" value="0"/>
</span>
<span class="radiogroup choice1 rb1">
  <label for="html_select_option-1eaa39">Yes</label>
  <input id="html_select_option-1eaa39" type="radio" checked="checked" name="choice1" value="1"/>
</span>

然而, 大多数情况下我们更倾向于使用一个复选框选或不选来决定 是/否 所以使用 $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');

输出:

<span class="checkbox donotask">
  <input id="html_select_option-e7be90" type="checkbox" name="donotask" value="1"/>
  <label for="html_select_option-e7be90">Do Not Ask</label>
</span>

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

1.2.14 html_select_optgroup

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

· 它有利于从所有moodle_html_component变量和方法。

1.3 moodle 组件

下面的组件并不正好映射到HTML元素，所以它们的前缀是moodle_.

1.3.1 moodle_paging_bar 分页条

· 表示用于导航的用户一样，论坛帖子等记录的大名单分页条.

· 由于4个参数是必须的，一个快捷功能提供:

moodle_paging_bar::make($totalcount, $page, $perpage, $baseurl)

· 第一页有一个0值，但显示为1，所以记得这个偏移.

· 如果你有多个页面条在一个页面上的不同列表，设置$ pagevar变量

· 去 Output_API#paging_bar 找寻使用用例

1.3.2 moodle_user_picture 用户头像

· 表示用户的图像，通过被输出 $OUTPUT->user_picture()

· 至少需要一个标准stdClass的$user对象作为最小的数据 (id) 和 一个 $courseid

· 如果没有特定图像被给出（作为html_image对象），则默认的图像被加载

· 看 Output_API#user_picture 查找用例

1.3.3 moodle_action_icon 活动图标

· 简单地说，这是一个链接的图像.

· 通过 Output_API#action_icon 查看例子

1.3.4 moodle_help_inco 帮助图标

看 Output_API#help_icon 来查找用例. 代替旧的 helpbutton() 全局函数.

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

标签：moodle   api   

原文地址：http://blog.csdn.net/wujiangwei567/article/details/42348547