Note: You are currently viewing documentation for Moodle 1.9. Up-to-date documentation for the latest stable version is available here: Output API.

Obsolete:Output API

From MoodleDocs

Moodle 2.0


Note: This article is a work in progress. Please use the page comments or an appropriate moodle.org forum for any recommendations/suggestions for improvement.


This page describes the Output API for Moodle 2.0. It works closely with the Page API, so you may want to refer to that documentation as well.

Components

Components in the Output API are classes that represent elements to be output. They do not contain any code for outputting anything, but they contain rich meta-data that is used by the Renderers to generate output. Some of the key aspects of components are outlined here:

  • Components do not have defined constructors with arguments. Passing arguments to the default constructor will not do anything useful.
  • Some components have a constructor which is used exclusively to instantiate object member variables.
  • Components consist mainly of variables with sensible defaults, and a prepare() method which makes use of these variables to setup other defaults prior to rendering.
  • The prepare() method always behaves the same way, regardless of which renderer is used. This ensures consistency of the component's variables.
  • Additional "shortcut" methods are sometimes added to provide a more high-level API to developers.

moodle_html_component

  • This is the base class for all output components. It is not declared as abstract, because you could actually use it to instantiate a basic component. However, almost all rendering functions will expect a sub-class of this class as a parameter, so instantiating it is unlikely to be very useful.
  • This class basically holds data and useful functions that can apply to any component, such as id, classes, style, alt and title (HTML attributes valid for any XHTML element). It also handles the collection and setting up of component_actions, which are described below. Refer to the class' PHP docs for details on variables and functions.
  • This class also defines a function for generating unique HTML ids for components that require one, and holds a static array for generated ids to prevent duplication.
  • A set_label($text, $for=null) is defined, with the first argument accepting either a string or a html_label component, in which latter case the second argument is ignored. If the component does not have an $id value, one will be generated and assigned to the label's $for value unless a html_label object is given as the $text argument. For this reason, if you explicitly set a component's $id value, make sure set_label() is called after you set that value.

HTML low-level components

This list of components replicate basic HTML elements. They are prefixed with html_ to make it clear that they are the basic building blocks of the output API.

html_label

  • Many HTML elements may have a label (input fields, dropdowns etc.). Some rendering functions look for this label and render it accordingly.
  • html_label requires a $text value, and should be given a $for value for accessibility reasons. It is rendered ultimately by $OUTPUT->label(html_label $label).

html_field

  • Represents a HTML input field. Can be used to output any input type, although some of its variables only apply to some types (e.g. maxlength only applies to text inputs).
  • It has a shortcut method for preparing a text input: make_text($name, $value, $alt, $maxlength).

html_button

  • Represents a HTML button, which may be rendered in many different ways, though by default it is rendered as an input field of type "button".
  • Requires a $text value (by default used as the HTML "value" attribute)

html_link

  • Represents a link, by default rendered by the $OUTPUT->link() function as HTML:

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

html_image

  • Simple class representing an image, rendered by $OUTPUT->image().
  • The $alt variable is set to HTML_ATTR_EMPTY by default. This constant is interpreted by the renderer as an attribute with an empty string as a value. If you use an actual empty string, the attribute will not be output at all, which would break XHTML strict for the <img/> tag.

html_form

  • This component represents a form 'wrapper' with an optional html_button object. You can use $OUTPUT->form($form, $contents) to output a form with any HTML you want within it.
  • The object requires a $url value, which can either be a string or a moodle_url object. In the prepare() method, this variable will be converted to a moodle_url.
  • If the $method "post" is used, the sesskey param will be added automatically
  • You can use the $params array to specify hidden inputs, but it will be ignored if you give a moodle_url as the $url value (because moodle_urls include query params).
  • This object is also used by the $OUTPUT->button($formwithbutton) and the $OUTPUT->confirm($message, $formcontinue, $formcancel) methods.

html_list

  • Represents a HTML nested list.
  • Has a load_data($tree, $level=0) recursive method which take a nested array and stores instantiated html_list_item objects in the $items array.
  • CSS classes are automatically added to each element in the list, to allow for custom styling.
  • This is rendered by $OUTPUT->htmllist($list) as a <ul> or <ol> element, but could be used to output nav menus etc. by yet unwritten output methods.
  • Use the $type variable to specify if the list should be ordered or unordered.

html_list_item

  • Represents a list item used by the html_list component. Only has a $value variable, but also benefits from all other variables and methods of the moodle_html_component base class.

html_table

  • Represents a HTML table with data
  • Is intended to replace the old flexible_table class
  • The $data array either holds an associate array of arrays representing rows and cells, or it can be set up with html_table_row and html_table_cell objects, for finer control over the look and layout of the table cells.
  • In the $OUTPUT->table($table) method, the $data array's contents are converted into html_table_row and html_table_cell objects if they are not already of that type.

html_table_row

  • A simple component holding an array of html_table_cell objects.

html_table_cell

  • This represents a table cell, and is aggregated by a html_table_row object, itself aggregated by html_table.
  • This component's variables mirror those of the XHTML <td> or <th> elements (differentiated by the $header boolean)

html_select

  • This object is by far the most complex HTML component in Moodle. It represents any element that presents the user with a choice. This includes:
    1. A dropdown menu (<select> tag), optionally with automatic redirection upon selection of an option
    2. A set of radio buttons (<input type="radio" /> tag)
    3. A set of checkboxes (<input type="checkbox" /> tag)
  • However, remember that the HTML tags given above are the default rendering of a html_select object. This object can hold so much data that it could be rendered in a multiple of different ways, not necessarily using these traditional HTML tags.
  • This class has a special method initialise_options() which converts the given $options into html_select_optgroup and html_select_option objects. This allows you to override these options' defaults and add style, classes and component_action objects before the object is sent to the renderer.
  • Some examples follow:
Basic example

The following will output a basic drop-down menu, ready to be included in a form: $select = html_select::make(array('1' => 'Value 1', '2' => 'Value 2'), 'choice1', '2')); echo $OUTPUT->select($select); Outputs: <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> Note that a default "Choose..." option with a value of 0 is added to the menu. To remove this, follow the next example: $select->nothinglabel = false; This will remove the default option completely.

Nested menus

You can also render a menu with one level of nesting, rendered as a dropdown with optgroups. You just need to do two things to achieve that:

  1. Specify $select->nested = true
  2. Either:
    • $select->load_data($flatarray), which requires a rather cryptic syntax with double-dashes for optgroups
    • $select->load_data($nestedarray), the first level's keys are the names of the optgroups, their arrays are the options' value=>label pairs.
    • Prepare the data directly as html_select_optgroup and html_select_option objects. This method requires more code but less debugging because it is a lot less brittle than a string-based syntax, and it allows more customised classes, JS actions etc. on each individual option.

The preferred method is the second one in the majority of cases, because it is easy to setup and debug. The first method should be avoided and will not be demonstrated here.

// Method 2: $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);

// Method 3: $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); Both these methods Output: <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> Although the last method looks very code-intensive, most of it would obviously be reduced using foreach loops, and it allows for much more customisation of the components.

Yes/No menu

A common use case is to print a Yes/No menu. This could be output as two radio buttons, but it is sometimes output as a menu. The two cases are demonstrated here: $select = html_select::make_yes_no('choice1', 1); $select->nothinglabel = false; // Don't forget to do this, or the "Choose..." option will appear and have the same value as the "No" option! echo $OUTPUT->select($select); Outputs: <select id="menuchoice1" class="menuchoice1 select" name="choice1">

 <option value="0">No</option>
 <option selected="selected" value="1">Yes</option>

</select>

Radio buttons: $select->rendertype = 'radio'; echo $OUTPUT->select($select); Outputs:

 <label for="html_select_option-b4d4bd">No</label>
 <input id="html_select_option-b4d4bd" type="radio" name="choice1" value="0"/>

 <label for="html_select_option-1eaa39">Yes</label>
 <input id="html_select_option-1eaa39" type="radio" checked="checked" name="choice1" value="1"/>

However, in many cases it is better to display a yes/no choice as a single checkbox. For this purpose, it is better to instantiate a single html_option object and pass it to $OUTPUT->checkbox().

Date/Time selectors

NOTE: This part of the API is under review

The html_select object can be used to output date or time selectors. A shortcut method is provided for this purpose: make_time_selector($type, $currenttime, $step); For more concise code, you can use the higher-level method 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);

// OR $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);

} Outputs: timeselectors.png

Popup Forms
  • This is a really bad name for a dropdown menu that redirects the user when an option is selected.
  • html_select::make_popup_form() is a shortcut method for returning an object ready for rendering through $OUTPUT->select()
  • The basic premise of a "popup form" is that each option has as its value the URL to which the user should be redirected when that option is selected
  • To simplify this process, make_popup_form() takes a URL as its first argument, and the name of a query param as the second. It is expected that the option values represent the value that will be assigned to this "variable" parameter.

$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); Outputs: <form id="myform" class="popupform" action="http://enterprise/cvs_moodle_head/course/jumpto.php" method="get">

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

</form>

Sometimes you will need some of the URLs to have a different base, or to have more parameters that change between options. The best way to achieve this is demonstrated here:

$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); Outputs: <form id="myform" class="popupform" action="http://enterprise/cvs_moodle_head/course/jumpto.php" method="get">

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

</form>

html_select_option

  • This component represents an option
  • It is not necessarily rendered as an <option> tag, but can also be rendered as a radio or a checkbox
  • It can be aggregated by html_select and html_select_optgroup, or used by itself in $OUTPUT->checkbox($option, $name)
  • It has a shortcut method for preparing a checkbox for output: make_checkbox($value, $selected, $label, $alt);

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

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

  • Note that an ID is generated in this case even though no component_action was added. This is the default behaviour for the checkbox() method.

html_select_optgroup

  • This represents an option group, used only by html_select to group options together. It doesn't do anything particularly useful in itself apart from aggregating html_select_option objects and having a text value.
  • It benefits from all the moodle_html_component variables and methods.

Moodle components

The following components do not map exactly to HTML elements, so they are prefixed with moodle_.

moodle_paging_bar

  • Represents a paging bar used to navigate a large list of records like users, forum posts etc.
  • Since 4 parameters are required, a shortcut function is provided: moodle_paging_bar::make($totalcount, $page, $perpage, $baseurl)
  • The first page has a value of 0 but is displayed as 1, so remember this offset.
  • If you have multiple paging bars on one page for different lists, set the $pagevar variable

$pagingbar = moodle_paging_bar::make(120, 3, 20, 'http://domain.com/index.php'); // Optionally : $pagingbar->pagevar = 'mypage'; echo $OUTPUT->paging_bar($pagingbar); Outputs:

 Page: (
 <a class="previous" href="http://domain.com/index.php?page=2">Previous</a>
 )   
 <a href="http://domain.com/index.php?page=0">1</a>
 <a href="http://domain.com/index.php?page=1">2</a>
 <a href="http://domain.com/index.php?page=2">3</a>
   4  
 <a href="http://domain.com/index.php?page=4">5</a>
 <a href="http://domain.com/index.php?page=5">6</a>
   (
 <a class="next" href="http://domain.com/index.php?page=4">Next</a>
 )

moodle_user_picture

  • Represents a user's picture to be output through $OUTPUT->user_picture()
  • Requires at least a $user object of stdClass with a minimum of data (id) and a $courseid
  • If no specific image is given (as a html_image object), then the default image is loaded

$user = new stdClass(); $user->id = 1; $userpic = new moodle_user_picture(); $userpic->user = $user; $userpic->courseid = 1;

echo $OUTPUT->user_picture($userpic); Outputs: <img class="image" style="height: 35px; width: 35px;" alt="Picture of Admin User" src="http://enterprise/cvs_moodle_head/pix/u/f2.png"/>

moodle_action_icon

  • Simply put, this is a linked image.

$icon = new moodle_action_icon(); $icon->image->src = $OUTPUT->old_icon_url('moodlelogo'); $icon->image->alt = 'What is moodle?'; $icon->link->url = new moodle_url('http://domain.com/index.php'); $icon->add_confirm_action('Are you sure?'); echo $OUTPUT->action_icon($icon);

moodle_help_icon

Renderers

moodle_renderer_base

  • Simple base class for Moodle renderers.
  • Tracks the xhtml_container_stack to use, which is passed in in the constructor.
  • Also has methods to facilitate generating HTML output.

output_tag methods

  • Low-level functions for outputting specific HTML tags.
  • For empty tags (with no content), use output_empty_tag

old_icon_url

  • Return the URL for an icon identified as in pre-Moodle 2.0 code
  • The equivalent for "$CFG->pixpath/i/course.gif" is mod_icon_url('i/course')

mod_icon_url

  • Same as old_icon_url, but for old module icons
  • The equivalent for "$CFG->modpixpath/$mod/icon.gif" is mod_icon_url('icon', $mod)

prepare_event_handlers(&$component)

  • Used by rendering functions to prepare JS event listeners for components that may require it.
  • All components that can receive user input should go through this method

prepare_legacy_width_and_height($component)

  • Returns the correct CSS for components that have the deprecated $height and/or $width attributes

template_renderer

moodle_core_renderer

Since these functions are very well documented inline (phpdoc), I will only put examples here, without in-depth explanations.

action_icon

$icon = new moodle_action_icon(); $icon->image->src = $OUTPUT->old_icon_url('moodlelogo'); $icon->image->alt = 'What is moodle?'; $icon->link->url = new moodle_url('http://domain.com/index.php'); $icon->add_confirm_action('Are you sure?'); // Optional. Equivalent to doing $icon->link->add_confirm_action('Are you sure?'); echo $OUTPUT->action_icon($icon); Outputs: <a id="html_link-2b4310" href="http://domain.com/index.php">

 <img class="action-icon image" alt="What is moodle?" src="http://enterprise/cvs_moodle_head/pix/moodlelogo.gif"/>

</a> ... <script type="text/javascript"> //<![CDATA[ YAHOO.util.Event.addListener('html_link-2b4310', 'click', confirm_dialog, {"message":"Are you sure?"}); //]]> </script>

box, box_start and box_end

echo $OUTPUT->box('A message of some kind'); // OR echo $OUTPUT->box_start(); echo 'A message of some kind'; echo $OUTPUT->box_end(); Outputs:

A message of some kind

button

  • Be aware that this method's signature requires a html_form component as its only argument. This form object must have a $button value (html_button)

$form = new html_form(); $form->url = new moodle_url('http://domain.com/index.php', array('id' => 3, 'userid' => 5)); $form->button->text = 'My account'; echo $OUTPUT->button($form); Outputs:

 <form action="http://domain.com/index.php" method="post">
     <input type="hidden" value="fXlccUgFTz" name="sesskey"/>
     <input type="hidden" value="3" name="id"/>
     <input type="hidden" value="5" name="userid"/>
     <input class="singlebutton" type="submit" value="My account"/>
 </form>

checkbox

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

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

close_window_button

echo $OUTPUT->close_window_button(); Outputs:

   <form action="http://enterprise/cvs_moodle_head/#" method="get">
       <input id="html_button-d35ffa" class="singlebutton" type="submit" value="Close this window"/>
   </form>

confirm

container, container_start and container_end

  • Container differs from box in two ways:
    1. It doesn't add default CSS classes (box adds a "box" class and a "generalbox" class unless the default is overridden)
    2. It is stored in the XHTML stack as a "container", not a "box"

echo $OUTPUT->container('A message of some kind', 'important', 'notice'); // OR echo $OUTPUT->container_start('important', 'notice'); echo 'A message of some kind'; echo $OUTPUT->container_end(); Outputs:

A message of some kind

continue_button

doc_link

error_text

footer

form

header

heading

heading_with_help

help_icon

htmllist

image

label

link

link_to_popup

notification

paging_bar

radio

select

select_option

spacer

table

textfield

user_picture

cli_core_renderer

Pix finders

interface icon_finder

pix_icon_finder

theme_icon_finder

smartpix_icon_finder

Actions

  • Component actions are objects that represent Moodle's response to a user's action on a component.
  • These objects bind to a moodle_html_component or one of its subclasses.
  • The renderers are responsible for interpreting these actions and generating the appropriate Javascript code.

component_action

  • This is the base class for all component actions. It includes the name of the event (click, change, keydown etc.), the name of the Javascript function to be called, and an optional array of arguments to pass to the JS function.
  • Important!: the JS function called by this event handler will always receive two arguments: "event" and "args".
    • The first is a DOM event object and can be used within the function to get the element on which the action was performed, and get information about the event (such as which key was pressed).
    • The second argument (args) is an object with named parameters (a "hash") that includes the optional JS arguments you defined in the component_action instantiation.
  • Any component which receives an action (through the moodle_html_component::add_action($action) method) needs to be given a unique DOM id attribute. If you do not specify it, one will be automatically generated for you.

$link = new html_link(); $link->url = new moodle_url('/index.php', array('id' => 2, 'delete' => 5)); $link->text = 'Delete this website';

$link->add_action('click', 'confirm_dialog', array('message' => 'Are you sure?')); // OR $action = new component_action('click', 'confirm_dialog', array('message' => 'Are you REALLY sure?')); $link->add_action($action);

echo $OUTPUT->link($link);

  • Actions cannot yet be stacked in a component. This means that the above code will behave erratically because we are setting two actions for the same event. It is better to write a custom, more complex JS function than to try to bind several event handlers to the same component.

popup_action

  • This action opens up a new window using the given $url value.
  • It has a $params associative array with the arguments to the JS window.open() function. It has sensible defaults, but you can override them if necessary.

Factories

Theme Config

XHTML Container Stack

Miscellaneous functions

See also