Obsolete:Output API

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.

Moodle components

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