MoodleDocs - User contributions [en]

Output API

2012-07-26T08:35:59Z

Simontite: /* moodle_action_icon */ Fix link to example usage and output

{{obsolete}}
See [[Migrating_your_code_to_the_2.0_rendering_API#Outputting_HTML_specific_to_your_module|this page]] for more up-to-date information. --[[User:David Mudrak|David Mudrak]] 22:16, 23 August 2009 (UTC)

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:
<code html4strict>
<a href="$url">$text</a>
</code>

==== 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 <nowiki><ul> or <ol></nowiki> 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 html_writer::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 <nowiki><td> or <th></nowiki> 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:
*#A dropdown menu (<nowiki><select> tag</nowiki>), optionally with automatic redirection upon selection of an option
*#A set of radio buttons (<nowiki><input type="radio" /> tag</nowiki>)
*#A set of checkboxes (<nowiki><input type="checkbox" /> tag</nowiki>)
*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:
<code php>
$select = html_select::make(array('1' => 'Value 1', '2' => 'Value 2'), 'choice1', '2'));
echo $OUTPUT->select($select);
</code>
Outputs:
<code html4strict>
<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>
</code>
Note that a default "Choose..." option with a value of 0 is added to the menu. To remove this, follow the next example:
<code php>
$select->nothinglabel = false;
</code>
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:
#Specify $select->nested = true
#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.

<code php>
// 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);
</code>
Both these methods Output:
<code html4strict>
<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>
</code>
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:
<code php>
$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);
</code>
Outputs:
<code html4strict>
<select id="menuchoice1" class="menuchoice1 select" name="choice1">
<option value="0">No</option>
<option selected="selected" value="1">Yes</option>
</select>
</code>

Radio buttons:
<code php>
$select->rendertype = 'radio';
echo $OUTPUT->select($select);
</code>
<code html4strict>
Outputs:
<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>
</code>

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

<code php>
$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);
}
</code>
Outputs:
[[Image: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.

<code php>
$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);
</code>
Outputs:
<code html4strict>
<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>
</code>

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:

<code php>
$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);
</code>
Outputs:
<code html4strict>
<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>
</code>

==== html_select_option ====
*This component represents an option
*It is not necessarily rendered as an <nowiki><option></nowiki> 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);

<code php>
$checkbox = html_select_option::make_checkbox('1', false, get_string('donotask'));
echo $OUTPUT->checkbox($checkbox, 'donotask');
</code>
Outputs:
<code html4strict>
<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>
</code>
*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
*See [[Output_API#paging_bar]] for example usage and output

==== 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
*See [[Output_API#user_picture]] for example usage and output

==== moodle_action_icon ====
*Simply put, this is a linked image.
*See [[Output_API#action_icon]] for example usage and output

==== moodle_help_icon ====
See [[Output_API#help_icon]] For example usage. Replaces the old helpbutton() global function.

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

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

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

==== action_icon ====
<code php>
$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);
</code>
Outputs:
<code html4strict>
<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>
</code>

==== box, box_start and box_end ====
<code php>
echo $OUTPUT->box('A message of some kind');
// OR
echo $OUTPUT->box_start();
echo 'A message of some kind';
echo $OUTPUT->box_end();
</code>
Outputs:
<code html4strict>
<div class="box generalbox">A message of some kind</div>
</code>

==== 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)
<code php>
$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);
</code>
Outputs:
<code html4strict>
<div class="singlebutton">
<form action="http://domain.com/index.php" method="post">
<div>
<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"/>
</div>
</form>
</div>
</code>

==== checkbox ====
<code php>
$checkbox = html_select_option::make_checkbox('1', false, get_string('donotask'));
echo $OUTPUT->checkbox($checkbox, 'donotask');
</code>
Outputs:
<code html4strict>
<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>
</code>

==== close_window_button ====
<code php>
echo $OUTPUT->close_window_button();
</code>
Outputs:
<code html4strict>
<div class="closewindow">
<div class="singlebutton">
<form action="http://enterprise/cvs_moodle_head/#" method="get">
<div>
<input id="html_button-d35ffa" class="singlebutton" type="submit" value="Close this window"/>
</div>
</form>
</div>
</div>
...
<script type="text/javascript">
//<![CDATA[
YAHOO.util.Event.addListener('html_button-d35ffa', 'click', close_window);
//]]>
</script>
</code>

==== confirm ====
<code php>
echo $OUTPUT->confirm('Are you sure?', '/index.php?delete=1', '/index.php');
</code>
Outputs
<code html4strict>
<div id="notice" class="box generalbox">
<p>Are you sure?</p>
<div class="buttons">
<div class="singlebutton">
<form action="http://enterprise/cvs_moodle_head/index.php" method="post">
<div>
<input type="hidden" value="fXlccUgFTz" name="sesskey"/>
<input type="hidden" value="1" name="delete"/>
<input class="singlebutton" type="submit" value="Yes"/>
</div>
</form>
</div>
<div class="singlebutton">
<form action="http://enterprise/cvs_moodle_head/index.php" method="post">
<div>
<input type="hidden" value="fXlccUgFTz" name="sesskey"/>
<input class="singlebutton" type="submit" value="No"/>
</div>
</form>
</div>
</div>
</div>
</code>

==== container, container_start and container_end ====
*Container differs from box in two ways:
*#It doesn't add default CSS classes (box adds a "box" class and a "generalbox" class unless the default is overridden)
*#It is stored in the XHTML stack as a "container", not a "box"
<code php>
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();
</code>
Outputs:
<code html4strict>
<div id="notice" class="important">A message of some kind</div>
</code>

==== continue_button ====
<code php>
echo $OUTPUT->continue_button('http://domain.com/index.php?id=2&userid=4');
// OR (preferred)
echo $OUTPUT->continue_button(new moodle_url('http://domain.com/index.php', array('id' => 2, 'userid' => 4)));
</code>
Outputs:
<code html4strict>
<div class="continuebutton">
<div class="singlebutton">
<form action="http://domain.com/index.php" method="get">
<div>
<input type="hidden" value="2" name="id"/>
<input type="hidden" value="4" name="userid"/>
<input class="singlebutton" type="submit" value="Continue"/>
</div>
</form>
</div>
</div>
</code>

==== doc_link ====
Not for general use.

==== error_text ====
<code php>
echo $OUTPUT->error_text("It's all broken!");
</code>
Outputs:
<code html4strict>
<span class="error">It's all broken!</span>
</code>

==== footer ====
*Simply call $OUTPUT->footer() at the end of each page.
*The output may vary depending on which page you are on.

==== form ====
<code php>
$form = new html_form();
$form->url = new moodle_url('http://domain.com/index.php', array('id' => 3, 'userid' => 5));
$checkbox = html_select_option::make_checkbox(1, false, 'Agree to terms');
$contents = $OUTPUT->container('Terms and conditions: Be kind and courteous');
$contents .= $OUTPUT->checkbox($checkbox, 'agree');
echo $OUTPUT->form($form, $contents);
</code>
Outputs:
<code html4strict>
<form action="http://domain.com/index.php" method="post">
<div>
<input type="hidden" value="79D3tSzYfz" name="sesskey"/>
<input type="hidden" value="3" name="id"/>
<input type="hidden" value="5" name="userid"/>
<div>Terms and conditions: Be kind and courteous</div>
<span class="checkbox agree">
<input id="html_select_option-3a3de0" type="checkbox" name="agree" value="1"/>
<label for="html_select_option-3a3de0">Agree to terms</label>
</span>
<input class="singlebutton" type="submit" value="Submit"/>
</div>
</form>
</code>

==== header ====
==== heading ====
<code php>
echo $OUTPUT->heading(get_string('help'), 3, 'helptitle', 'uniqueid');
</code>
Outputs:
<code html4strict>
<h3 id="uniqueid" class="helptitle">Help</h3>
</code>

==== heading_with_help ====
<code php>
$helpicon = new moodle_help_icon();
$helpicon->page = 'posts';
$helpicon->text = 'Help about forum posts';
$helpicon->module = 'forum';
echo $OUTPUT->heading_with_help($helpicon);
</code>
Outputs:
<code html4strict>
<div class="heading-with-help">
<h2 class="main help">Help about forum posts</h2>
<span class="helplink">
<a id="html_link-7b0b0d" href="http://enterprise/cvs_moodle_head/help.php?module=forum&file=posts.html">
<img class="iconhelp image" src="http://enterprise/cvs_moodle_head/pix/help.gif" alt="" />
</a>
</span>
</div>
</code>

==== help_icon ====
<code php>
$helpicon = new moodle_help_icon();
$helpicon->page = 'posts';
$helpicon->text = 'Help about forum posts';
$helpicon->module = 'forum';
echo $OUTPUT->help_icon($helpicon);
</code>
Outputs:
<code html4strict>
<span class="helplink">
<a id="html_link-42560f" href="http://enterprise/cvs_moodle_head/help.php?module=forum&file=posts.html">
<img class="iconhelp image" src="http://enterprise/cvs_moodle_head/pix/help.gif" alt="Help about forum posts" title="Help about forum posts" />
</a>
</span>
</code>

==== htmllist ====
<code php>
$data = array('Group 1' => array('Group 1.1' => array('Item 1.1.1', 'Item 1.1.2'), 'Item 1.2'),
'Group 2' => array('Item 2.1', 'Item 2.2', 'Item 2.3'));
$list = new html_list();
$list->type = 'ordered';
$list->load_data($data);
echo $OUTPUT->htmllist($list);
</code>
Outputs:
<code html4strict>
<ol class="list-0">
<li>Group 1
<ol class="list-1">
<li>Group 1.1
<ol class="list-2">
<li class="list-item-2-1">Item 1.1.1</li>
<li class="list-item-2-2">Item 1.1.2</li>
</ol>
</li>
<li class="list-item-1-2">Item 1.2</li>
</ol>
</li>
<li>Group 2
<ol class="list-1">
<li class="list-item-1-1">Item 2.1</li>
<li class="list-item-1-2">Item 2.2</li>
<li class="list-item-1-3">Item 2.3</li>
</ol>
</li>
</ol>
</code>
Notes:
*The class names are generated automatically. For ol and ul classes, the digit represents the depth of nesting.
*This is also the meaning of the first digit in the list item classes, the second being the number of the list item in the item's list.
*Once you have called $list->load_data($array), the list->items array is filled with html_list and html_list_item components, which you can setup in more details in preparation for output.

==== image ====
<code php>
$image = new html_image();
$image->src = 'http://domain.com/help.gif';
$image->alt = 'Helpful icon';
$image->width = 24;
$image->height = 24;
</code>
Outputs:
<code html4strict>
<img class="image" style="height: 24px; width: 24px;" alt="Helpful icon" src="http://domain.com/help.gif"/>
</code>

==== label ====
<code php>
$label = new html_label();
$label->text = 'Form element';
echo $OUTPUT->label($label);
</code>
Outputs:
<code html4strict>
<label>Form element</label>
</code>

This is a rather low-level function, you will rarely need to call it directly. Instead, use labels on subclasses of labelled_html_component:

<code php>
$field = new html_field();
$field->name = 'variable1';
$field->id = 'myfield';
$field->set_label('Form element');
echo $OUTPUT->textfield($field);
</code>
Outputs:
<code html4strict>
<span class="textfield variable1">
<label for="myfield">Form element</label>
<input id="myfield" type="text" style="width: 4em;" name="variable1"/>
</span>
</code>

==== link ====
<code php>
$link = new html_link();
$link->url = new moodle_url('http://domain.com/index.php', array('id' => 2, 'action' => 'browse')); // required, but you can use a string instead
$link->text = 'Browse page 2'; // Required
echo $OUTPUT->link($link)
</code>
Outputs:
<code html4strict>
<a href="http://domain.com/index.php?id=2&action=browse">Browse page 2</a>
</code>

==== link_to_popup ====
*Same API as for link(), but you set a popup_action on the component, and link() will forward it to the link_to_popup() method. You shouldn't need to call this method directly.
==== link ====
<code php>
$link = html_link::make(new moodle_url('http://domain.com/index.php', array('id' => 2, 'action' => 'browse')), 'Browse page 2');
$link->add_action(new popup_action('click', $link->url));
echo $OUTPUT->link($link)
</code>
Outputs:
<code html4strict>
<a id="html_link-985165" href="http://domain.com/index.php?id=2&action=browse">Browse page 2</a>
...
<script type="text/javascript">
//<![CDATA[
YAHOO.util.Event.addListener('html_link-985165', 'click', openpopup, {"url":"http:\/\/domain.com\/index.php?id=2&action=browse","name":"popup","options":"[...]"});
//]]>
</script>
</code>

==== notification ====
*By default this function works just like container(), with a default class set to 'notifyproblem'.
*It actually inserts a template token which is interpreted and rendered at a later stage.

==== paging_bar ====
<code php>
$pagingbar = moodle_paging_bar::make(120, 3, 20, 'http://domain.com/index.php');
// Optionally : $pagingbar->pagevar = 'mypage';
echo $OUTPUT->paging_bar($pagingbar);
</code>
Outputs:
<code html4strict>
<div class="paging">
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>
)
</div>
</code>

==== radio ====
==== select ====
*This method depends heavily on how the passed component is configured, so see [[Output_API#html_select]] For a detailed description

==== select_option ====
*Used internally by select(), you shouldn't need to call this directly.

==== spacer ====
==== table ====
<code php>
$table = new html_table();
$table->head = array('Student', 'Grade', 'Comments');
$table->data = array(
array('Harry Potter', '76%', 'Getting better'),
array('Rincewind', '89%', 'Lucky as usual'),
array('Elminster Aumar', '100%', 'Easy when you know everything!')
);
echo html_writer::table($table);
</code>
Outputs:
<code html4strict>
<table class="generaltable">
<thead>
<tr>
<th class="header c0" scope="col" style="white-space: nowrap;">Student</th>
<th class="header c1" scope="col" style="white-space: nowrap;">Grade</th>
<th class="header c2 lastcol" scope="col" style="white-space: nowrap;">Comments</th>
</tr>
</thead>
<tbody>
<tr class="r0">
<td class="cell">Harry Potter</td>
<td class="cell">76%</td>
<td class="cell">Getting better</td>
</tr>
<tr class="r1">
<td class="cell">Rincewind</td>
<td class="cell">89%</td>
<td class="cell">Lucky as usual</td>
</tr>
<tr class="r0 lastrow">
<td class="cell">Elminster Aumar</td>
<td class="cell">100%</td>
<td class="cell">Easy when you know everything!</td>
</tr>
</tbody>
</table>
</code>

==== textfield ====
==== user_picture ====
<code php>
$user = new stdClass();
$user->id = 1;
$userpic = new moodle_user_picture();
$userpic->user = $user;
$userpic->courseid = 1;

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

=== cli_core_renderer ===

== 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.
<code php>
$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);
</code>
*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==

* [[How_Moodle_outputs_HTML]]
* [[Migrating your code to the 2.0 rendering_API]]
* [[Outputting HTML in 2.0]]
* [[Theme_changes]]

Output API

2012-07-26T08:34:11Z

Simontite: /* moodle_user_picture */ Fix link to user_picture example usage and output

{{obsolete}}
See [[Migrating_your_code_to_the_2.0_rendering_API#Outputting_HTML_specific_to_your_module|this page]] for more up-to-date information. --[[User:David Mudrak|David Mudrak]] 22:16, 23 August 2009 (UTC)

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:
<code html4strict>
<a href="$url">$text</a>
</code>

==== 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 <nowiki><ul> or <ol></nowiki> 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 html_writer::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 <nowiki><td> or <th></nowiki> 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:
*#A dropdown menu (<nowiki><select> tag</nowiki>), optionally with automatic redirection upon selection of an option
*#A set of radio buttons (<nowiki><input type="radio" /> tag</nowiki>)
*#A set of checkboxes (<nowiki><input type="checkbox" /> tag</nowiki>)
*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:
<code php>
$select = html_select::make(array('1' => 'Value 1', '2' => 'Value 2'), 'choice1', '2'));
echo $OUTPUT->select($select);
</code>
Outputs:
<code html4strict>
<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>
</code>
Note that a default "Choose..." option with a value of 0 is added to the menu. To remove this, follow the next example:
<code php>
$select->nothinglabel = false;
</code>
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:
#Specify $select->nested = true
#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.

<code php>
// 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);
</code>
Both these methods Output:
<code html4strict>
<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>
</code>
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:
<code php>
$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);
</code>
Outputs:
<code html4strict>
<select id="menuchoice1" class="menuchoice1 select" name="choice1">
<option value="0">No</option>
<option selected="selected" value="1">Yes</option>
</select>
</code>

Radio buttons:
<code php>
$select->rendertype = 'radio';
echo $OUTPUT->select($select);
</code>
<code html4strict>
Outputs:
<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>
</code>

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

<code php>
$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);
}
</code>
Outputs:
[[Image: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.

<code php>
$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);
</code>
Outputs:
<code html4strict>
<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>
</code>

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:

<code php>
$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);
</code>
Outputs:
<code html4strict>
<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>
</code>

==== html_select_option ====
*This component represents an option
*It is not necessarily rendered as an <nowiki><option></nowiki> 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);

<code php>
$checkbox = html_select_option::make_checkbox('1', false, get_string('donotask'));
echo $OUTPUT->checkbox($checkbox, 'donotask');
</code>
Outputs:
<code html4strict>
<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>
</code>
*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
*See [[Output_API#paging_bar]] for example usage and output

==== 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
*See [[Output_API#user_picture]] for example usage and output

==== moodle_action_icon ====
*Simply put, this is a linked image.
*See [[Output_API:action_icon]] for example usage and output

==== moodle_help_icon ====
See [[Output_API#help_icon]] For example usage. Replaces the old helpbutton() global function.

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

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

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

==== action_icon ====
<code php>
$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);
</code>
Outputs:
<code html4strict>
<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>
</code>

==== box, box_start and box_end ====
<code php>
echo $OUTPUT->box('A message of some kind');
// OR
echo $OUTPUT->box_start();
echo 'A message of some kind';
echo $OUTPUT->box_end();
</code>
Outputs:
<code html4strict>
<div class="box generalbox">A message of some kind</div>
</code>

==== 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)
<code php>
$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);
</code>
Outputs:
<code html4strict>
<div class="singlebutton">
<form action="http://domain.com/index.php" method="post">
<div>
<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"/>
</div>
</form>
</div>
</code>

==== checkbox ====
<code php>
$checkbox = html_select_option::make_checkbox('1', false, get_string('donotask'));
echo $OUTPUT->checkbox($checkbox, 'donotask');
</code>
Outputs:
<code html4strict>
<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>
</code>

==== close_window_button ====
<code php>
echo $OUTPUT->close_window_button();
</code>
Outputs:
<code html4strict>
<div class="closewindow">
<div class="singlebutton">
<form action="http://enterprise/cvs_moodle_head/#" method="get">
<div>
<input id="html_button-d35ffa" class="singlebutton" type="submit" value="Close this window"/>
</div>
</form>
</div>
</div>
...
<script type="text/javascript">
//<![CDATA[
YAHOO.util.Event.addListener('html_button-d35ffa', 'click', close_window);
//]]>
</script>
</code>

==== confirm ====
<code php>
echo $OUTPUT->confirm('Are you sure?', '/index.php?delete=1', '/index.php');
</code>
Outputs
<code html4strict>
<div id="notice" class="box generalbox">
<p>Are you sure?</p>
<div class="buttons">
<div class="singlebutton">
<form action="http://enterprise/cvs_moodle_head/index.php" method="post">
<div>
<input type="hidden" value="fXlccUgFTz" name="sesskey"/>
<input type="hidden" value="1" name="delete"/>
<input class="singlebutton" type="submit" value="Yes"/>
</div>
</form>
</div>
<div class="singlebutton">
<form action="http://enterprise/cvs_moodle_head/index.php" method="post">
<div>
<input type="hidden" value="fXlccUgFTz" name="sesskey"/>
<input class="singlebutton" type="submit" value="No"/>
</div>
</form>
</div>
</div>
</div>
</code>

==== container, container_start and container_end ====
*Container differs from box in two ways:
*#It doesn't add default CSS classes (box adds a "box" class and a "generalbox" class unless the default is overridden)
*#It is stored in the XHTML stack as a "container", not a "box"
<code php>
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();
</code>
Outputs:
<code html4strict>
<div id="notice" class="important">A message of some kind</div>
</code>

==== continue_button ====
<code php>
echo $OUTPUT->continue_button('http://domain.com/index.php?id=2&userid=4');
// OR (preferred)
echo $OUTPUT->continue_button(new moodle_url('http://domain.com/index.php', array('id' => 2, 'userid' => 4)));
</code>
Outputs:
<code html4strict>
<div class="continuebutton">
<div class="singlebutton">
<form action="http://domain.com/index.php" method="get">
<div>
<input type="hidden" value="2" name="id"/>
<input type="hidden" value="4" name="userid"/>
<input class="singlebutton" type="submit" value="Continue"/>
</div>
</form>
</div>
</div>
</code>

==== doc_link ====
Not for general use.

==== error_text ====
<code php>
echo $OUTPUT->error_text("It's all broken!");
</code>
Outputs:
<code html4strict>
<span class="error">It's all broken!</span>
</code>

==== footer ====
*Simply call $OUTPUT->footer() at the end of each page.
*The output may vary depending on which page you are on.

==== form ====
<code php>
$form = new html_form();
$form->url = new moodle_url('http://domain.com/index.php', array('id' => 3, 'userid' => 5));
$checkbox = html_select_option::make_checkbox(1, false, 'Agree to terms');
$contents = $OUTPUT->container('Terms and conditions: Be kind and courteous');
$contents .= $OUTPUT->checkbox($checkbox, 'agree');
echo $OUTPUT->form($form, $contents);
</code>
Outputs:
<code html4strict>
<form action="http://domain.com/index.php" method="post">
<div>
<input type="hidden" value="79D3tSzYfz" name="sesskey"/>
<input type="hidden" value="3" name="id"/>
<input type="hidden" value="5" name="userid"/>
<div>Terms and conditions: Be kind and courteous</div>
<span class="checkbox agree">
<input id="html_select_option-3a3de0" type="checkbox" name="agree" value="1"/>
<label for="html_select_option-3a3de0">Agree to terms</label>
</span>
<input class="singlebutton" type="submit" value="Submit"/>
</div>
</form>
</code>

==== header ====
==== heading ====
<code php>
echo $OUTPUT->heading(get_string('help'), 3, 'helptitle', 'uniqueid');
</code>
Outputs:
<code html4strict>
<h3 id="uniqueid" class="helptitle">Help</h3>
</code>

==== heading_with_help ====
<code php>
$helpicon = new moodle_help_icon();
$helpicon->page = 'posts';
$helpicon->text = 'Help about forum posts';
$helpicon->module = 'forum';
echo $OUTPUT->heading_with_help($helpicon);
</code>
Outputs:
<code html4strict>
<div class="heading-with-help">
<h2 class="main help">Help about forum posts</h2>
<span class="helplink">
<a id="html_link-7b0b0d" href="http://enterprise/cvs_moodle_head/help.php?module=forum&file=posts.html">
<img class="iconhelp image" src="http://enterprise/cvs_moodle_head/pix/help.gif" alt="" />
</a>
</span>
</div>
</code>

==== help_icon ====
<code php>
$helpicon = new moodle_help_icon();
$helpicon->page = 'posts';
$helpicon->text = 'Help about forum posts';
$helpicon->module = 'forum';
echo $OUTPUT->help_icon($helpicon);
</code>
Outputs:
<code html4strict>
<span class="helplink">
<a id="html_link-42560f" href="http://enterprise/cvs_moodle_head/help.php?module=forum&file=posts.html">
<img class="iconhelp image" src="http://enterprise/cvs_moodle_head/pix/help.gif" alt="Help about forum posts" title="Help about forum posts" />
</a>
</span>
</code>

==== htmllist ====
<code php>
$data = array('Group 1' => array('Group 1.1' => array('Item 1.1.1', 'Item 1.1.2'), 'Item 1.2'),
'Group 2' => array('Item 2.1', 'Item 2.2', 'Item 2.3'));
$list = new html_list();
$list->type = 'ordered';
$list->load_data($data);
echo $OUTPUT->htmllist($list);
</code>
Outputs:
<code html4strict>
<ol class="list-0">
<li>Group 1
<ol class="list-1">
<li>Group 1.1
<ol class="list-2">
<li class="list-item-2-1">Item 1.1.1</li>
<li class="list-item-2-2">Item 1.1.2</li>
</ol>
</li>
<li class="list-item-1-2">Item 1.2</li>
</ol>
</li>
<li>Group 2
<ol class="list-1">
<li class="list-item-1-1">Item 2.1</li>
<li class="list-item-1-2">Item 2.2</li>
<li class="list-item-1-3">Item 2.3</li>
</ol>
</li>
</ol>
</code>
Notes:
*The class names are generated automatically. For ol and ul classes, the digit represents the depth of nesting.
*This is also the meaning of the first digit in the list item classes, the second being the number of the list item in the item's list.
*Once you have called $list->load_data($array), the list->items array is filled with html_list and html_list_item components, which you can setup in more details in preparation for output.

==== image ====
<code php>
$image = new html_image();
$image->src = 'http://domain.com/help.gif';
$image->alt = 'Helpful icon';
$image->width = 24;
$image->height = 24;
</code>
Outputs:
<code html4strict>
<img class="image" style="height: 24px; width: 24px;" alt="Helpful icon" src="http://domain.com/help.gif"/>
</code>

==== label ====
<code php>
$label = new html_label();
$label->text = 'Form element';
echo $OUTPUT->label($label);
</code>
Outputs:
<code html4strict>
<label>Form element</label>
</code>

This is a rather low-level function, you will rarely need to call it directly. Instead, use labels on subclasses of labelled_html_component:

<code php>
$field = new html_field();
$field->name = 'variable1';
$field->id = 'myfield';
$field->set_label('Form element');
echo $OUTPUT->textfield($field);
</code>
Outputs:
<code html4strict>
<span class="textfield variable1">
<label for="myfield">Form element</label>
<input id="myfield" type="text" style="width: 4em;" name="variable1"/>
</span>
</code>

==== link ====
<code php>
$link = new html_link();
$link->url = new moodle_url('http://domain.com/index.php', array('id' => 2, 'action' => 'browse')); // required, but you can use a string instead
$link->text = 'Browse page 2'; // Required
echo $OUTPUT->link($link)
</code>
Outputs:
<code html4strict>
<a href="http://domain.com/index.php?id=2&action=browse">Browse page 2</a>
</code>

==== link_to_popup ====
*Same API as for link(), but you set a popup_action on the component, and link() will forward it to the link_to_popup() method. You shouldn't need to call this method directly.
==== link ====
<code php>
$link = html_link::make(new moodle_url('http://domain.com/index.php', array('id' => 2, 'action' => 'browse')), 'Browse page 2');
$link->add_action(new popup_action('click', $link->url));
echo $OUTPUT->link($link)
</code>
Outputs:
<code html4strict>
<a id="html_link-985165" href="http://domain.com/index.php?id=2&action=browse">Browse page 2</a>
...
<script type="text/javascript">
//<![CDATA[
YAHOO.util.Event.addListener('html_link-985165', 'click', openpopup, {"url":"http:\/\/domain.com\/index.php?id=2&action=browse","name":"popup","options":"[...]"});
//]]>
</script>
</code>

==== notification ====
*By default this function works just like container(), with a default class set to 'notifyproblem'.
*It actually inserts a template token which is interpreted and rendered at a later stage.

==== paging_bar ====
<code php>
$pagingbar = moodle_paging_bar::make(120, 3, 20, 'http://domain.com/index.php');
// Optionally : $pagingbar->pagevar = 'mypage';
echo $OUTPUT->paging_bar($pagingbar);
</code>
Outputs:
<code html4strict>
<div class="paging">
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>
)
</div>
</code>

==== radio ====
==== select ====
*This method depends heavily on how the passed component is configured, so see [[Output_API#html_select]] For a detailed description

==== select_option ====
*Used internally by select(), you shouldn't need to call this directly.

==== spacer ====
==== table ====
<code php>
$table = new html_table();
$table->head = array('Student', 'Grade', 'Comments');
$table->data = array(
array('Harry Potter', '76%', 'Getting better'),
array('Rincewind', '89%', 'Lucky as usual'),
array('Elminster Aumar', '100%', 'Easy when you know everything!')
);
echo html_writer::table($table);
</code>
Outputs:
<code html4strict>
<table class="generaltable">
<thead>
<tr>
<th class="header c0" scope="col" style="white-space: nowrap;">Student</th>
<th class="header c1" scope="col" style="white-space: nowrap;">Grade</th>
<th class="header c2 lastcol" scope="col" style="white-space: nowrap;">Comments</th>
</tr>
</thead>
<tbody>
<tr class="r0">
<td class="cell">Harry Potter</td>
<td class="cell">76%</td>
<td class="cell">Getting better</td>
</tr>
<tr class="r1">
<td class="cell">Rincewind</td>
<td class="cell">89%</td>
<td class="cell">Lucky as usual</td>
</tr>
<tr class="r0 lastrow">
<td class="cell">Elminster Aumar</td>
<td class="cell">100%</td>
<td class="cell">Easy when you know everything!</td>
</tr>
</tbody>
</table>
</code>

==== textfield ====
==== user_picture ====
<code php>
$user = new stdClass();
$user->id = 1;
$userpic = new moodle_user_picture();
$userpic->user = $user;
$userpic->courseid = 1;

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

=== cli_core_renderer ===

== 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.
<code php>
$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);
</code>
*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==

* [[How_Moodle_outputs_HTML]]
* [[Migrating your code to the 2.0 rendering_API]]
* [[Outputting HTML in 2.0]]
* [[Theme_changes]]

Page API

2012-07-06T10:09:51Z

Simontite: /* Context */ equivilant -> equivalent

The Page API is used to set up the current page, add JavaScript, and configure how things will be displayed to the user.

==Overview==
The Page API is an integral part of any Moodle page. It also the developer to set things up they way they envisage it. Through the Page API you can set things like the title, initial heading, where the user is for the navigation, and which layout you think the page should use.

This document starts off with a simple example, and then proceeds to provide a more complete description of how to set up a page for display.

==A simple example==
This example covers how to set up a basic page for use within an activity plugin and is undoubtedly the simplest example as much of the work is done behind the scenes for you.
<code php>
// File: /mod/mymodulename/view.php
require_once('../../config.php');
$cmid = required_param('id', PARAM_INT);
$cm = get_coursemodule_from_id('mymodulename', $cmid, 0, false, MUST_EXIST);
$course = $DB->get_record('course', array('id' => $cm->course), '*', MUST_EXIST);

require_login($course, true, $cm);
$PAGE->set_url('/mod/mymodulename/view.php', array('id' => $cm->id));
$PAGE->set_title('My modules page title');
$PAGE->set_heading('My modules page heading');

// The rest of your code goes below this.
</code>
I'm going to assume you know what the first four lines are doing, if not you are starting in the wrong place.

So lets start at require_login and assume you already have the course and course module objects ready to use. When you call require_login part of the magic it does for you is set up the basic for the current page.<br />
In the case of the example above because require_login is given a course and course module it is already setting up much of the page for you. It is giving the course and course module objects to the page, setting the context for the page to the course modules context, and setting the page layout to ''incourse'' so that you get the standard look of a course module.

The set up that we are having to do is as follows:
# Set the URL for the page. This MUST be done.
# Set a title for the page. Most likely will be shown in the <title> tag.
# Set the heading for the page. Most likely used in the pages header.

It's important to mention that this has to be done before output starts. That means you must set up the page before the header is printed and before you instantiate any moodleform instances.

And that is it, if you were to add a bit of simple output there you would get a page that already looks like other module pages you would have seen. Simple as.

==$PAGE The Moodle page global==
For every page request Moodle sets up a couple of global structures that you will likely need. $DB the database object, and $CFG which stores configuration are two that you are likely already aware of. $PAGE is the focus of this article, it is a moodle_page instance that stores all of the information and is used by the output library $OUTPUT when displaying the page.<br />
It's important to note the difference between $PAGE and $OUTPUT, $PAGE is for setting up the page and $OUTPUT is for displaying the page. $PAGE contains lots of logic and magic, $OUTPUT is purely about display and does little more than produce HTML.

==Setting up the page==
When creating a page in Moodle there are a couple of things that you must set, and a couple of things that get set for you in many cases but not all of the time.

===URL===
This is an absolute must, failing to set this will lead Moodle to display an error that it has not been set.<br />
It can be set in the following manner:

<code php>
$PAGE->set_url(new moodle_url('/page/to/your/file.php', array('key' => 'value', 'id' => 3)));
$PAGE->set_url('/page/to/your/file.php', array('key' => 'value', 'id' => 3));
$PAGE->set_url('/page/to/your/file.php?key=value&id=3');
</code>

The above code sets the page URL 3 times, and highlights the 3 different ways you can set the URL. Either of the first two methods are the preferred way as it provides 100% accuracy when processing the URL. Internally set_url() converts what ever you give it to a moodle_url object.

The URL that you give to the page is going to be use by a lot of Moodle core API's. Most importantly it is going to be used to create the navigation for your page so it's very important you set it accurately.

===Context===
This is an absolute must as well, however in many cases it will be set for you magically by Moodle.

In order to set the context for the page you must provide a context object, in Moodle 2.2 and greater this will look as follows:
<code php>
// Moodle 2.2 and greater
$PAGE->set_context(context_system::instance());
$PAGE->set_context(context_coursecat::instance($categoryid));
$PAGE->set_context(context_course::instance($courseid));
$PAGE->set_context(context_module::instance($moduleid));
</code>

In Moodle 2.0+, and Moodle 2.1+ the following is the equivalent code:
<code php>
// Moodle 2.2 and greater
$PAGE->set_context(get_system_context());
$PAGE->set_context(get_context_instance(CONTEXT_COURSECAT, $categoryid));
$PAGE->set_context(get_context_instance(CONTEXT_COURSE, $courseid));
$PAGE->set_context(get_context_instance(CONTEXT_MODULE, $moduleid));
</code>

In both examples above setting different types of contexts has been illustrated however you should only ever call set_context() once with the context that is most appropriate to the page you are creating.<br />
If it is a plugin then the context to use would be the context you are using for your capability checks.

As mentioned above the other thing to be aware of is that in some circumstances this gets automatically set for you.<br />
If your script calls require_login (and most scripts have to) and you are providing a course, or a module to your require login call then you will not need to call set_context().<br />
This is because require_login handles it for you.

If your script doesn't call require_login, or you don't call it with a course and/or module then you will need to manually set the context as shown.

===Optional set up===
The following are optional extras you can set up against the PAGE object that you are likely to encounter throughout Moodle core, and are likely to want to use yourself.
====Page layout====
The following code sets the pages layout to the standard layout, the most generic layout in the arsenal.
<code php>
$PAGE->set_pagelayout('standard');
</code>
When setting the page layout you should use the layout that is the closest match to the page you are creating. Layouts are used by themes to determine what is is shown on the page. The most prominent difference between layouts is the block regions they support. The default layout `''base''` for example doesn't normally have any block regions at all, where as normally `''standard''` has the most generic layout and several block regions.

There are dozens of different layouts that can be, and are used throughout Moodle core that you can use within your code. For a full list of common layouts you are best too look at theme/base/config.php or refer to the list below.

Note: It's important to know that the theme determines what layouts are available and how each looks. If you select a layout that the theme doesn't support then it will revert to the default layout while using that theme.<br />Themes are also able to specify additional layouts, however its important to spot them and know that while they may work with one theme they are unlikely to work as you expect with other themes.

====Base theme page layouts====
The following is a list of the layouts defined by the base theme. Theme designers are encouraged to make the base theme a parent of their custom theme so you can be sure that in 99% of cases these layouts will be available.
{| class="nicetable"
|-
! Layout
! Description
|-
| base
| Most backwards compatible layout without the blocks. This is the layout used by default.
|-
| standard
| Standard layout with blocks, this is recommended for most pages with general information
|-
| course
| The course main page uses this layout.
|-
| coursecategory
| Category course listings.
|-
| incourse
| Used for areas within a course, typical for modules. Default page layout if $cm specified in require_login().
|-
| frontpage
| The site home page uses this.
|-
| admin
| Admin and settings pages as well as server administration scripts.
|-
| mydashboard
| The users dashboard.
|-
| mypublic
| A users public profile uses this layout.
|-
| login
| The login screen.
|-
| popup
| Pages that appear in popup windows, usually no navigation, blocks, or header.
|-
| frametop
| Used for the outermost content of a page constructed with frames. Usually no blocks and minimal footer.
|-
| embedded
| Embedded pages such as content for iframes/objects. Needs as much space as possible usually no blocks, header, or footer.
|-
| maintenance
| Used during upgrade, installation, and when maintenance mode is enabled.
|-
| print
| Gets used when printing a page. Normally just a simple header and no blocks.
|-
| redirect
| A special layout used during a redirect. Normally with content only.
|-
| report
| Used for reports within Moodle. Special layout designed to handle horizontal scrolling in a nice way.
|}

====Title====
Setting an appropriate title is certainly a must for any properly designed page. While it is optional it is highly recommended that you set the title.
<code php>
$PAGE->set_title('This is my title');
</code>
When setting the title for the page you need to provide just the string you want to use for the title. It should be a basic string and contain no HTML. Any HTML will be stripped out as the title is used within the <title> tag in the HTML head.

====Heading====
Like title it is highly recommended that you set a meaningful heading for the page, although it is optional.<br />The heading is normally displayed at the top of the page before the rest of the content starts. However it is up to the layout defined by the theme as to where it is displayed. Not all layouts will display a heading but I encourage you to always set one even if you are using a layout that doesn't support headings. This way if you are using a theme that uses a heading on every page regardless of layout things still look consistent.

<code php>
$PAGE->set_heading(get_string('pluginname', 'local_myplugin'), 3);
</code>

When setting a heading there is just one argument, the string to use for the heading. It should be a basic string and contain no HTML.

=== Advanced set up ===
The following are advanced optional methods you can call to further set up your page. In most cases you will never need to use these.

; set_activity_record : If you have called require_login with a course module, or you have manually set a course module on $PAGE then one other thing you may want to do is set the activity module record on $PAGE as well.<br />This is best done when you have already fetched the activity record yourself in which case manually setting the activity record may reduce the number of queries for the page by 1.
<code php>$PAGE->set_activity_record($activityrecord)</code>

; set_blocks_editing_capability : Using this method you can set an additional capability that users must posses before being able to edit blocks on this page.<br />By default 'moodle/site:manageblocks' is used however there are sometimes reasons to use a different capability.
<code php>$PAGE->set_blocks_editing_capability($strcapability)</code>

; set_button : This allows you to set some HTML that will be shown in the navigation bar where the `Turn on editing` button normally lives.
<code php>$PAGE->set_button($htmlstring)</code>

; set_cacheable : By setting this to false the page will be sent with headers to prevent the client from caching the page. Defaults to true.
<code php>$PAGE->set_cacheable(true/false)</code>

; set_category_by_id : Allows you to set a category that this page is displaying. Calling this will force the $PAGE->course to be set to the front page course.
<code php>$PAGE->set_category_by_id($categoryid)</code>

; set_cm : Like set page above, sometimes you need to manually set the course module for $PAGE. Again you must set the context to the context of the course module if you call this.
<code php>$PAGE->set_cm($coursemodulerecord)</code>

; set_course : This allows you to set the course the page belongs to. Normally when you call require_login the course you give it automatically gets sent to $PAGE for you.<br />However if you don't want to require login for the course, but you need it in $PAGE then you can call set_course and provide it.<br />Note that if you do this then you MUST use the context of the course when calling set_context().
<code php>$PAGE->set_course($courserecord)</code>

; set_docs_path : Normally this gets automatically constructed for you, however in some circumstances you may want to manually set it.<br />This allows you to have several pages that all point to the same docs page rather than requiring a docs page for each.<br />The docs page link is normally shown by a theme in the footer.
<code php>$PAGE->set_docs_path($strpath)</code>

; set_focuscontrol : If you pass this method an element id when the page loads on the client focus will be shifted to the element with the corresponding id.<br />Using this function is a REALLY bad idea in most situations because changing focus automatically in a browser is a nightmare for the vision impaired and those using screen readers.
<code php>$PAGE->set_focuscontrol($controlid)</code>

; set_headingmenu : This allows you to set some HTML that will be shown next to the pages main heading where the language select box normally lives.
<code php>$PAGE->set_headingmenu($htmlstring)</code>

; set_other_editing_capability : Can be used to set an additional capability that the user must posses before they can turn editing on for this page.<br />This is useful if you can an editing more for your page that is more than just editing blocks.
<code php>$PAGE->set_other_editing_capability($strcapability)</code>

; set_pagetype : This gets automatically set up for by default to the path of your file e.g. mod/mymod/index.php will set up as mod-mymod-index.<br />This is absolutely fine in 99% of cases however every now and again there is a reason to override it.
<code php>$PAGE->set_pagetype($strpagetype)</code>

; set_periodic_refresh_delay : If set a meta tag gets added to the page header causing it to refresh intermittently.<br />This is rarely needed but can be useful if you need to automatically refresh the likes of a chat page, or news feed.<br />Today it is not recommended to use this, but instead to create a means of getting additional content via AJAX.
<code php>$PAGE->set_periodic_refresh_delay($intdelay)</code>

; set_popup_notification_allowed : Allow or disallow popup notifications on this page. Things like messaging can cause messages to popup at the bottom of the screen sometimes.<br />On some pages this functionality is not desired and can be stopped by calling this method and using false as the first argument.<br />Popups are allowed by default.
<code php>$PAGE->set_popup_notification_allowed(true/false)</code>

; set_subpage : If context->id and pagetype are not enough to uniquely identify this page and you need to include another string to make it more unique you can do it by calling this method setting a custom sub page type.
<code php>$PAGE->set_subpage($strsubpage)</code>

; add_body_class : Adds a CSS class to the body tag that will be printed by the Output API as part of the header.<br />This is useful for adding classes to the body tag that describe the content of the page and may be required for styling the whole page, or for including indicator classes that may be useful to look for in JavaScript.
<code php>$PAGE->add_body_class($strcssclass)</code>

; add_body_classes : Adds an array of CSS classes to the body tag. Have a look at the above comment for '''add_body_class''' for more details.
<code php>$PAGE->add_body_classes($arrayofclasses)</code>

==Getting information about the page==
As well of setting up the page you can of course get information back from it about the page it has been set up to display.<br />
Anything you set against the page can be retrieved as can any information that was set magically for you by other methods.

The following are the most interesting and likely useful things you can get back from the page.

; activityrecord : The activityrecord will be the record from the database that relates to the cm that was set by require_login, or manually by your code.<br />For example if you provided a $cm instance that related to a forum this will be a row from the forum table.
<code php>$var = $PAGE->activityrecord;</code>

; blockmanager : This is the block manager responsible for loading the all of the blocks that will be shown on the page.<br />For more information see the [[Blocks API]].
<code php>$var = $PAGE->blockmanager;</code>

; bodyid : The id that will be given to the body tag when the page is displayed.
<code php>$var = $PAGE->bodyid</code>

; categories : An array of all the categories the page course belongs to, starting with the immediately containing category.
<code php>$var = $PAGE->categories</code>

; category : The category that the page course belongs to.
<code php>$var = $PAGE->category</code>

; cm : The course module that has been set for the page.
<code php>$var = $PAGE->cm</code>

; course : The course that has been set for the page.
<code php>$var = $PAGE->course</code>

; devicetypeinuse : The device the user is using browse the page.
<code php>$var = $PAGE->devicetypeinuse</code>

; headerprinted : Is true if the page header has already been printed.
<code php>$var = $PAGE->headerprinted</code>

; heading : The page heading.
<code php>$var = $PAGE->heading</code>

; navbar : Gets a reference to the pages navigation bar so that you can interact with that. See the [[Navigation API]] for more information.
<code php>$var = $PAGE->navbar</code>

; navigation : Gets a reference to the navigation for the page. See the [[Navigation API]] for more information.
<code php>$var = $PAGE-></code>

; requires : Gets the page requirements manager that handles any JavaScript and special CSS requirements for the page.
<code php>$var = $PAGE->requires</code>

; settingsnav : Gets the settings navigation for the page. See the [[Navigation API]] for more information.
<code php>$var = $PAGE->settingsnav</code>

; theme : Gets the theme that is being used for the page. Is a theme_config object.
<code php>$var = $PAGE->theme</code>

; title : Gets the title for the page.
<code php>$var = $PAGE->title</code>

; url : Gets the URL that was set for the page. Is a moodle_url object.
<code php>$var = $PAGE->url</code>

==FAQs==

; I don't have any blocks on my page? : This has happened because you have not set a page layout that uses blocks OR you have set it after output has started. Once output has started you cannot change integral aspects of that page that are used for the initial output. Included is the page title, heading, url and layout.

; I am getting a notice about not having set the page URL but I have set it? : As above you must set up the page before output starts, trying to do so will lead to notices and developer warnings about having things in the wrong order.

; What starts output? : Output starts when either the script calls echo $OUTPUT->header OR a moodleform is instantiated.

==Related API's==
There are a couple of API's that are closely related to the Page API that you should be aware of as well.

===Output API===
The output API is an immediate relation of the page API. The page API is about setting things up, whereas the output API is all about displaying things.
It's through the output API that content is actually produced, and much of the information you set up through the page is used to customise what is produced, and fill in the general blanks of any page (such as title and heading.

See the [[Output API]] documentation for more information.

===Page requirements API===
The page requirements API allows you the developer to include additional CSS, and JavaScript resources that should be included with the page, and to include JavaScript calls within the page through a variety of means.
Technically this API is part of the Output API mentioned above, however it deserves special mention. If you are going to be using any JavaScript or CSS within your page you will need to know about this.

See the [[Output API]] documentation for more information on the page requirements API.

===Navigation API===
The final API to mention is the navigation API. This again is integral to both the page and output API and is used to recognise the context of the content being displayed and ensure that the correct blocks and navigaiton structure are loaded for the context.
There is a good chance that you will encounter a need to customise the navigation early on in plugin page development and it's important to be aware of this important API.

See the [[Navigation API]] documentation for more information on the page requirements API.

==See also==

* [[Core APIs]] : A list of all the core API's in Moodle.
* [[Output API]] : The Output API.
* [[Navigation API]] : The Navigation API.
* [http://moodle.org/mod/forum/view.php?id=55 General developer forum] : The place to ask question you may have about the Page API.
* MDL-30977 : The issue to see the Page API properly documented.

[[Category:API]]

Blocks

2012-06-28T11:48:22Z

Simontite: /* See also */ Blocks Advanced A continuation of this tutorial.

''' A Step-by-step Guide To Creating Blocks '''

Original Author: Jon Papaioannou ([mailto:pj@moodle.org pj@moodle.org])

Updated to Moodle 2.0 and above by: Greg J Preece ([mailto:greg.preece@blackboard.com greg.preece@blackboard.com])

{{Moodle 2.0}}

The present document serves as a guide to developers who want to create their own blocks for use in Moodle. It applies to the 2.0 development version of Moodle (and any newer) '''only''', as the blocks API changed significantly enough to warrant new documentation. Those wishing to read the old tutorial for Moodles 1.5 to 1.9 can find it under [[Blocks/Blocks for 1.5 to 1.9| Blocks for 1.5 to 1.9]].

The guide is written as an interactive course which aims to develop a configurable, multi-purpose block that displays arbitrary HTML. It's targeted mainly at people with little experience with Moodle or programming in general and aims to show how easy it is to create new blocks for Moodle. A certain small amount of PHP programming knowledge is still required, though.

Experienced developers and those who just want a '''programmer's reference''' text should refer to [[Blocks/Appendix_A| Appendix A]] because the main guide has a rather low concentration of pure information in the text.

== Basic Concepts ==

Through this guide, we will be following the creation of an "HTML" block from scratch in order to demonstrate most of the block features at our disposal. Our block will be named "SimpleHTML". This does not constrain us regarding the name of the actual directory on the server where the files for our block will be stored, but for consistency we will follow the practice of using the lowercased form "simplehtml" in any case where such a name is required.

Whenever we refer to a file or directory name which contains "simplehtml", it's important to remember that ''only'' the "simplehtml" part is up to us to change; the rest is standardised and essential for Moodle to work correctly.

Whenever a file's path is mentioned in this guide, it will always start with a slash. This refers to the Moodle home directory; all files and directories will be referred to with respect to that directory.

== Ready, Set, Go! ==

To define a "block" in Moodle, in the most basic case we need to provide just three PHP files:

; /blocks/simplehtml/block_simplehtml.php : This file will hold the class definition for the block, and is used both to manage it as a plugin and to render it onscreen.

; /blocks/simplehtml/version.php : This file will hold version information for the plugin, along with other advanced parameters (not covered here - see [[version.php]] if you want more details).

; /blocks/simplehtml/lang/en/block_simplehtml.php : This is the English language file for your block. If you are not an English speaker, you can replace 'en' with your appropriate language code. All language files for blocks go under the /lang subfolder of the block's installation folder.

We start by creating the directory ''/blocks/simplehtml/'' and creating the main object file, ''/blocks/simplehtml/'''''block_simplehtml.php'''. We then begin coding the block:

<code php>
<?php
class block_simplehtml extends block_base {
public function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
}
// The PHP tag and the curly bracket for the class definition
// will only be closed after there is another function added in the next section.
</code>

The first line is our block class definition; it must be named exactly in the manner shown. Again, only the "simplehtml" part can (and indeed must) change; everything else is standardised.

Our class is then given a small method: [[Blocks/Appendix_A#init.28.29| init()]]. This is essential for all blocks, and its purpose is to give values to any class member variables that need instantiating.

In this very basic example, we only want to set [[Blocks/Appendix_A#.24this-.3Etitle| $this->title]], which is the title displayed in the header of our block. We can set it to whatever we like; in this case it's set to read the actual title from the language file mentioned previously, which is then distributed along with the block. I'll skip ahead a bit here and say that if you want your block to display '''no''' title at all, then you should set this to any descriptive value you want (but '''not''' make it an empty string). We will later see [[Blocks#Eye_Candy|how to disable the title's display]].

The second file we will need to construct our block skeleton is a version file. Prior to Moodle 2.0, version details for blocks were stored as class fields; as of Moodle 2.0 these are stored in a file called version.php, stored under ''/blocks/simplehtml/'''version.php'''''. The version file is very simple indeed, containing only a few field definitions, depending on your needs. Here is an example:
<code php>
<?php
$plugin->version = 2011062800; // YYYYMMDDHH (year, month, day, 24-hr time)
$plugin->requires = 2010112400; // YYYYMMDDHH (This is the release version for Moodle 2.0)
</code>

This file contains object field definitions that denote the version number of the block, along with the minimum version of Moodle that must be installed in order to use it. Please note that the object being used here is ''always'' called '''$plugin''', and that you do not need to create this object yourself within the version file. Note also that we didnt include the closing "?>" tag for PHP. This is intentional, and a [[Coding_style#PHP_tags | workaround for whitespace issues]].

Moodle 2.0 and above also require a name for our plugin to show in the upgrading page. We set this value, along with any other language strings we wish to use within the block, in a language package as previously mentioned (the same file where we put our string for the plugin title). Now we will create this language package. Create the file ''/blocks/simplehtml/lang/en/'''''block_simplehtml.php''' and paste the following code:

<code php>
<?php
$string['pluginname'] = 'Simple html block';
$string['simplehtml'] = 'Simple html';
</code>

{{Top}}

== I Just Hear Static ==
In order to get our block to actually display something on screen, we need to add one more method to our class (before the final closing brace in our file). The new code is:

<code php>
public function get_content() {
if ($this->content !== null) {
return $this->content;
}

$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';

return $this->content;
}
} // Here's the closing bracket for the class definition

</code>

It can't get any simpler than that, can it? Let's dissect this method to see what's going on...

First of all, there is a check that returns the current value of [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]] if it's not NULL; otherwise we proceed with "computing" it. Since the computation is potentially a time-consuming operation and it '''will''' be called several times for each block (Moodle works that way internally), we take a precaution and include this time-saver.
Supposing the content had not been computed before (it was NULL), we then define it from scratch. The code speaks for itself there, so there isn't much to say. Just keep in mind that we can use HTML both in the text '''and''' in the footer, if we want to.

It's worth mentioning that this is not the only type of content a block can output. You can also create lists and hierarchical trees, which are better suited for certain types of output, such as menus. These different content types have an impact on the content object and how it is constructed. For more information, see [[Blocks/Appendix A#.24this-.3Econtent_type|Appendix A]]

At this point our block should be capable of being automatically installed in Moodle and added to courses; visit your administration page to install it (Click "Notifications" under the Site Administration Block) and after seeing it in action come back to continue our tutorial.

== Configure That Out ==

The current version of our block doesn't really do much; it just displays a fixed message, which is not very useful. What we'd really like to do is allow the teachers to customize what goes into the block. This, in block-speak, is called "instance configuration". Basic instance configuration is automatic in Moodle 2.0; if you put any page with blocks on it into "editing mode", you will notice that each block has an edit button in its title bar. Clicking on this will take you to the block configuration form. The settings that Moodle adds to this form by default relate to the block's appearance and position on Moodle pages.

We can extend this configuration form, and add custom preferences fields, so that users can better tailor our block to a given task or page. To extend the configuration form, create the file <span class="filename">/blocks/simplehtml/'''edit_form.php'''</span>, and fill it with the following code:

<code php>
<?php

class block_simplehtml_edit_form extends block_edit_form {

protected function specific_definition($mform) {

// Section header title according to language file.
$mform->addElement('header', 'configheader', get_string('blocksettings', 'block'));

// A sample string variable with a default value.
$mform->addElement('text', 'config_text', get_string('blockstring', 'block_simplehtml'));
$mform->setDefault('config_text', 'default value');
$mform->setType('config_text', PARAM_MULTILANG);

}
}
</code>
The first line declares a class that inherits '''from block_edit_form''', and this allows Moodle to identify the code to execute in the configuration page. The '''specific_definition()''' method is where your form elements are defined, and these take the same format as with the standard [[lib/formslib.php_Form_Definition|Moodle form library]]. Within our specific_definition method, we have created a header, and an input field which will accept text to be used within the block.

IMPORTANT: All your field names need to start with "config_", otherwise they will not be saved and will not be available within the block via [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]].

So once our instance configuration form has been saved, we can use the inputted text within the block like so:

<code php>
if (! empty($this->config->text)) {
$this->content->text = $this->config->text;
}
</code>

Note that [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] is available in all block methods ''except'' [[Blocks/Appendix_A#init.28.29|init()]]. This is because [[Blocks/Appendix_A#init.28.29|init()]] is called immediately as the block is being created, with the purpose of setting things up, so [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] has not yet been instantiated.

'''Note about Checkbox:''' You cannot use the 'checkbox' element in the form (once set it will stay set). You must use advcheckbox instead.

{{Top}}

== The Specialists ==

Implementing instance configuration for the block's contents was good enough to whet our appetite, but who wants to stop there? Why not customize the block's title, too?

Why not, indeed. Well, our first attempt to achieve this is natural enough: let's add another field to ''/blocks/simplehtml/'''edit_form.php'''''. Here goes:

<code php>
// A sample string variable with a default value.
$mform->addElement('text', 'config_title', get_string('blocktitle', 'block_simplehtml'));
$mform->setDefault('config_title', 'default value');
$mform->setType('config_title', PARAM_MULTILANG);
</code>

We save the edited file, go to a course, edit the title of the block and... nothing happens! The instance configuration is saved correctly, all right (editing it once more proves that) but it's not being displayed. All we get is just the simple "SimpleHTML" title.

That's not too weird, if we think back a bit. Do you remember that [[Blocks/Appendix_A#init.28.29|init()]] method, where we set [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]]? We didn't actually change its value from then, and [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]] is definitely not the same as '''$this->config->title''' (to Moodle, at least). What we need is a way to update [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]] with the value in the instance configuration. But as we said a bit earlier, we can use [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] in all methods ''except'' [[Blocks/Appendix_A#init.28.29|init()]]! So what can we do?

Let's pull out another ace from our sleeve, and add this small method to our block class:

<code php>
public function specialization() {
if (!empty($this->config->title)) {
$this->title = $this->config->title;
} else {
$this->config->title = 'Default title ...';
}

if (empty($this->config->text)) {
$this->config->text = 'Default text ...';
}
}
</code>

Aha, here's what we wanted to do all along! But what's going on with the [[Blocks/Appendix_A#specialization.28.29| specialization()]] method?

This "magic" method has actually a very nice property: it's ''guaranteed'' to be automatically called by Moodle as soon as our instance configuration is loaded and available (that is, immediately after [[Blocks/Appendix_A#init.28.29|init()]] is called). That means before the block's content is computed for the first time, and indeed before ''anything'' else is done with the block. Thus, providing a [[Blocks/Appendix_A#specialization.28.29| specialization()]] method is the natural choice for any configuration data that needs to be acted upon or made available "as soon as possible", as in this case.

{{Top}}

== Now You See Me, Now You Don't ==

Now would be a good time to mention another nifty technique that can be used in blocks, and which comes in handy quite often. Specifically, it may be the case that our block will have something interesting to display some of the time; but in some other cases, it won't have anything useful to say. An example here would be the "Recent Activity" block, in the case where no recent activity in fact exists.

However in that case the block chooses to explicitly inform you of the lack of said activity, which is arguably useful. It would be nice, then, to be able to have our block "disappear" if it's not needed to display it.

This is indeed possible, and the way to do it is to make sure that after the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method is called, the block has no content to display. This means that all fields in $this->content should be equal to the empty string (<nowiki>''</nowiki>). In the case of our HTML-based block, these fields are $this->content->text and $this->content->footer. Moodle performs this check by calling the block's [[Blocks/Appendix_A#is_empty.28.29| is_empty()]] method, and if the block is indeed empty then it is not displayed at all.

Note that the exact value of the block's title and the presence or absence of a [[Blocks/Appendix_A#hide_header.28.29| hide_header()]] method do ''not'' affect this behavior. A block is considered empty if it has no content, irrespective of anything else.

{{Top}}

== We Are Legion ==

Right now our block is fully configurable, both in title and content. It's so versatile, in fact, that we could make pretty much anything out of it. It would be really nice to be able to add multiple blocks of this type to a single course. And, as you might have guessed, doing that is as simple as adding another small method to our block class:

<code php>
public function instance_allow_multiple() {
return true;
}
</code>

This tells Moodle that it should allow any number of instances of the SimpleHTML block in any course. After saving the changes to our file, Moodle immediately allows us to add multiple copies of the block without further ado!

Please note that even if a block itself allows multiple instances in the same page, the administrator still has the option of disallowing such behavior. This setting can be set separately for each block from the Administration / Configuration / Blocks page.

{{Top}}

== The Effects of Globalization ==

Configuring each block instance with its own personal data is cool enough, but sometimes administrators need some way to "touch" all instances of a specific block at the same time. In the case of our SimpleHTML block, a few settings that would make sense to apply to all instances aren't that hard to come up with.

For example, we might want to limit the contents of each block to only so many characters, or we might have a setting that filters HTML out of the block's contents, only allowing pure text in. Granted, such a feature wouldn't win us any awards for naming our block "SimpleHTML" but some tormented administrator somewhere might actually find it useful.

This kind of configuration is called "global configuration" and applies only to a specific block type (all instances of that block type are affected, however). Implementing such configuration for our block is quite similar to implementing the instance configuration. We will now see how to implement the second example, having a setting that only allows text and not HTML in the block's contents. To enable global configuration for the block, we create a new file, ''/blocks/simplehtml/'''settings.php''''', and populate it with form field definitions for each setting, which Moodle will use to generate and handle a global settings form. This is quite similar in concept to how we generated the instance configuration form earlier, but the actual code used to generate the form and fields is somewhat different.

Place the following in your settings.php file:

<code php>
$settings->add(new admin_setting_heading(
'headerconfig',
get_string('headerconfig', 'block_simplehtml'),
get_string('descconfig', 'block_simplehtml')
));

$settings->add(new admin_setting_configcheckbox(
'simplehtml/Allow_HTML',
get_string('labelallowhtml', 'block_simplehtml'),
get_string('descallowhtml', 'block_simplehtml'),
'0'
));
</code>

As you can see, to generate a global configuration form, we simply create admin setting objects and add them to an array. This array is then stepped over to create the settings form, and the inputted data is automatically saved to the database. Full details of the setting types available and how to add them can be found under [[Admin_settings#Individual_settings]].

We've now created a header and checkbox form element to accept configuration details from the site admin. You should pay extra attention to the name of our checkbox element, ''' 'simplehtml/Allow_HTML' ''', as it specifies not only the name of the configuration option, but also how it should be stored. If you simply specify a name for the config option, it will be stored in the global $CFG object, and in the ''<prefix>_config'' database table. This will make your config variable available immediately via $CFG without requiring an additional database call, but will also increase the size of the $CFG object. In addition, we must prefix the variable with the name of our block, otherwise we run the risk of our config variable sharing its name with a similar variable in another plugin, or within Moodle itself.

The preferred method of storing your block's configuration data is to prefix each config variable name in your settings.php file with your block's name, followed by a slash ( / ), and the name of the configuration variable, as we have done above. If you write your settings.php file in this way, then your variables will be stored in the ''<prefix>_config_plugin'' table, under your block's name. Your config data will still be available via a '''get_config()''' call, and name collision will be impossible between plugins.

Finally, if you're wondering why there are two language tags specified for each element, the first tag is for the element's label or primary text, and the second tag is for its description. And that's it. Pretty easy, huh?

'''NOTE FOR UPGRADERS'''

You'll notice that the settings.php file and parsed element names replaces Moodle's old storage method, wherein it would send all the configuration data to your block's [[Blocks/Appendix_A#config_save.28.29|config_save()]] method, and allow you to override how the data is saved. The [[Blocks/Appendix_A#config_save.28.29|config_save()]] method is no longer used in Moodle 2.x; however the [[Blocks/Appendix_A#instance_config_save.28.29|instance_config_save()]] method is very much alive and well, as you will see shortly.

{{Top}}

=== Accessing Global Config Data ===

Now that we have global data defined for the plugin, we need to know how to access it within our code. If you saved your config variables in the global namespace, you can access them from the global $CFG object, like so:

<code php>
$allowHTML = $CFG->Allow_HTML;
</code>

If, as recommended, you saved your config variables in a custom namespace for your block, then you can access them via a call to '''get_config()''':

<code php>
$allowHTML = get_config('simplehtml', 'Allow_HTML');
</code>

{{Top}}

=== Rolling It All Together ===

OK, so we now have an instance configuration form that allows users to enter custom content text for a block, and a global configuration option that dictates whether or not that user should be allowed to enter HTML tags as part of the content. Now we just need to tie the two together. But if Moodle takes care of the form processing for our instance configuration in edit_form.php, how can we capture it and remove the HTML tags where required?

Well, fortunately, there is a way this can be done. By overriding the [[Blocks/Appendix_A#instance_config_save.28.29| instance_config_save()]] method in our block class, we can modify the way in which instance configuration data is stored after input. The default implementation is as follows:

<code php>
public function instance_config_save($data) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance',
'configdata',
base64_encode(serialize($data)),
'id',
$this->instance->id);
}
</code>

This may look intimidating at first (what's all this stripslashes_recursive() and base64_encode() and serialize() stuff?) but do not despair; we won't have to touch any of it. We will only add some extra validation code in the beginning and then instruct Moodle to additionally call this default implementation to do the actual storing of the data. Specifically, we will add a method to our class which goes like this:

<code php>
public function instance_config_save($data) {
if(get_config('simplehtml', 'Allow_HTML') == '1') {
$data->text = strip_tags($data->text);
}

// And now forward to the default implementation defined in the parent class
return parent::instance_config_save($data);
}
</code>

(This example assumes you are using a custom namespace for the block.)

At last! Now the administrator has absolute power of life and death over what type of content is allowed in our "SimpleHTML" block! Absolute? Well... not exactly. In fact, if we think about it for a while, it will become apparent that if at some point in time HTML is allowed and some blocks have saved their content with HTML included, and afterwards the administrator changes the setting to "off", this will only prevent subsequent content changes from including HTML. Blocks which already had HTML in their content would continue to display it!

Following that train of thought, the next stop is realizing that we wouldn't have this problem if we had chosen the lazy approach a while back, because in that case we would "sanitize" each block's content just before it was displayed.

The only thing we can do with the eager approach is strip all the tags from the content of all SimpleHTML instances as soon as the admin setting is changed to "HTML off"; but even then, turning the setting back to "HTML on" won't bring back the tags we stripped away. On the other hand, the lazy approach might be slower, but it's more versatile; we can choose whether to strip or keep the HTML before displaying the content, and we won't lose it at all if the admin toggles the setting off and on again. Isn't the life of a developer simple and wonderful?

=== Exercise ===
We will let this part of the tutorial come to a close with the obligatory exercise for the reader:
In order to have the SimpleHTML block work "correctly", find out how to strengthen the eager approach to strip out all tags from the existing configuration of all instances of our block, '''or''' go back and implement the lazy approach instead.
(Hint: Do that in the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method.)

{{Top}}

== Eye Candy ==

Our block is just about complete functionally, so now let's take a look at some of the tricks we can use to make its behavior customized in a few more useful ways.

First of all, there are a couple of ways we can adjust the visual aspects of our block. For starters, it might be useful to create a block that doesn't display a header (title) at all. You can see this effect in action in the Course Description block that comes with Moodle. This behavior is achieved by, you guessed it, adding one more method to our block class:

<code php>
public function hide_header() {
return true;
}
</code>

One more note here: we cannot just set an empty title inside the block's [[Blocks/Appendix_A#init.28.29| init()]] method; it's necessary for each block to have a unique, non-empty title after [[Blocks/Appendix_A#init.28.29| init()]] is called so that Moodle can use those titles to differentiate between all of the installed blocks.

Next, we can affect some properties of the actual HTML that will be used to print our block. Each block is fully contained within a <div> or <table> elements, inside which all the HTML for that block is printed. We can instruct Moodle to add HTML attributes with specific values to that container. This is generally done to give us freedom to customize the end result using CSS (this is in fact done by default as we'll see below).

The default behavior of this feature in our case will modify our block's "class" HTML attribute by appending the value "block_simplehtml" (the prefix "block_" followed by the name of our block, lowercased). We can then use that class to make CSS selectors in our theme to alter this block's visual style (for example, ".block_simplehtml { border: 1px black solid}").

To change the default behavior, we will need to define a method which returns an associative array of attribute names and values. For example:

<code php>
public function html_attributes() {
$attributes = parent::html_attributes(); // Get default values
$attributes['class'] .= ' block_'. $this->name(); // Append our class to class attribute
return $attributes;
}
</code>

This results in the block having all its normal HTML attributes, as inherited from the base block class, plus our additional class name. We can now use this class name to change the style of the block, add JavaScript events to it via YUI, and so on. And for one final elegant touch, we have not set the class to the hard-coded value "block_simplehtml", but instead used the [[Blocks/Appendix_A#name.28.29| name()]] method to make it dynamically match our block's name.

{{Top}}

== Authorized Personnel Only ==

Some blocks are useful in some circumstances, but not in others. An example of this would be the "Social Activities" block, which is useful in courses with the "social" course format, but not courses with the "weeks" format. What we need to be able to do is limit our block's availability, so that it can only be selected on pages where its content or abilities are appropriate.

Moodle allows us to declare which page formats a block is available on, and enforces these restrictions as set by the block's developer at all times. The information is given to Moodle as a standard associative array, with each key corresponding to a page format and defining a boolean value (true/false) that declares whether the block should be allowed to appear in that page format.

Notice the deliberate use of the term ''page'' instead of ''course'' in the above paragraph. This is because in Moodle 1.5 and onwards, blocks can be displayed in any page that supports them. The best example of such pages are the course pages, but we are not restricted to them. For instance, the quiz view page (the first one we see when we click on the name of the quiz) also supports blocks.

The format names we can use for the pages derive from the name of the script which is actually used to display that page. For example, when we are looking at a course, the script is <span class="filename">/course/view.php</span> (this is evident from the browser's address line). Thus, the format name of that page is '''course-view'''. It follows easily that the format name for a quiz view page is '''mod-quiz-view'''. This rule of thumb does have a few exceptions, however:

# The format name for the front page of Moodle is '''site-index'''.
# The format name for courses is actually not just '''course-view'''<nowiki>; it is </nowiki>'''course-view-weeks''', '''course-view-topics''', etc.
# Even though there is no such page, the format name '''all''' can be used as a catch-all option.

We can include as many format names as we want in our definition of the applicable formats. Each format can be allowed or disallowed, and there are also three more rules that help resolve the question "is this block allowed into this page or not?":

# Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
# The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
# The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
# The order that the format names appear does not make any difference.
All of the above are enough to make the situation sound complex, so let's look at some specific examples. First of all, to have our block appear '''only''' in the site front page, we would use:

<code php>
public function applicable_formats() {
return array('site' => true);
}
</code>

Since '''all''' is missing, the block is disallowed from appearing in ''any'' course format; but then '''site''' is set to TRUE, so it's explicitly allowed to appear in the site front page (remember that '''site''' matches '''site-index''' because it's a prefix).

For another example, if we wanted to allow the block to appear in all course formats ''except'' social, and also to ''not'' be allowed anywhere but in courses, we would use:

<code php>
public function applicable_formats() {
return array(
'course-view' => true,
'course-view-social' => false);
}
</code>

This time, we first allow the block to appear in all courses and then we explicitly disallow the social format.
For our final, most complicated example, suppose that a block can be displayed in the site front page, in courses (but not social courses) and also when we are viewing any activity module, ''except'' quiz. This would be:

<code php>
public function applicable_formats() {
return array(
'site-index' => true,
'course-view' => true,
'course-view-social' => false,
'mod' => true,
'mod-quiz' => false
);
}
</code>

It is not difficult to realize that the above accomplishes the objective if we remember that there is a "best match" policy to determine the end result.

{{Top}}

== Responding to Cron ==

It is possible to have our block respond to the global Moodle cron process; we can have a method that is run at regular intervals regardless of user interaction. There are two parts to this. Firstly we need to define a new function within our block class:

<code php>
public function cron() {
mtrace( "Hey, my cron script is running" );

// do something

return true;
}
</code>

Then we will need to set the (minimum) execution interval for our cron function. Prior to Moodle 2.0, this was achieved by setting the value of a block's $this->cron field, via the init() method. This is now achieved by adding an additional line to our ''/blocks/simplehtml/'''version.php''''' file. Open it up and add the following:

<code php>
$plugin->cron = 300;
</code>

Cron intervals are set in seconds, so the above line will set our minimum execution interval to 5 minutes. However, the function can only be called as frequently as cron has been set to run in the Moodle installation. So if our block is set to wait at least 5 minutes between runs, as in this example, but Moodle's cron system is only set to run every 24 hours, then our block is going to be waiting a lot longer between runs than we expected!

Remember that if we change any values in the version file or block file we '''must''' bump the version number and visit the Notifications page to upgrade the block, otherwise they will be ignored.

'''NOTE:'''
The block cron is designed to call the cron script for that block '''type''' only. That is, cron does not care about individual instances of blocks. Inside your cron function ''$this'' is defined, but it has almost nothing in it (only title and content fields are populated). If you need to execute cron for individual instances it is your own responsibility to iterate over them in the block's cron function. Example:

<code php>
public function cron() {

global $DB; // Global database object

// Get the instances of the block
$instances = $DB->get_records( 'block_instance', array('blockid'=>'simplehtml') );

// Iterate over the instances
foreach ($instances as $instance) {

// Recreate block object
$block = block_instance('simplehtml', $instance);

// $block is now the equivalent of $this in 'normal' block
// usage, e.g.
$someconfigitem = $block->config->item2;
}
}
</code>

TIP: This also means that creating a block is a possible way to create code that can respond to cron with a reasonably low overhead. No actual instances of the block are required.

{{Top}}

== Additional Content Types ==

=== Lists ===

In this final part of the guide we will briefly discuss several additional capabilities of Moodle's block system, namely the ability to create blocks that display different kinds of content to the user. The first of these creates a list of options and displays them to the user. This list is displayed with one item per line, and an optional image (icon) next to the item. An example of such a ''list block'' is the standard Moodle "admin" block, which illustrates all the points discussed in this section.

As we have seen so far, blocks use two properties of [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]]: "text" and "footer". The text is displayed as-is as the block content, and the footer is displayed below the content in a smaller font size. List blocks use $this->content->footer in the exact same way, but they ignore $this->content->text.

Instead, Moodle expects such blocks to set two other properties when the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method is called: $this->content->items and $this->content->icons. $this->content->items should be a numerically indexed array containing elements that represent the HTML for each item in the list that is going to be displayed. Usually these items will be HTML anchor tags which provide links to some page. $this->content->icons should also be a numerically indexed array, with exactly as many items as $this->content->items has. Each of these items should be a fully qualified HTML <img> tag, with "src", "height", "width" and "alt" attributes. Obviously, it makes sense to keep the images small and of a uniform size. We would recommend standard 16x16 images for this purpose.

In order to tell Moodle that we want to have a list block instead of the standard text block, we need to make a small change to our block class declaration. Instead of extending class '''block_base''', our block will extend class '''block_list'''. For example:

<code php>
class block_my_menu extends block_list {
// The init() method does not need to change at all
}
</code>

In addition to making this change, we must of course also modify the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method to construct the [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]] variable as discussed above:

<code php>
public function get_content() {
if ($this->content !== null) {
return $this->content;
}

$this->content = new stdClass;
$this->content->items = array();
$this->content->icons = array();
$this->content->footer = 'Footer here...';

$this->content->items[] = html_writer::tag('a', 'Menu Option 1', array('href' => 'some_file.php'));
$this->content->icons[] = html_writer::empty_tag('img', array('src' => 'images/icons/1.gif', 'class' => 'icon'));

// Add more list items here

return $this->content;
}
</code>

To summarise, if we want to create a list block instead of a text block, we just need to change the block class declaration and the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method. Adding the mandatory [[Blocks/Appendix_A#init.28.29| init()]] method as discussed earlier will then give us our first list block in no time!

=== Trees ===

As of 23rd December 2011, this functionality remains inoperable in all Moodle 2.x versions. It appears that classes are missing from the code base. This has been added to the tracker at the URL below. Please upvote this issue if you require this functionality.

[http://tracker.moodle.org/browse/MDL-28289 Visit this issue on the tracker @ MDL28289]

{{Top}}

== Database support ==
In case we need to have a database table that holds some specific information used within our block, we will need to create the file ''/blocks/simplehtml/'''install.xml''''' with the table schema contained within it.

To create the install.xml file, use the [[XMLDB editor]]. See [[Database_FAQ#XMLDB|Database FAQ > XMLDB]] for further details.

Up-to-date documentation on upgrading our block, as well as providing new capabilities and events to the system, can be found under [https://docs.moodle.org/dev/Installing_and_upgrading_plugin_database_tables#install.php Installing and Upgrading Plugin Database Tables]

== See also ==
* [[Blocks Advanced]] A continuation of this tutorial.
* [http://dev.moodle.org/mod/resource/view.php?id=48 Unit 7 of the Introduction to Moodle Programming course] is a follow up to this course. (But you should follow the forum discussions of that course closely as there are still some bugs and inconsistencies.)
* A [http://cvs.moodle.org/contrib/plugins/blocks/NEWBLOCK/ NEWBLOCK template] you can all use to start you own block.

== Appendices ==

The appendices have been moved to separate pages:

* Appendix A: [[Blocks/Appendix A|''block_base'' Reference]]

{{Top}}

[[Category:Blocks]]
[[Category:Tutorial]]

[[es:Desarrollo de bloques]]
[[ja:開発:ブロック]]
[[:en:Blocks|Blocks]]

[[Category:Plugins]]