<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
* Please see http://docs.moodle.org/en/Developement:How_Moodle_outputs_HTML
* for an overview.
*
- * @package core
- * @subpackage lib
- * @copyright 2009 Nicolas Connault
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package core
+ * @category output
+ * @copyright 2009 Nicolas Connault
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
defined('MOODLE_INTERNAL') || die();
* Helper class used by other components that involve an action on the page (URL or JS).
*
* @copyright 2009 Nicolas Connault
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class component_action {
/**
- * The DOM event that will trigger this action when caught
- * @var string $event DOM event
+ * @var string $event The DOM event that will trigger this action when caught
*/
public $event;
/**
+ * @var string A function name to call when the button is clicked
* The JS function you create must have two arguments:
* 1. The event object
* 2. An object/array of arguments ($jsfunctionargs)
- * @var string $jsfunction A function name to call when the button is clicked
*/
public $jsfunction = false;
/**
- * @var array $jsfunctionargs An array of arguments to pass to the JS function
+ * @var array An array of arguments to pass to the JS function
*/
public $jsfunctionargs = array();
/**
* Constructor
* @param string $event DOM event
- * @param moodle_url $url A moodle_url object, required if no jsfunction is given
- * @param string $method 'post' or 'get'
* @param string $jsfunction An optional JS function. Required if jsfunctionargs is given
- * @param array $jsfunctionargs An array of arguments to pass to the jsfunction
- * @return void
+ * @param array $jsfunctionargs An array of arguments to pass to the jsfunction
*/
public function __construct($event, $jsfunction, $jsfunctionargs=array()) {
$this->event = $event;
/**
* Confirm action
+ *
+ * @copyright 2009 Nicolas Connault
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class confirm_action extends component_action {
+ /**
+ * Constructs the confirm action object
+ *
+ * @param string $message The message to display to the user when they are shown
+ * the confirm dialogue.
+ * @param string $callback The method to call when the user confirms the action.
+ * @param string $continuelabel The string to use for he continue button
+ * @param string $cancellabel The string to use for the cancel button
+ */
public function __construct($message, $callback = null, $continuelabel = null, $cancellabel = null) {
parent::__construct('click', 'M.util.show_confirm_dialog', array(
'message' => $message, 'callback' => $callback,
* Component action for a popup window.
*
* @copyright 2009 Nicolas Connault
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class popup_action extends component_action {
+ /**
+ * @var string The JS function to call for the popup
+ */
public $jsfunction = 'openpopup';
/**
- * @var array $params An array of parameters that will be passed to the openpopup JS function
+ * @var array An array of parameters that will be passed to the openpopup JS function
*/
public $params = array(
'height' => 400,
/**
* Constructor
+ *
* @param string $event DOM event
* @param moodle_url|string $url A moodle_url object, required if no jsfunction is given
- * @param string $method 'post' or 'get'
+ * @param string $name The JS function to call for the popup (default 'popup')
* @param array $params An array of popup parameters
- * @return void
*/
public function __construct($event, $url, $name='popup', $params=array()) {
global $CFG;
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
* Please see http://docs.moodle.org/en/Developement:How_Moodle_outputs_HTML
* for an overview.
*
- * @package core
- * @subpackage lib
- * @copyright 2009 Tim Hunt
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package core
+ * @category output
+ * @copyright 2009 Tim Hunt
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
defined('MOODLE_INTERNAL') || die();
/**
* Interface marking other classes as suitable for renderer_base::render()
- * @author 2010 Petr Skoda (skodak) info@skodak.org
+ *
+ * @copyright 2010 Petr Skoda (skodak) info@skodak.org
+ * @package core
+ * @category output
*/
interface renderable {
// intentionally empty
* Data structure representing a file picker.
*
* @copyright 2010 Dongsheng Cai
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class file_picker implements renderable {
+
+ /**
+ * @var stdClass An object containing options for the file picker
+ */
public $options;
+
+ /**
+ * Constructs a file picker object.
+ *
+ * The following are possible options for the filepicker:
+ * - accepted_types (*)
+ * - return_types (FILE_INTERNAL)
+ * - env (filepicker)
+ * - client_id (uniqid)
+ * - itemid (0)
+ * - maxbytes (-1)
+ * - maxfiles (1)
+ * - buttonname (false)
+ *
+ * @param stdClass $options An object containing options for the file picker.
+ */
public function __construct(stdClass $options) {
global $CFG, $USER, $PAGE;
require_once($CFG->dirroot. '/repository/lib.php');
* Data structure representing a user picture.
*
* @copyright 2009 Nicolas Connault, 2010 Petr Skoda
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Modle 2.0
+ * @package core
+ * @category output
*/
class user_picture implements renderable {
/**
- * @var array List of mandatory fields in user record here. (do not include TEXT columns because it would break SELECT DISTINCT in MSSQL and ORACLE)
+ * @var array List of mandatory fields in user record here. (do not include
+ * TEXT columns because it would break SELECT DISTINCT in MSSQL and ORACLE)
*/
- protected static $fields = array('id', 'picture', 'firstname', 'lastname', 'imagealt', 'email'); //TODO: add deleted
+ protected static $fields = array('id', 'picture', 'firstname', 'lastname', 'imagealt', 'email');
/**
- * @var object $user A user object with at least fields all columns specified in $fields array constant set.
+ * @var stdClass A user object with at least fields all columns specified
+ * in $fields array constant set.
*/
public $user;
+
/**
- * @var int $courseid The course id. Used when constructing the link to the user's profile,
- * page course id used if not specified.
+ * @var int The course id. Used when constructing the link to the user's
+ * profile, page course id used if not specified.
*/
public $courseid;
+
/**
- * @var bool $link add course profile link to image
+ * @var bool Add course profile link to image
*/
public $link = true;
+
/**
- * @var int $size Size in pixels. Special values are (true/1 = 100px) and (false/0 = 35px) for backward compatibility
+ * @var int Size in pixels. Special values are (true/1 = 100px) and
+ * (false/0 = 35px)
+ * for backward compatibility.
*/
public $size = 35;
+
/**
- * @var boolean $alttext add non-blank alt-text to the image.
+ * @var bool Add non-blank alt-text to the image.
* Default true, set to false when image alt just duplicates text in screenreaders.
*/
public $alttext = true;
+
/**
- * @var boolean $popup Whether or not to open the link in a popup window.
+ * @var bool Whether or not to open the link in a popup window.
*/
public $popup = false;
+
/**
* @var string Image class attribute
*/
/**
* User picture constructor.
*
- * @param object $user user record with at least id, picture, imagealt, firstname and lastname set.
- * @param array $options such as link, size, link, ...
+ * @param stdClass $user user record with at least id, picture, imagealt, firstname and lastname set.
*/
public function __construct(stdClass $user) {
global $DB;
* @param string $fieldprefix prefix added to all columns in their aliases, does not apply to 'id'
* @return stdClass object with unaliased user fields
*/
- public static function unalias(stdClass $record, array $extrafields=null, $idalias='id', $fieldprefix='') {
+ public static function unalias(stdClass $record, array $extrafields = null, $idalias = 'id', $fieldprefix = '') {
if (empty($idalias)) {
$idalias = 'id';
* This method is recommended as it avoids costly redirects of user pictures
* if requests are made for non-existent files etc.
*
+ * @param moodle_page $page
* @param renderer_base $renderer
* @return moodle_url
*/
* Data structure representing a help icon.
*
* @copyright 2009 Nicolas Connault, 2010 Petr Skoda
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class old_help_icon implements renderable {
+
/**
- * @var string $helpidentifier lang pack identifier
+ * @var string Lang pack identifier
*/
public $helpidentifier;
+
/**
- * @var string $title A descriptive text for title tooltip
+ * @var string A descriptive text for title tooltip
*/
public $title = null;
+
/**
- * @var string $component Component name, the same as in get_string()
+ * @var string Component name, the same as in get_string()
*/
public $component = 'moodle';
+
/**
- * @var string $linktext Extra descriptive text next to the icon
+ * @var string Extra descriptive text next to the icon
*/
public $linktext = null;
/**
* Constructor: sets up the other components in case they are needed
+ *
* @param string $helpidentifier The keyword that defines a help page
* @param string $title A descriptive text for accessibility only
* @param string $component
- * @param bool $linktext add extra text to icon
- * @return void
*/
public function __construct($helpidentifier, $title, $component = 'moodle') {
if (empty($title)) {
* Data structure representing a help icon.
*
* @copyright 2010 Petr Skoda (info@skodak.org)
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class help_icon implements renderable {
+
/**
- * @var string $identifier lang pack identifier (without the "_help" suffix),
- * both get_string($identifier, $component) and get_string($identifier.'_help', $component)
- * must exist.
+ * @var string lang pack identifier (without the "_help" suffix),
+ * both get_string($identifier, $component) and get_string($identifier.'_help', $component)
+ * must exist.
*/
public $identifier;
+
/**
- * @var string $component Component name, the same as in get_string()
+ * @var string Component name, the same as in get_string()
*/
public $component;
+
/**
- * @var string $linktext Extra descriptive text next to the icon
+ * @var string Extra descriptive text next to the icon
*/
public $linktext = null;
/**
* Constructor
- * @param string $identifier string for help page title,
+ *
+ * @param string $identifier string for help page title,
* string with _help suffix is used for the actual help text.
* string with _link suffix is used to create a link to further info (if it exists)
* @param string $component
* Data structure representing an icon.
*
* @copyright 2010 Petr Skoda
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class pix_icon implements renderable {
+
+ /**
+ * @var string The icon name
+ */
var $pix;
+
+ /**
+ * @var string The component the icon belongs to.
+ */
var $component;
+
+ /**
+ * @var array An array of attributes to use on the icon
+ */
var $attributes = array();
/**
* Constructor
+ *
* @param string $pix short icon name
* @param string $alt The alt text to use for the icon
* @param string $component component name
/**
* Data structure representing an emoticon image
*
- * @since Moodle 2.0
+ * @copyright 2010 David Mudrak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class pix_emoticon extends pix_icon implements renderable {
* Data structure representing a simple form with only one button.
*
* @copyright 2009 Petr Skoda
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class single_button implements renderable {
+
/**
- * Target url
- * @var moodle_url
+ * @var moodle_url Target url
*/
var $url;
+
/**
- * Button label
- * @var string
+ * @var string Button label
*/
var $label;
+
/**
- * Form submit method
- * @var string post or get
+ * @var string Form submit method post or get
*/
var $method = 'post';
+
/**
- * Wrapping div class
- * @var string
- * */
+ * @var string Wrapping div class
+ */
var $class = 'singlebutton';
+
/**
- * True if button disabled, false if normal
- * @var boolean
+ * @var bool True if button disabled, false if normal
*/
var $disabled = false;
+
/**
- * Button tooltip
- * @var string
+ * @var string Button tooltip
*/
var $tooltip = null;
+
/**
- * Form id
- * @var string
+ * @var string Form id
*/
var $formid;
+
/**
- * List of attached actions
- * @var array of component_action
+ * @var array List of attached actions
*/
var $actions = array();
/**
* Constructor
- * @param string|moodle_url $url
+ * @param moodle_url $url
* @param string $label button text
* @param string $method get or post submit method
*/
/**
* Shortcut for adding a JS confirm dialog when the button is clicked.
* The message must be a yes/no question.
- * @param string $message The yes/no confirmation question. If "Yes" is clicked, the original action will occur.
- * @return void
+ *
+ * @param string $confirmmessage The yes/no confirmation question. If "Yes" is clicked, the original action will occur.
*/
public function add_confirm_action($confirmmessage) {
$this->add_action(new confirm_action($confirmmessage));
/**
* Add action to the button.
* @param component_action $action
- * @return void
*/
public function add_action(component_action $action) {
$this->actions[] = $action;
/**
* Simple form with just one select field that gets submitted automatically.
+ *
* If JS not enabled small go button is printed too.
*
* @copyright 2009 Petr Skoda
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class single_select implements renderable {
+
/**
- * Target url - includes hidden fields
- * @var moodle_url
+ * @var moodle_url Target url - includes hidden fields
*/
var $url;
+
/**
- * Name of the select element.
- * @var string
+ * @var string Name of the select element.
*/
var $name;
+
/**
- * @var array $options associative array value=>label ex.:
- * array(1=>'One, 2=>Two)
- * it is also possible to specify optgroup as complex label array ex.:
- * array(array('Odd'=>array(1=>'One', 3=>'Three)), array('Even'=>array(2=>'Two')))
- * array(1=>'One', '--1uniquekey'=>array('More'=>array(2=>'Two', 3=>'Three')))
+ * @var array $options associative array value=>label ex.: array(1=>'One, 2=>Two)
+ * it is also possible to specify optgroup as complex label array ex.:
+ * array(array('Odd'=>array(1=>'One', 3=>'Three)), array('Even'=>array(2=>'Two')))
+ * array(1=>'One', '--1uniquekey'=>array('More'=>array(2=>'Two', 3=>'Three')))
*/
var $options;
+
/**
- * Selected option
- * @var string
+ * @var string Selected option
*/
var $selected;
+
/**
- * Nothing selected
- * @var array
+ * @var array Nothing selected
*/
var $nothing;
+
/**
- * Extra select field attributes
- * @var array
+ * @var array Extra select field attributes
*/
var $attributes = array();
+
/**
- * Button label
- * @var string
+ * @var string Button label
*/
var $label = '';
+
/**
- * Form submit method
- * @var string post or get
+ * @var string Form submit method post or get
*/
var $method = 'get';
+
/**
- * Wrapping div class
- * @var string
- * */
+ * @var string Wrapping div class
+ */
var $class = 'singleselect';
+
/**
- * True if button disabled, false if normal
- * @var boolean
+ * @var bool True if button disabled, false if normal
*/
var $disabled = false;
+
/**
- * Button tooltip
- * @var string
+ * @var string Button tooltip
*/
var $tooltip = null;
+
/**
- * Form id
- * @var string
+ * @var string Form id
*/
var $formid = null;
+
/**
- * List of attached actions
- * @var array of component_action
+ * @var array List of attached actions
*/
var $helpicon = null;
+
/**
* Constructor
* @param moodle_url $url form action target, includes hidden fields
* @param array $nothing
* @param string $formid
*/
- public function __construct(moodle_url $url, $name, array $options, $selected='', $nothing=array(''=>'choosedots'), $formid=null) {
+ public function __construct(moodle_url $url, $name, array $options, $selected = '', $nothing = array('' => 'choosedots'), $formid = null) {
$this->url = $url;
$this->name = $name;
$this->options = $options;
/**
* Shortcut for adding a JS confirm dialog when the button is clicked.
* The message must be a yes/no question.
- * @param string $message The yes/no confirmation question. If "Yes" is clicked, the original action will occur.
- * @return void
+ *
+ * @param string $confirmmessage The yes/no confirmation question. If "Yes" is clicked, the original action will occur.
*/
public function add_confirm_action($confirmmessage) {
$this->add_action(new component_action('submit', 'M.util.show_confirm_dialog', array('message' => $confirmmessage)));
/**
* Add action to the button.
+ *
* @param component_action $action
- * @return void
*/
public function add_action(component_action $action) {
$this->actions[] = $action;
/**
* Adds help icon.
- * @param string $page The keyword that defines a help page
+ *
+ * @param string $helppage The keyword that defines a help page
* @param string $title A descriptive text for accessibility only
* @param string $component
- * @param bool $linktext add extra text to icon
- * @return void
*/
public function set_old_help_icon($helppage, $title, $component = 'moodle') {
$this->helpicon = new old_help_icon($helppage, $title, $component);
/**
* Adds help icon.
+ *
* @param string $identifier The keyword that defines a help page
* @param string $component
- * @param bool $linktext add extra text to icon
- * @return void
*/
public function set_help_icon($identifier, $component = 'moodle') {
$this->helpicon = new help_icon($identifier, $component);
/**
* Sets select's label
+ *
* @param string $label
- * @return void
*/
public function set_label($label) {
$this->label = $label;
}
}
-
/**
* Simple URL selection widget description.
+ *
* @copyright 2009 Petr Skoda
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class url_select implements renderable {
/**
- * @var array $urls associative array value=>label ex.:
- * array(1=>'One, 2=>Two)
- * it is also possible to specify optgroup as complex label array ex.:
- * array(array('Odd'=>array(1=>'One', 3=>'Three)), array('Even'=>array(2=>'Two')))
- * array(1=>'One', '--1uniquekey'=>array('More'=>array(2=>'Two', 3=>'Three')))
+ * @var array $urls associative array value=>label ex.: array(1=>'One, 2=>Two)
+ * it is also possible to specify optgroup as complex label array ex.:
+ * array(array('Odd'=>array(1=>'One', 3=>'Three)), array('Even'=>array(2=>'Two')))
+ * array(1=>'One', '--1uniquekey'=>array('More'=>array(2=>'Two', 3=>'Three')))
*/
var $urls;
+
/**
- * Selected option
- * @var string
+ * @var string Selected option
*/
var $selected;
+
/**
- * Nothing selected
- * @var array
+ * @var array Nothing selected
*/
var $nothing;
+
/**
- * Extra select field attributes
- * @var array
+ * @var array Extra select field attributes
*/
var $attributes = array();
+
/**
- * Button label
- * @var string
+ * @var string Button label
*/
var $label = '';
+
/**
- * Wrapping div class
- * @var string
- * */
+ * @var string Wrapping div class
+ */
var $class = 'urlselect';
+
/**
- * True if button disabled, false if normal
- * @var boolean
+ * @var bool True if button disabled, false if normal
*/
var $disabled = false;
+
/**
- * Button tooltip
- * @var string
+ * @var string Button tooltip
*/
var $tooltip = null;
+
/**
- * Form id
- * @var string
+ * @var string Form id
*/
var $formid = null;
+
/**
- * List of attached actions
- * @var array of component_action
+ * @var array List of attached actions
*/
var $helpicon = null;
+
/**
* @var string If set, makes button visible with given name for button
*/
var $showbutton = null;
+
/**
* Constructor
* @param array $urls list of options
* @param string $showbutton Set to text of button if it should be visible
* or null if it should be hidden (hidden version always has text 'go')
*/
- public function __construct(array $urls, $selected='', $nothing=array(''=>'choosedots'),
- $formid=null, $showbutton=null) {
+ public function __construct(array $urls, $selected = '', $nothing = array('' => 'choosedots'), $formid = null, $showbutton = null) {
$this->urls = $urls;
$this->selected = $selected;
$this->nothing = $nothing;
/**
* Adds help icon.
- * @param string $page The keyword that defines a help page
+ *
+ * @param string $helppage The keyword that defines a help page
* @param string $title A descriptive text for accessibility only
* @param string $component
- * @param bool $linktext add extra text to icon
- * @return void
*/
public function set_old_help_icon($helppage, $title, $component = 'moodle') {
$this->helpicon = new old_help_icon($helppage, $title, $component);
/**
* Adds help icon.
+ *
* @param string $identifier The keyword that defines a help page
* @param string $component
- * @param bool $linktext add extra text to icon
- * @return void
*/
public function set_help_icon($identifier, $component = 'moodle') {
$this->helpicon = new help_icon($identifier, $component);
/**
* Sets select's label
+ *
* @param string $label
- * @return void
*/
public function set_label($label) {
$this->label = $label;
}
}
-
/**
* Data structure describing html link with special action attached.
+ *
* @copyright 2010 Petr Skoda
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class action_link implements renderable {
+
/**
- * Href url
- * @var moodle_url
+ * @var moodle_url Href url
*/
var $url;
+
/**
- * Link text
- * @var string HTML fragment
+ * @var string Link text HTML fragment
*/
var $text;
+
/**
- * HTML attributes
- * @var array
+ * @var array HTML attributes
*/
var $attributes;
+
/**
- * List of actions attached to link
- * @var array of component_action
+ * @var array List of actions attached to link
*/
var $actions;
/**
* Constructor
- * @param string|moodle_url $url
+ * @param moodle_url $url
* @param string $text HTML fragment
* @param component_action $action
* @param array $attributes associative array of html link attributes + disabled
*/
- public function __construct(moodle_url $url, $text, component_action $action=null, array $attributes=null) {
- $this->url = clone($url);
- $this->text = $text;
+ public function __construct(moodle_url $url, $text, component_action $action = null, array $attributes = null) {
+ $this->url = clone($url);
+ $this->text = $text;
$this->attributes = (array)$attributes;
if ($action) {
$this->add_action($action);
/**
* Add action to the link.
+ *
* @param component_action $action
- * @return void
*/
public function add_action(component_action $action) {
$this->actions[] = $action;
}
+ /**
+ * Adds a CSS class to this action link object
+ * @param string $class
+ */
public function add_class($class) {
if (empty($this->attributes['class'])) {
$this->attributes['class'] = $class;
}
}
-// ==== HTML writer and helper classes, will be probably moved elsewhere ======
-
/**
* Simple html output class
+ *
* @copyright 2009 Tim Hunt, 2010 Petr Skoda
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class html_writer {
+
/**
* Outputs a tag with attributes and contents
+ *
* @param string $tagname The name of tag ('a', 'img', 'span' etc.)
* @param string $contents What goes between the opening and closing tags
* @param array $attributes The tag attributes (array('src' => $url, 'class' => 'class1') etc.)
/**
* Outputs an opening tag with attributes
+ *
* @param string $tagname The name of tag ('a', 'img', 'span' etc.)
* @param array $attributes The tag attributes (array('src' => $url, 'class' => 'class1') etc.)
* @return string HTML fragment
/**
* Outputs a closing tag
+ *
* @param string $tagname The name of tag ('a', 'img', 'span' etc.)
* @return string HTML fragment
*/
/**
* Outputs an empty tag with attributes
+ *
* @param string $tagname The name of tag ('input', 'img', 'br' etc.)
* @param array $attributes The tag attributes (array('src' => $url, 'class' => 'class1') etc.)
* @return string HTML fragment
/**
* Outputs a tag, but only if the contents are not empty
+ *
* @param string $tagname The name of tag ('a', 'img', 'span' etc.)
* @param string $contents What goes between the opening and closing tags
* @param array $attributes The tag attributes (array('src' => $url, 'class' => 'class1') etc.)
/**
* Outputs a HTML attribute and value
+ *
* @param string $name The name of the attribute ('src', 'href', 'class' etc.)
* @param string $value The value of the attribute. The value will be escaped with {@link s()}
* @return string HTML fragment
/**
* Outputs a list of HTML attributes and values
+ *
* @param array $attributes The tag attributes (array('src' => $url, 'class' => 'class1') etc.)
* The values will be escaped with {@link s()}
* @return string HTML fragment
/**
* Generates random html element id.
- * @param string $base
- * @return string
+ *
+ * @staticvar int $counter
+ * @staticvar type $uniq
+ * @param string $base A string fragment that will be included in the random ID.
+ * @return string A unique ID
*/
public static function random_id($base='random') {
static $counter = 0;
/**
* Generates a simple html link
- * @param string|moodle_url $url
- * @param string $text link txt
- * @param array $attributes extra html attributes
+ *
+ * @param string|moodle_url $url The URL
+ * @param string $text The text
+ * @param array $attributes HTML attributes
* @return string HTML fragment
*/
public static function link($url, $text, array $attributes = null) {
}
/**
- * generates a simple checkbox with optional label
- * @param string $name
- * @param string $value
- * @param bool $checked
- * @param string $label
- * @param array $attributes
+ * Generates a simple checkbox with optional label
+ *
+ * @param string $name The name of the checkbox
+ * @param string $value The value of the checkbox
+ * @param bool $checked Whether the checkbox is checked
+ * @param string $label The label for the checkbox
+ * @param array $attributes Any attributes to apply to the checkbox
* @return string html fragment
*/
public static function checkbox($name, $value, $checked = true, $label = '', array $attributes = null) {
/**
* Generates a simple select yes/no form field
+ *
* @param string $name name of select element
* @param bool $selected
* @param array $attributes - html select element attributes
- * @return string HRML fragment
+ * @return string HTML fragment
*/
public static function select_yes_no($name, $selected=true, array $attributes = null) {
$options = array('1'=>get_string('yes'), '0'=>get_string('no'));
/**
* Generates a simple select form field
+ *
* @param array $options associative array value=>label ex.:
* array(1=>'One, 2=>Two)
* it is also possible to specify optgroup as complex label array ex.:
* array(1=>'One', '--1uniquekey'=>array('More'=>array(2=>'Two', 3=>'Three')))
* @param string $name name of select element
* @param string|array $selected value or array of values depending on multiple attribute
- * @param array|bool $nothing, add nothing selected option, or false of not added
- * @param array $attributes - html select element attributes
+ * @param array|bool $nothing add nothing selected option, or false of not added
+ * @param array $attributes html select element attributes
* @return string HTML fragment
*/
- public static function select(array $options, $name, $selected = '', $nothing = array(''=>'choosedots'), array $attributes = null) {
+ public static function select(array $options, $name, $selected = '', $nothing = array('' => 'choosedots'), array $attributes = null) {
$attributes = (array)$attributes;
if (is_array($nothing)) {
foreach ($nothing as $k=>$v) {
$class = str_replace(']', '', $class);
$attributes['class'] = $class;
}
- $attributes['class'] = 'select ' . $attributes['class']; /// Add 'select' selector always
+ $attributes['class'] = 'select ' . $attributes['class']; // Add 'select' selector always
$attributes['name'] = $name;
return self::tag('select', $output, $attributes);
}
+ /**
+ * Returns HTML to display a select box option.
+ *
+ * @param string $label The label to display as the option.
+ * @param string|int $value The value the option represents
+ * @param array $selected An array of selected options
+ * @return string HTML fragment
+ */
private static function select_option($label, $value, array $selected) {
$attributes = array();
$value = (string)$value;
return self::tag('option', $label, $attributes);
}
+ /**
+ * Returns HTML to display a select box option group.
+ *
+ * @param string $groupname The label to use for the group
+ * @param array $options The options in the group
+ * @param array $selected An array of selected values.
+ * @return string HTML fragment.
+ */
private static function select_optgroup($groupname, $options, array $selected) {
if (empty($options)) {
return '';
/**
* This is a shortcut for making an hour selector menu.
+ *
* @param string $type The type of selector (years, months, days, hours, minutes)
* @param string $name fieldname
* @param int $currenttime A default timestamp in GMT
* @param array $attributes - html select element attributes
* @return HTML fragment
*/
- public static function select_time($type, $name, $currenttime=0, $step=5, array $attributes=null) {
+ public static function select_time($type, $name, $currenttime = 0, $step = 5, array $attributes = null) {
if (!$currenttime) {
$currenttime = time();
}
/**
* Shortcut for quick making of lists
+ *
+ * Note: 'list' is a reserved keyword ;-)
+ *
* @param array $items
- * @param string $tag ul or ol
* @param array $attributes
+ * @param string $tag ul or ol
* @return string
*/
public static function alist(array $items, array $attributes = null, $tag = 'ul') {
- //note: 'list' is a reserved keyword ;-)
-
$output = '';
foreach ($items as $item) {
/**
* Returns hidden input fields created from url parameters.
+ *
* @param moodle_url $url
* @param array $exclude list of excluded parameters
* @return string HTML fragment
/**
* Generate a script tag containing the the specified code.
*
- * @param string $js the JavaScript code
- * @param moodle_url|string optional url of the external script, $code ignored if specified
+ * @param string $jscode the JavaScript code
+ * @param moodle_url|string $url optional url of the external script, $code ignored if specified
* @return string HTML, the code wrapped in <script> tags.
*/
public static function script($jscode, $url=null) {
* @param array $attributes to be inserted in the tab, for example array('accesskey' => 'a')
* @return string HTML of the label element
*/
- public static function label($text, $for, $colonize=true, array $attributes=array()) {
+ public static function label($text, $for, $colonize = true, array $attributes=array()) {
if (!is_null($for)) {
$attributes = array_merge($attributes, array('for' => $for));
}
$text = trim($text);
$label = self::tag('label', $text, $attributes);
- /*
- // TODO $colonize disabled for now yet - see MDL-12192 for details
- if (!empty($text) and $colonize) {
- // the $text may end with the colon already, though it is bad string definition style
- $colon = get_string('labelsep', 'langconfig');
- if (!empty($colon)) {
- $trimmed = trim($colon);
- if ((substr($text, -strlen($trimmed)) == $trimmed) or (substr($text, -1) == ':')) {
- //debugging('The label text should not end with colon or other label separator,
- // please fix the string definition.', DEBUG_DEVELOPER);
- } else {
- $label .= $colon;
- }
- }
- }
- */
+ // TODO MDL-12192 $colonize disabled for now yet
+ // if (!empty($text) and $colonize) {
+ // // the $text may end with the colon already, though it is bad string definition style
+ // $colon = get_string('labelsep', 'langconfig');
+ // if (!empty($colon)) {
+ // $trimmed = trim($colon);
+ // if ((substr($text, -strlen($trimmed)) == $trimmed) or (substr($text, -1) == ':')) {
+ // //debugging('The label text should not end with colon or other label separator,
+ // // please fix the string definition.', DEBUG_DEVELOPER);
+ // } else {
+ // $label .= $colon;
+ // }
+ // }
+ // }
return $label;
}
}
-// ==== JS writer and helper classes, will be probably moved elsewhere ======
-
/**
* Simple javascript output class
+ *
* @copyright 2010 Petr Skoda
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class js_writer {
+
/**
* Returns javascript code calling the function
+ *
* @param string $function function name, can be complex like Y.Event.purgeElement
* @param array $arguments parameters
* @param int $delay execution delay in seconds
}
/**
- * Special function which adds Y as first argument of fucntion call.
- * @param string $function
- * @param array $extraarguments
- * @return string
+ * Special function which adds Y as first argument of function call.
+ *
+ * @param string $function The function to call
+ * @param array $extraarguments Any arguments to pass to it
+ * @return string Some JS code
*/
public static function function_call_with_Y($function, array $extraarguments = null) {
if ($extraarguments) {
/**
* Returns JavaScript code to initialise a new object
- * @param string|null $var If it is null then no var is assigned the new object
- * @param string $class
- * @param array $arguments
- * @param array $requirements
- * @param int $delay
- * @return string
+ *
+ * @param string $var If it is null then no var is assigned the new object.
+ * @param string $class The class to initialise an object for.
+ * @param array $arguments An array of args to pass to the init method.
+ * @param array $requirements Any modules required for this class.
+ * @param int $delay The delay before initialisation. 0 = no delay.
+ * @return string Some JS code
*/
public static function object_init($var, $class, array $arguments = null, array $requirements = null, $delay=0) {
if (is_array($arguments)) {
/**
* Returns code setting value to variable
+ *
* @param string $name
* @param mixed $value json serialised value
* @param bool $usevar add var definition, ignored for nested properties
* @return string JS code fragment
*/
- public static function set_variable($name, $value, $usevar=true) {
+ public static function set_variable($name, $value, $usevar = true) {
$output = '';
if ($usevar) {
/**
* Writes event handler attaching code
- * @param mixed $selector standard YUI selector for elements, may be array or string, element id is in the form "#idvalue"
+ *
+ * @param array|string $selector standard YUI selector for elements, may be
+ * array or string, element id is in the form "#idvalue"
* @param string $event A valid DOM event (click, mousedown, change etc.)
* @param string $function The name of the function to call
- * @param array $arguments An optional array of argument parameters to pass to the function
+ * @param array $arguments An optional array of argument parameters to pass to the function
* @return string JS code fragment
*/
public static function event_handler($selector, $event, $function, array $arguments = null) {
}
/**
- * Holds all the information required to render a <table> by {@see core_renderer::table()}
+ * Holds all the information required to render a <table> by {@link core_renderer::table()}
*
* Example of usage:
* $t = new html_table();
* echo html_writer::table($t);
*
* @copyright 2009 David Mudrak <david.mudrak@gmail.com>
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class html_table {
+
/**
- * @var string value to use for the id attribute of the table
+ * @var string Value to use for the id attribute of the table
*/
public $id = null;
+
/**
- * @var array
attributes of HTML attributes for the <table> element
+ * @var array
Attributes of HTML attributes for the <table> element
*/
public $attributes = array();
+
/**
+ * @var array An array of headings. The n-th array item is used as a heading of the n-th column.
* For more control over the rendering of the headers, an array of html_table_cell objects
* can be passed instead of an array of strings.
- * @var array of headings. The n-th array item is used as a heading of the n-th column.
*
* Example of usage:
* $t->head = array('Student', 'Grade');
*/
public $head;
+
/**
- * @var array can be used to make a heading span multiple columns
+ * @var array An array that can be used to make a heading span multiple columns.
+ * In this example, {@link html_table:$data} is supposed to have three columns. For the first two columns,
+ * the same heading is used. Therefore, {@link html_table::$head} should consist of two items.
*
* Example of usage:
* $t->headspan = array(2,1);
- *
- * In this example, {@see html_table:$data} is supposed to have three columns. For the first two columns,
- * the same heading is used. Therefore, {@see html_table::$head} should consist of two items.
*/
public $headspan;
+
/**
- * @var array of column alignments. The value is used as CSS 'text-align' property. Therefore, possible
+ * @var array An array of column alignments.
+ * The value is used as CSS 'text-align' property. Therefore, possible
* values are 'left', 'right', 'center' and 'justify'. Specify 'right' or 'left' from the perspective
* of a left-to-right (LTR) language. For RTL, the values are flipped automatically.
*
* $t->align = array(null, 'right');
* or
* $t->align[1] = 'right';
- *
*/
public $align;
+
/**
- * @var array of column sizes. The value is used as CSS 'size' property.
+ * @var array The value is used as CSS 'size' property.
*
* Examples of usage:
* $t->size = array('50%', '50%');
* $t->size[1] = '120px';
*/
public $size;
+
/**
- * @var array of wrapping information. The only possible value is 'nowrap' that sets the
+ * @var array An array of wrapping information.
+ * The only possible value is 'nowrap' that sets the
* CSS property 'white-space' to the value 'nowrap' in the given column.
*
* Example of usage:
* $t->wrap = array(null, 'nowrap');
*/
public $wrap;
+
/**
- * @var array of arrays or html_table_row objects containing the data. Alternatively, if you have
+ * @var array Array of arrays or html_table_row objects containing the data. Alternatively, if you have
* $head specified, the string 'hr' (for horizontal ruler) can be used
* instead of an array of cells data resulting in a divider rendered.
*
* $t->data = array($row1, $row2);
*/
public $data;
+
/**
- * @var string width of the table, percentage of the page preferred. Defaults to 80%
* @deprecated since Moodle 2.0. Styling should be in the CSS.
+ * @var string Width of the table, percentage of the page preferred.
*/
public $width = null;
+
/**
- * @var string alignment the whole table. Can be 'right', 'left' or 'center' (default).
* @deprecated since Moodle 2.0. Styling should be in the CSS.
+ * @var string Alignment for the whole table. Can be 'right', 'left' or 'center' (default).
*/
public $tablealign = null;
+
/**
- * @var int padding on each cell, in pixels
* @deprecated since Moodle 2.0. Styling should be in the CSS.
+ * @var int Padding on each cell, in pixels
*/
public $cellpadding = null;
+
/**
- * @var int spacing between cells, in pixels
+ * @var int Spacing between cells, in pixels
* @deprecated since Moodle 2.0. Styling should be in the CSS.
*/
public $cellspacing = null;
+
/**
- * @var array classes to add to particular rows, space-separated string.
+ * @var array Array of classes to add to particular rows, space-separated string.
* Classes 'r0' or 'r1' are added automatically for every odd or even row,
* respectively. Class 'lastrow' is added automatically for the last row
* in the table.
* $t->rowclasses[9] = 'tenth'
*/
public $rowclasses;
+
/**
- * @var array classes to add to every cell in a particular column,
+ * @var array An array of classes to add to every cell in a particular column,
* space-separated string. Class 'cell' is added automatically by the renderer.
* Classes 'c0' or 'c1' are added automatically for every odd or even column,
* respectively. Class 'lastcol' is added automatically for all last cells
* $t->colclasses = array(null, 'grade');
*/
public $colclasses;
+
/**
- * @var string description of the contents for screen readers.
+ * @var string Description of the contents for screen readers.
*/
public $summary;
}
}
-
/**
* Component representing a table row.
*
* @copyright 2009 Nicolas Connault
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class html_table_row {
+
/**
- * @var string value to use for the id attribute of the row
+ * @var string Value to use for the id attribute of the row.
*/
public $id = null;
+
/**
- * @var array $cells Array of html_table_cell objects
+ * @var array Array of html_table_cell objects
*/
public $cells = array();
+
/**
- * @var string $style value to use for the style attribute of the table row
+ * @var string Value to use for the style attribute of the table row
*/
public $style = null;
+
/**
- * @var array attributes of additional HTML attributes for the <tr> element
+ * @var array Attributes of additional HTML attributes for the <tr> element
*/
public $attributes = array();
}
}
-
/**
* Component representing a table cell.
*
* @copyright 2009 Nicolas Connault
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class html_table_cell {
+
/**
- * @var string value to use for the id attribute of the cell
+ * @var string Value to use for the id attribute of the cell.
*/
public $id = null;
+
/**
- * @var string $text The contents of the cell
+ * @var string The contents of the cell.
*/
public $text;
+
/**
- * @var string $abbr Abbreviated version of the contents of the cell
+ * @var string Abbreviated version of the contents of the cell.
*/
public $abbr = null;
+
/**
- * @var int $colspan Number of columns this cell should span
+ * @var int Number of columns this cell should span.
*/
public $colspan = null;
+
/**
- * @var int $rowspan Number of rows this cell should span
+ * @var int Number of rows this cell should span.
*/
public $rowspan = null;
+
/**
- * @var string $scope Defines a way to associate header cells and data cells in a table
+ * @var string Defines a way to associate header cells and data cells in a table.
*/
public $scope = null;
+
/**
- * @var boolean $header Whether or not this cell is a header cell
+ * @var bool Whether or not this cell is a header cell.
*/
public $header = null;
+
/**
- * @var string $style value to use for the style attribute of the table cell
+ * @var string Value to use for the style attribute of the table cell
*/
public $style = null;
+
/**
- * @var array attributes of additional HTML attributes for the <td> element
+ * @var array Attributes of additional HTML attributes for the <td> element
*/
public $attributes = array();
+ /**
+ * Constructs a table cell
+ *
+ * @param string $text
+ */
public function __construct($text = null) {
$this->text = $text;
$this->attributes['class'] = '';
}
}
-
-/// Complex components aggregating simpler components
-
-
/**
* Component representing a paging bar.
*
* @copyright 2009 Nicolas Connault
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class paging_bar implements renderable {
+
/**
- * @var int $maxdisplay The maximum number of pagelinks to display
+ * @var int The maximum number of pagelinks to display.
*/
public $maxdisplay = 18;
+
/**
- * @var int $totalcount post or get
+ * @var int The total number of entries to be pages through..
*/
public $totalcount;
+
/**
- * @var int $page The page you are currently viewing
+ * @var int The page you are currently viewing.
*/
public $page;
+
/**
- * @var int $perpage The number of entries that should be shown per page
+ * @var int The number of entries that should be shown per page.
*/
public $perpage;
+
/**
- * @var string $baseurl If this is a string then it is the url which will be appended with $pagevar, an equals sign and the page number.
- * If this is a moodle_url object then the pagevar param will be replaced by the page no, for each page.
+ * @var string|moodle_url If this is a string then it is the url which will be appended with $pagevar,
+ * an equals sign and the page number.
+ * If this is a moodle_url object then the pagevar param will be replaced by
+ * the page no, for each page.
*/
public $baseurl;
+
/**
- * @var string $pagevar This is the variable name that you use for the page number in your code (ie. 'tablepage', 'blogpage', etc)
+ * @var string This is the variable name that you use for the pagenumber in your
+ * code (ie. 'tablepage', 'blogpage', etc)
*/
public $pagevar;
+
/**
- * @var string $previouslink A HTML link representing the "previous" page
+ * @var string A HTML link representing the "previous" page.
*/
public $previouslink = null;
+
/**
- * @var tring $nextlink A HTML link representing the "next" page
+ * @var string A HTML link representing the "next" page.
*/
public $nextlink = null;
+
/**
- * @var tring $firstlink A HTML link representing the first page
+ * @var string A HTML link representing the first page.
*/
public $firstlink = null;
+
/**
- * @var tring $lastlink A HTML link representing the last page
+ * @var string A HTML link representing the last page.
*/
public $lastlink = null;
+
/**
- * @var array $pagelinks An array of strings. One of them is just a string: the current page
+ * @var array An array of strings. One of them is just a string: the current page
*/
public $pagelinks = array();
}
/**
- * @return void
+ * Prepares the paging bar for output.
+ *
+ * This method validates the arguments set up for the paging bar and then
+ * produces fragments of HTML to assist display later on.
+ *
+ * @param renderer_base $output
+ * @param moodle_page $page
+ * @param string $target
+ * @throws coding_exception
*/
public function prepare(renderer_base $output, moodle_page $page, $target) {
if (!isset($this->totalcount) || is_null($this->totalcount)) {
}
}
-
/**
* This class represents how a block appears on a page.
*
* During output, each block instance is asked to return a block_contents object,
* those are then passed to the $OUTPUT->block function for display.
*
- * {@link $contents} should probably be generated using a moodle_block_..._renderer.
+ * contents should probably be generated using a moodle_block_..._renderer.
*
* Other block-like things that need to appear on the page, for example the
* add new block UI, are also represented as block_contents objects.
*
* @copyright 2009 Tim Hunt
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class block_contents {
- /** @var int used to set $skipid. */
- protected static $idcounter = 1;
+ /** Used when the block cannot be collapsed **/
const NOT_HIDEABLE = 0;
+
+ /** Used when the block can be collapsed but currently is not **/
const VISIBLE = 1;
+
+ /** Used when the block has been collapsed **/
const HIDDEN = 2;
/**
- * @var integer $skipid All the blocks (or things that look like blocks)
- * printed on a page are given a unique number that can be used to construct
- * id="" attributes. This is set automatically be the {@link prepare()} method.
+ * @var int Used to set $skipid.
+ */
+ protected static $idcounter = 1;
+
+ /**
+ * @var int All the blocks (or things that look like blocks) printed on
+ * a page are given a unique number that can be used to construct id="" attributes.
+ * This is set automatically be the {@link prepare()} method.
* Do not try to set it manually.
*/
public $skipid;
/**
- * @var integer If this is the contents of a real block, this should be set to
- * the block_instance.id. Otherwise this should be set to 0.
+ * @var int If this is the contents of a real block, this should be set
+ * to the block_instance.id. Otherwise this should be set to 0.
*/
public $blockinstanceid = 0;
/**
- * @var integer if this is a real block instance, and there is a corresponding
+ * @var int If this is a real block instance, and there is a corresponding
* block_position.id for the block on this page, this should be set to that id.
* Otherwise it should be 0.
*/
public $blockpositionid = 0;
/**
- * @param array $attributes an array of attribute => value pairs that are put on the
- * outer div of this block. {@link $id} and {@link $classes} attributes should be set separately.
+ * @var array An array of attribute => value pairs that are put on the outer div of this
+ * block. {@link $id} and {@link $classes} attributes should be set separately.
*/
public $attributes;
/**
- * @param string $title The title of this block. If this came from user input,
- * it should already have had format_string() processing done on it. This will
- * be output inside <h2> tags. Please do not cause invalid XHTML.
+ * @var string The title of this block. If this came from user input, it should already
+ * have had format_string() processing done on it. This will be output inside
+ * <h2> tags. Please do not cause invalid XHTML.
*/
public $title = '';
/**
- * @param string $content HTML for the content
+ * @var string HTML for the content
*/
public $content = '';
/**
- * @param array $list an alternative to $content, it you want a list of things with optional icons.
+ * @var array An alternative to $content, it you want a list of things with optional icons.
*/
public $footer = '';
/**
- * Any small print that should appear under the block to explain to the
- * teacher about the block, for example 'This is a sticky block that was
+ * @var string Any small print that should appear under the block to explain
+ * to the teacher about the block, for example 'This is a sticky block that was
* added in the system context.'
- * @var string
*/
public $annotation = '';
/**
- * @var integer one of the constants NOT_HIDEABLE, VISIBLE, HIDDEN. Whether
+ * @var int One of the constants NOT_HIDEABLE, VISIBLE, HIDDEN. Whether
* the user can toggle whether this block is visible.
*/
public $collapsible = self::NOT_HIDEABLE;
/**
- * A (possibly empty) array of editing controls. Each element of this array
- * should be an array('url' => $url, 'icon' => $icon, 'caption' => $caption).
+ * @var array A (possibly empty) array of editing controls. Each element of
+ * this array should be an array('url' => $url, 'icon' => $icon, 'caption' => $caption).
* $icon is the icon name. Fed to $OUTPUT->pix_url.
- * @var array
*/
public $controls = array();
* Create new instance of block content
* @param array $attributes
*/
- public function __construct(array $attributes=null) {
+ public function __construct(array $attributes = null) {
$this->skipid = self::$idcounter;
self::$idcounter += 1;
/**
* Add html class to block
+ *
* @param string $class
- * @return void
*/
public function add_class($class) {
$this->attributes['class'] .= ' '.$class;
* $PAGE->url.
*
* @copyright 2009 Tim Hunt
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class block_move_target {
+
/**
- * Move url
- * @var moodle_url
+ * @var moodle_url Move url
*/
public $url;
+
/**
- * label
- * @var string
+ * @var string label
*/
public $text;
* not have children.
*
* @copyright 2010 Sam Hemelryk
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class custom_menu_item implements renderable {
+
/**
- * The text to show for the item
- * @var string
+ * @var string The text to show for the item
*/
protected $text;
+
/**
- * The link to give the icon if it has no children
- * @var moodle_url
+ * @var moodle_url The link to give the icon if it has no children
*/
protected $url;
+
/**
- * A title to apply to the item. By default the text
- * @var string
+ * @var string A title to apply to the item. By default the text
*/
protected $title;
+
/**
- * A sort order for the item, not necessary if you order things in the CFG var
- * @var int
+ * @var int A sort order for the item, not necessary if you order things in
+ * the CFG var.
*/
protected $sort;
+
/**
- * A reference to the parent for this item or NULL if it is a top level item
- * @var custom_menu_item
+ * @var custom_menu_item A reference to the parent for this item or NULL if
+ * it is a top level item
*/
protected $parent;
+
/**
- * A array in which to store children this item has.
- * @var array
+ * @var array A array in which to store children this item has.
*/
protected $children = array();
+
/**
- * A reference to the sort var of the last child that was added
- * @var int
+ * @var int A reference to the sort var of the last child that was added
*/
protected $lastsort = 0;
+
/**
* Constructs the new custom menu item
*
* @param custom_menu_item $parent A reference to the parent custom_menu_item this child
* belongs to, only if the child has a parent. [Optional]
*/
- public function __construct($text, moodle_url $url=null, $title=null, $sort = null, custom_menu_item $parent=null) {
+ public function __construct($text, moodle_url $url=null, $title=null, $sort = null, custom_menu_item $parent = null) {
$this->text = $text;
$this->url = $url;
$this->title = $title;
* @param int $sort
* @return custom_menu_item
*/
- public function add($text, moodle_url $url=null, $title=null, $sort = null) {
+ public function add($text, moodle_url $url = null, $title = null, $sort = null) {
$key = count($this->children);
if (empty($sort)) {
$sort = $this->lastsort + 1;
$this->lastsort = (int)$sort;
return $this->children[$key];
}
+
/**
* Returns the text for this item
* @return string
public function get_text() {
return $this->text;
}
+
/**
* Returns the url for this item
* @return moodle_url
public function get_url() {
return $this->url;
}
+
/**
* Returns the title for this item
* @return string
public function get_title() {
return $this->title;
}
+
/**
* Sorts and returns the children for this item
* @return array
$this->sort();
return $this->children;
}
+
/**
* Gets the sort order for this child
* @return int
public function get_sort_order() {
return $this->sort;
}
+
/**
* Gets the parent this child belong to
* @return custom_menu_item
public function get_parent() {
return $this->parent;
}
+
/**
* Sorts the children this item has
*/
public function sort() {
usort($this->children, array('custom_menu','sort_custom_menu_items'));
}
+
/**
* Returns true if this item has any children
* @return bool
* Settings: Administration > Appearance > Themes > Theme settings
*
* @copyright 2010 Sam Hemelryk
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class custom_menu extends custom_menu_item {
- /** @var string the language we should render for, null disables multilang support */
+ /**
+ * @var string The language we should render for, null disables multilang support.
+ */
protected $currentlanguage = null;
/**
* Creates the custom menu
*
* @param string $definition the menu items definition in syntax required by {@link convert_text_to_menu_nodes()}
- * @param string $language the current language code, null disables multilang support
+ * @param string $currentlanguage the current language code, null disables multilang support
*/
public function __construct($definition = '', $currentlanguage = null) {
-
$this->currentlanguage = $currentlanguage;
parent::__construct('root'); // create virtual root element of the menu
if (!empty($definition)) {
/**
* Overrides the children of this custom menu. Useful when getting children
* from $CFG->custommenuitems
+ *
+ * @param array $children
*/
public function override_children(array $children) {
$this->children = array();
* This function is designed to be used with the usort method
* usort($this->children, array('custom_menu','sort_custom_menu_items'));
*
+ * @static
* @param custom_menu_item $itema
* @param custom_menu_item $itemb
* @return int
}
return ($itema > $itemb) ? +1 : -1;
}
-}
+}
\ No newline at end of file
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
/**
- * Interface and classes for creating appropriate renderers for various
- * parts of Moodle.
+ * Interface and classes for creating appropriate renderers for various parts of Moodle.
*
* Please see http://docs.moodle.org/en/Developement:How_Moodle_outputs_HTML
* for an overview.
*
- * @package core
- * @subpackage lib
- * @copyright 2009 Tim Hunt
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @copyright 2009 Tim Hunt
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package core
+ * @category output
*/
defined('MOODLE_INTERNAL') || die();
/** Rich text html rendering intended for sending via email */
define('RENDERER_TARGET_HTMLEMAIL', 'htmlemail');
-/* note: maybe we could define portfolio export target too */
+// note: maybe we could define portfolio export target too
/**
* (See {@link renderer_factory_base::__construct} for an example.)
*
* @copyright 2009 Tim Hunt
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
interface renderer_factory {
+
/**
* Return the renderer for a particular part of Moodle.
*
* @param string $component name such as 'core', 'mod_forum' or 'qtype_multichoice'.
* @param string $subtype optional subtype such as 'news' resulting to 'mod_forum_news'
* @param string $target one of rendering target constants
- * @return object an object implementing the requested renderer interface.
+ * @return renderer_base an object implementing the requested renderer interface.
*/
public function get_renderer(moodle_page $page, $component, $subtype=null, $target=null);
}
* the definition of, the standard renderer class for a given module.
*
* @copyright 2009 Tim Hunt
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
abstract class renderer_factory_base implements renderer_factory {
- /** @var theme_config the theme we belong to. */
+ /**
+ * @var theme_config The theme we belong to.
+ */
protected $theme;
/**
* Constructor.
+ *
* @param theme_config $theme the theme we belong to.
*/
public function __construct(theme_config $theme) {
/**
* Returns suffix of renderer class expected for given target.
+ *
* @param string $target one of the renderer target constants, target is guessed if null used
* @return array two element array, first element is target, second the target suffix string
*/
}
}
-
/**
- * This is the default renderer factory for Moodle. It simply returns an instance
- * of the appropriate standard renderer class.
+ * This is the default renderer factory for Moodle.
+ *
+ * It simply returns an instance of the appropriate standard renderer class.
*
* @copyright 2009 Tim Hunt
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class standard_renderer_factory extends renderer_factory_base {
+
/**
* Implement the subclass method
+ *
* @param moodle_page $page the page the renderer is outputting content for.
* @param string $component name such as 'core', 'mod_forum' or 'qtype_multichoice'.
* @param string $subtype optional subtype such as 'news' resulting to 'mod_forum_news'
* @param string $target one of rendering target constants
- * @return object an object implementing the requested renderer interface.
+ * @return renderer_base an object implementing the requested renderer interface.
*/
public function get_renderer(moodle_page $page, $component, $subtype = null, $target = null) {
$classname = $this->standard_renderer_classname($component, $subtype);
/**
- * This is renderer factory allows themes to override the standard renderers using
- * php code.
+ * This is renderer factory allows themes to override the standard renderers using php code.
*
* It will load any code from theme/mytheme/renderers.php and
* theme/parenttheme/renderers.php, if then exist. Then whenever you ask for
* if either of those classes exist.
*
* @copyright 2009 Tim Hunt
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class theme_overridden_renderer_factory extends renderer_factory_base {
+ /**
+ * @var array An array of renderer prefixes
+ */
protected $prefixes = array();
/**
* Constructor.
- * @param object $theme the theme we are rendering for.
+ * @param theme_config $theme the theme we are rendering for.
*/
public function __construct(theme_config $theme) {
parent::__construct($theme);
/**
* Implement the subclass method
+ *
* @param moodle_page $page the page the renderer is outputting content for.
* @param string $component name such as 'core', 'mod_forum' or 'qtype_multichoice'.
* @param string $subtype optional subtype such as 'news' resulting to 'mod_forum_news'
* @param string $target one of rendering target constants
- * @return object an object implementing the requested renderer interface.
+ * @return renderer_base an object implementing the requested renderer interface.
*/
public function get_renderer(moodle_page $page, $component, $subtype = null, $target = null) {
$classname = $this->standard_renderer_classname($component, $subtype);
return new $classname($page, $target);
}
-}
+}
\ No newline at end of file
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
* Please see http://docs.moodle.org/en/Developement:How_Moodle_outputs_HTML
* for an overview.
*
- * @package core
- * @subpackage lib
- * @copyright 2009 Tim Hunt
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @copyright 2009 Tim Hunt
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package core
+ * @category output
*/
defined('MOODLE_INTERNAL') || die();
/**
* Invalidate all server and client side caches.
- * @return void
+ *
+ * This method deletes the phsyical directory that is used to cache the theme
+ * files used for serving.
+ * Because it deletes the main theme cache directoy all themes are reset by
+ * this function.
*/
function theme_reset_all_caches() {
global $CFG;
/**
* Enable or disable theme designer mode.
+ *
* @param bool $state
- * @return void
*/
function theme_set_designer_mod($state) {
theme_reset_all_caches();
/**
* Returns current theme revision number.
+ *
* @return int
*/
function theme_get_revision() {
* This class represents the configuration variables of a Moodle theme.
*
* All the variables with access: public below (with a few exceptions that are marked)
- * are the properties you can set in your theme's config.php file.
+ * are the properties you can set in your themes config.php file.
*
* There are also some methods and protected variables that are part of the inner
- * workings of Moodle's themes system. If you are just editing a theme's config.php
+ * workings of Moodle's themes system. If you are just editing a themes config.php
* file, you can just ignore those, and the following information for developers.
*
* Normally, to create an instance of this class, you should use the
* will create one for you, accessible as $PAGE->theme.
*
* @copyright 2009 Tim Hunt
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class theme_config {
+
/**
- * @var string default theme, used when requested theme not found
+ * @var string Default theme, used when requested theme not found.
*/
const DEFAULT_THEME = 'standard';
/**
- * You can base your theme on other themes by linking to the other theme as
+ * @var array You can base your theme on other themes by linking to the other theme as
* parents. This lets you use the CSS and layouts from the other themes
- * (see {@link $layouts}).
+ * (see {@link theme_config::$layouts}).
* That makes it easy to create a new theme that is similar to another one
- * but with a few changes. In this theme's CSS you only need to override
+ * but with a few changes. In this themes CSS you only need to override
* those rules you want to change.
- *
- * @var array
*/
public $parents;
/**
- * The names of all the stylesheets from this theme that you would
+ * @var array The names of all the stylesheets from this theme that you would
* like included, in order. Give the names of the files without .css.
- *
- * @var array
*/
public $sheets = array();
/**
- * The names of all the stylesheets from parents that should be excluded.
+ * @var array The names of all the stylesheets from parents that should be excluded.
* true value may be used to specify all parents or all themes from one parent.
* If no value specified value from parent theme used.
- *
- * @var array or arrays, true means all, null means use value from parent
*/
public $parents_exclude_sheets = null;
/**
- * List of plugin sheets to be excluded.
+ * @var array List of plugin sheets to be excluded.
* If no value specified value from parent theme used.
- *
- * @var array of full plugin names, null means use value from parent
*/
public $plugins_exclude_sheets = null;
/**
- * List of style sheets that are included in the text editor bodies.
+ * @var array List of style sheets that are included in the text editor bodies.
* Sheets from parent themes are used automatically and can not be excluded.
- *
- * @var array
*/
public $editor_sheets = array();
/**
- * The names of all the javascript files this theme that you would
+ * @var array The names of all the javascript files this theme that you would
* like included from head, in order. Give the names of the files without .js.
- *
- * @var array
*/
public $javascripts = array();
/**
- * The names of all the javascript files this theme that you would
+ * @var array The names of all the javascript files this theme that you would
* like included from footer, in order. Give the names of the files without .js.
- *
- * @var array
*/
public $javascripts_footer = array();
/**
- * The names of all the javascript files from parents that should be excluded.
- * true value may be used to specify all parents or all themes from one parent.
+ * @var array The names of all the javascript files from parents that should
+ * be excluded. true value may be used to specify all parents or all themes
+ * from one parent.
* If no value specified value from parent theme used.
- *
- * @var array or arrays, true means all, null means use value from parent
*/
public $parents_exclude_javascripts = null;
/**
- * Which file to use for each page layout.
+ * @var array Which file to use for each page layout.
*
* This is an array of arrays. The keys of the outer array are the different layouts.
* Pages in Moodle are using several different layouts like 'normal', 'course', 'home',
* the page, but in non-existent regions, they appear here. (Imaging, for example,
* that someone added blocks using a different theme that used different region
* names, and then switched to this theme.)
- *
- * @var array
*/
public $layouts = array();
/**
- * Name of the renderer factory class to use.
+ * @var string Name of the renderer factory class to use. Must implement the
+ * {@link renderer_factory} interface.
*
* This is an advanced feature. Moodle output is generated by 'renderers',
* you can customise the HTML that is output by writing custom renderers,
* <li>{@link theme_overridden_renderer_factory} - use this if you want to write
* your own custom renderers in a lib.php file in this theme (or the parent theme).</li>
* </ul>
- *
- * @var string name of a class implementing the {@link renderer_factory} interface.
*/
public $rendererfactory = 'standard_renderer_factory';
/**
- * Function to do custom CSS post-processing.
+ * @var string Function to do custom CSS post-processing.
*
* This is an advanced feature. If you want to do custom post-processing on the
* CSS before it is output (for example, to replace certain variable names
* with particular values) you can give the name of a function here.
- *
- * @var string the name of a function.
*/
public $csspostprocess = null;
/**
- * Accessibility: Right arrow-like character is
+ * @var string Accessibility: Right arrow-like character is
* used in the breadcrumb trail, course navigation menu
* (previous/next activity), calendar, and search forum block.
* If the theme does not set characters, appropriate defaults
* are set automatically. Please DO NOT
* use < > » - these are confusing for blind users.
- *
- * @var string
*/
public $rarrow = null;
/**
- * Accessibility: Right arrow-like character is
+ * @var string Accessibility: Right arrow-like character is
* used in the breadcrumb trail, course navigation menu
* (previous/next activity), calendar, and search forum block.
* If the theme does not set characters, appropriate defaults
* are set automatically. Please DO NOT
* use < > » - these are confusing for blind users.
- *
- * @var string
*/
public $larrow = null;
/**
- * Some themes may want to disable ajax course editing.
- * @var bool
+ * @var bool Some themes may want to disable ajax course editing.
*/
public $enablecourseajax = true;
//==Following properties are not configurable from theme config.php==
/**
- * The name of this theme. Set automatically when this theme is
+ * @var string The name of this theme. Set automatically when this theme is
* loaded. This can not be set in theme config.php
- * @var string
*/
public $name;
/**
- * the folder where this themes files are stored. This is set
+ * @var string The folder where this themes files are stored. This is set
* automatically. This can not be set in theme config.php
- * @var string
*/
public $dir;
/**
- * Theme settings stored in config_plugins table.
+ * @var stdClass Theme settings stored in config_plugins table.
* This can not be set in theme config.php
- * @var object
*/
public $setting = null;
/**
- * If set to true and the theme enables the dock then blocks will be able
+ * @var bool If set to true and the theme enables the dock then blocks will be able
* to be moved to the special dock
- * @var bool
*/
public $enable_dock = false;
/**
- * If set to true then this theme will not be shown in the theme selector unless
+ * @var bool If set to true then this theme will not be shown in the theme selector unless
* theme designer mode is turned on.
- * @var bool
*/
public $hidefromselector = false;
/**
- * Instance of the renderer_factory implementation
+ * @var renderer_factory Instance of the renderer_factory implementation
* we are using. Implementation detail.
- * @var renderer_factory
*/
protected $rf = null;
/**
- * List of parent config objects.
- * @var array list of parent configs
+ * @var array List of parent config objects.
**/
protected $parent_configs = array();
$this->check_theme_arrows();
}
- /*
+ /**
* Checks if arrows $THEME->rarrow, $THEME->larrow have been set (theme/-/config.php).
* If not it applies sensible defaults.
*
$this->larrow = '<';
}
- /// RTL support - in RTL languages, swap r and l arrows
+ // RTL support - in RTL languages, swap r and l arrows
if (right_to_left()) {
$t = $this->rarrow;
$this->rarrow = $this->larrow;
/**
* Returns output renderer prefixes, these are used when looking
* for the overridden renderers in themes.
+ *
* @return array
*/
public function renderer_prefixes() {
/**
* Returns the stylesheet URL of this editor content
+ *
* @param bool $encoded false means use & and true use & in URLs
* @return string
*/
/**
* Returns the content of the CSS to be used in editor content
+ *
* @return string
*/
public function editor_css_files() {
/**
* Get the stylesheet URL of this theme
- * @param bool $encoded false means use & and true use & in URLs
+ *
+ * @param moodle_page $page Not used... deprecated?
* @return array of moodle_url
*/
public function css_urls(moodle_page $page) {
/**
* Returns an array of organised CSS files required for this output
+ *
* @return array
*/
public function css_files() {
/**
* Returns the content of the one huge CSS merged from all style sheets.
+ *
* @return string
*/
public function css_content() {
* Given an array of file paths or a single file path loads the contents of
* the CSS file, processes it then returns it in the same structure it was given.
*
- * Can be used recursively on the results of {@see css_files}
+ * Can be used recursively on the results of {@link css_files}
*
* @param array|string $file An array of file paths or a single file path
* @param array $keys An array of previous array keys [recursive addition]
/**
- * Get the javascript URL of this theme
+ * Generate a URL to the file that serves theme JavaScript files.
+ *
* @param bool $inhead true means head url, false means footer
* @return moodle_url
*/
return new moodle_url($CFG->httpswwwroot.'/theme/javascript.php', $params);
}
+ /**
+ * Get the URL's for the JavaScript files used by this theme.
+ * They won't be served directly, instead they'll be mediated through
+ * theme/javascript.php.
+ *
+ * @param string $type Either javascripts_footer, or javascripts
+ * @return array
+ */
public function javascript_files($type) {
if ($type === 'footer') {
$type = 'javascripts_footer';
}
/**
- * Resolves an exclude setting to the theme's setting is applicable or the
+ * Resolves an exclude setting to the themes setting is applicable or the
* setting of its closest parent.
*
* @param string $variable The name of the setting the exclude setting to resolve
+ * @param string $default
* @return mixed
*/
- protected function resolve_excludes($variable, $default=null) {
+ protected function resolve_excludes($variable, $default = null) {
$setting = $default;
if (is_array($this->{$variable}) or $this->{$variable} === true) {
$setting = $this->{$variable};
/**
* Returns the content of the one huge javascript file merged from all theme javascript files.
- * @param bool $inhead
+ *
+ * @param bool $type
* @return string
*/
public function javascript_content($type) {
return $js;
}
+ /**
+ * Post processes CSS.
+ *
+ * This method post processes all of the CSS before it is served for this theme.
+ * This is done so that things such as image URL's can be swapped in and to
+ * run any specific CSS post process method the theme has requested.
+ * This allows themes to use CSS settings.
+ *
+ * @param string $css The CSS to process.
+ * @return string The processed CSS.
+ */
public function post_process($css) {
global $CFG;
* Return the URL for an image
*
* @param string $imagename the name of the icon.
- * @param string $component, specification of one plugin like in get_string()
+ * @param string $component specification of one plugin like in get_string()
* @return moodle_url
*/
public function pix_url($imagename, $component) {
/**
* Checks if file with any image extension exists.
+ *
* @param string $filepath
* @return string image name with extension
*/
/**
* Loads the theme config from config.php file.
+ *
* @param string $themename
- * @param object $settings from config_plugins table
- * @return object
+ * @param stdClass $settings from config_plugins table
+ * @return stdClass The theme configuration
*/
private static function find_theme_config($themename, $settings) {
// We have to use the variable name $THEME (upper case) because that
/**
* Finds the theme location and verifies the theme has all needed files
* and is not obsoleted.
+ *
* @param string $themename
* @return string full dir path or null if not found
*/
/**
* Get the renderer for a part of Moodle for this theme.
+ *
* @param moodle_page $page the page we are rendering
- * @param string $module the name of part of moodle. E.g. 'core', 'quiz', 'qtype_multichoice'.
+ * @param string $component the name of part of moodle. E.g. 'core', 'quiz', 'qtype_multichoice'.
* @param string $subtype optional subtype such as 'news' resulting to 'mod_forum_news'
* @param string $target one of rendering target constants
* @return renderer_base the requested renderer.
/**
* Get the information from {@link $layouts} for this type of page.
+ *
* @param string $pagelayout the the page layout name.
* @return array the appropriate part of {@link $layouts}.
*/
/**
* Returns auxiliary page layout options specified in layout configuration array.
+ *
* @param string $pagelayout
* @return array
*/
/**
* Inform a block_manager about the block regions this theme wants on this
* page layout.
+ *
* @param string $pagelayout the general type of the page.
* @param block_manager $blockmanager the block_manger to set up.
- * @return void
*/
public function setup_blocks($pagelayout, $blockmanager) {
$layoutinfo = $this->layout_info_for_page($pagelayout);
}
}
+ /**
+ * Gets the visible name for the requested block region.
+ *
+ * @param string $region The region name to get
+ * @param string $theme The theme the region belongs to (may come from the parent theme)
+ * @return string
+ */
protected function get_region_name($region, $theme) {
$regionstring = get_string('region-' . $region, 'theme_' . $theme);
// A name exists in this theme, so use it
/**
* Get the list of all block regions known to this theme in all templates.
+ *
* @return array internal region name => human readable name.
*/
public function get_all_block_regions() {
}
}
-
/**
* This class keeps track of which HTML tags are currently open.
*
* onto the stack.
*
* @copyright 2009 Tim Hunt
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class xhtml_container_stack {
- /** @var array stores the list of open containers. */
+
+ /**
+ * @var array Stores the list of open containers.
+ */
protected $opencontainers = array();
+
/**
- * @var array in developer debug mode, stores a stack trace of all opens and
+ * @var array In developer debug mode, stores a stack trace of all opens and
* closes, so we can output helpful error messages when there is a mismatch.
*/
protected $log = array();
+
/**
- * Store whether we are developer debug mode. We need this in several places
- * including in the destructor where we may not have access to $CFG.
- * @var boolean
+ * @var boolean Store whether we are developer debug mode. We need this in
+ * several places including in the destructor where we may not have access to $CFG.
*/
protected $isdebugging;
+ /**
+ * Constructor
+ */
public function __construct() {
$this->isdebugging = debugging('', DEBUG_DEVELOPER);
}
/**
* Push the close HTML for a recently opened container onto the stack.
+ *
* @param string $type The type of container. This is checked when {@link pop()}
* is called and must match, otherwise a developer debug warning is output.
* @param string $closehtml The HTML required to close the container.
- * @return void
*/
public function push($type, $closehtml) {
$container = new stdClass;
* Pop the HTML for the next closing container from the stack. The $type
* must match the type passed when the container was opened, otherwise a
* warning will be output.
+ *
* @param string $type The type of container.
* @return string the HTML required to close the container.
*/
* Close all but the last open container. This is useful in places like error
* handling, where you want to close all the open containers (apart from <body>)
* before outputting the error message.
+ *
* @param bool $shouldbenone assert that the stack should be empty now - causes a
* developer debug warning if it isn't.
* @return string the HTML required to close any open containers inside <body>.
* class without properly emptying the stack (for example, in a unit test).
* Calling this method stops the destruct method from outputting a developer
* debug warning. After calling this method, the instance can no longer be used.
- * @return void
*/
public function discard() {
$this->opencontainers = null;
/**
* Adds an entry to the log.
+ *
* @param string $action The name of the action
* @param string $type The type of action
- * @return void
*/
protected function log($action, $type) {
$this->log[] = '<li>' . $action . ' ' . $type . ' at:' .
/**
* Outputs the log's contents as a HTML list.
+ *
* @return string HTML list of the log
*/
protected function output_log() {
return '<ul>' . implode("\n", $this->log) . '</ul>';
}
-}
+}
\ No newline at end of file
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
/**
* Classes for rendering HTML output for Moodle.
*
- * Please see http://docs.moodle.org/en/Developement:How_Moodle_outputs_HTML
+ * Please see {@link http://docs.moodle.org/en/Developement:How_Moodle_outputs_HTML}
* for an overview.
*
- * @package core
- * @subpackage lib
+ * Included in this file are the primary renderer classes:
+ * - renderer_base: The renderer outline class that all renderers
+ * should inherit from.
+ * - core_renderer: The standard HTML renderer.
+ * - core_renderer_cli: An adaption of the standard renderer for CLI scripts.
+ * - core_renderer_ajax: An adaption of the standard renderer for AJAX scripts.
+ * - plugin_renderer_base: A renderer class that should be extended by all
+ * plugin renderers.
+ *
+ * @package core
+ * @category output
* @copyright 2009 Tim Hunt
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
* Also has methods to facilitate generating HTML output.
*
* @copyright 2009 Tim Hunt
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class renderer_base {
- /** @var xhtml_container_stack the xhtml_container_stack to use. */
+ /**
+ * @var xhtml_container_stack The xhtml_container_stack to use.
+ */
protected $opencontainers;
- /** @var moodle_page the page we are rendering for. */
+
+ /**
+ * @var moodle_page The Moodle page the renderer has been created to assist with.
+ */
protected $page;
- /** @var requested rendering target */
+
+ /**
+ * @var string The requested rendering target.
+ */
protected $target;
/**
* Constructor
+ *
+ * The constructor takes two arguments. The first is the page that the renderer
+ * has been created to assist with, and the second is the target.
+ * The target is an additional identifier that can be used to load different
+ * renderers for different options.
+ *
* @param moodle_page $page the page we are doing output for.
* @param string $target one of rendering target constants
*/
/**
* Returns rendered widget.
+ *
+ * The provided widget needs to be an object that extends the renderable
+ * interface.
+ * If will then be rendered by a method based upon the classname for the widget.
+ * For instance a widget of class `crazywidget` will be rendered by a protected
+ * render_crazywidget method of this renderer.
+ *
* @param renderable $widget instance with renderable interface
* @return string
*/
}
/**
- * Adds JS handlers needed for event execution for one html element id
- * @param component_action $actions
+ * Adds a JS action for the element with the provided id.
+ *
+ * This method adds a JS event for the provided component action to the page
+ * and then returns the id that the event has been attached to.
+ * If no id has been provided then a new ID is generated by {@link html_writer::random_id()}
+ *
+ * @param component_action $action
* @param string $id
* @return string id of element, either original submitted or random new if not supplied
*/
- public function add_action_handler(component_action $action, $id=null) {
+ public function add_action_handler(component_action $action, $id = null) {
if (!$id) {
$id = html_writer::random_id($action->event);
}
}
/**
- * Have we started output yet?
+ * Returns true is output has already started, and false if not.
+ *
* @return boolean true if the header has been printed.
*/
public function has_started() {
/**
* Given an array or space-separated list of classes, prepares and returns the HTML class attribute value
+ *
* @param mixed $classes Space-separated string or array of classes
* @return string HTML class attribute value
*/
/**
* Return the moodle_url for an image.
+ *
* The exact image location and extension is determined
* automatically by searching for gif|png|jpg|jpeg, please
* note there can not be diferent images with the different
/**
* Basis for all plugin renderers.
*
- * @author Petr Skoda (skodak)
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @copyright Petr Skoda (skodak)
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class plugin_renderer_base extends renderer_base {
+
/**
- * A reference to the current general renderer probably {@see core_renderer}
- * @var renderer_base
+ * @var renderer_base|core_renderer A reference to the current renderer.
+ * The renderer provided here will be determined by the page but will in 90%
+ * of cases by the {@link core_renderer}
*/
protected $output;
/**
* Constructor method, calls the parent constructor
+ *
* @param moodle_page $page
* @param string $target one of rendering target constants
*/
}
/**
- * Returns rendered widget.
+ * Renders the provided widget and returns the HTML to display it.
+ *
* @param renderable $widget instance with renderable interface
* @return string
*/
* The standard implementation of the core_renderer interface.
*
* @copyright 2009 Tim Hunt
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class core_renderer extends renderer_base {
/**
* Do NOT use, please use <?php echo $OUTPUT->main_content() ?>
* in layout files instead.
- * @var string used in {@link header()}.
* @deprecated
+ * @var string used in {@link core_renderer::header()}.
*/
const MAIN_CONTENT_TOKEN = '[MAIN CONTENT GOES HERE]';
- /** @var string used to pass information from {@link doctype()} to {@link standard_head_html()}. */
+
+ /**
+ * @var string Used to pass information from {@link core_renderer::doctype()} to
+ * {@link core_renderer::standard_head_html()}.
+ */
protected $contenttype;
- /** @var string used by {@link redirect_message()} method to communicate with {@link header()}. */
+
+ /**
+ * @var string Used by {@link core_renderer::redirect_message()} method to communicate
+ * with {@link core_renderer::header()}.
+ */
protected $metarefreshtag = '';
- /** @var string unique token */
+
+ /**
+ * @var string Unique token for the closing HTML
+ */
protected $unique_end_html_token;
- /** @var string unique token */
+
+ /**
+ * @var string Unique token for performance information
+ */
protected $unique_performance_info_token;
- /** @var string unique token */
+
+ /**
+ * @var string Unique token for the main content.
+ */
protected $unique_main_content_token;
/**
* Constructor
+ *
* @param moodle_page $page the page we are doing output for.
* @param string $target one of rendering target constants
*/
/**
* Get the DOCTYPE declaration that should be used with this page. Designed to
* be called in theme layout.php files.
+ *
* @return string the DOCTYPE declaration (and any XML prologue) that should be used.
*/
public function doctype() {
/**
* The attributes that should be added to the <html> tag. Designed to
* be called in theme layout.php files.
+ *
* @return string HTML fragment.
*/
public function htmlattributes() {
* The standard tags (meta tags, links to stylesheets and JavaScript, etc.)
* that should be included in the <head> tag. Designed to be called in theme
* layout.php files.
+ *
* @return string HTML fragment.
*/
public function standard_head_html() {
/**
* The standard tags (typically skip links) that should be output just inside
* the start of the <body> tag. Designed to be called in theme layout.php files.
+ *
* @return string HTML fragment.
*/
public function standard_top_of_body_html() {
* The standard tags (typically performance information and validation links,
* if we are in developer debug mode) that should be output in the footer area
* of the page. Designed to be called in theme layout.php files.
+ *
* @return string HTML fragment.
*/
public function standard_footer_html() {
global $CFG, $SCRIPT;
- // This function is normally called from a layout.php file in {@link header()}
+ // This function is normally called from a layout.php file in {@link core_renderer::header()}
// but some of the content won't be known until later, so we return a placeholder
- // for now. This will be replaced with the real content in {@link footer()}.
+ // for now. This will be replaced with the real content in {@link core_renderer::footer()}.
$output = $this->unique_performance_info_token;
if ($this->page->devicetypeinuse == 'legacy') {
// The legacy theme is in use print the notification
/**
* Returns standard main content placeholder.
* Designed to be called in theme layout.php files.
+ *
* @return string HTML fragment.
*/
public function main_content() {
/**
* The standard tags (typically script tags that are not needed earlier) that
* should be output after everything else, . Designed to be called in theme layout.php files.
+ *
* @return string HTML fragment.
*/
public function standard_end_of_body_html() {
- // This function is normally called from a layout.php file in {@link header()}
+ // This function is normally called from a layout.php file in {@link core_renderer::header()}
// but some of the content won't be known until later, so we return a placeholder
- // for now. This will be replaced with the real content in {@link footer()}.
+ // for now. This will be replaced with the real content in {@link core_renderer::footer()}.
return $this->unique_end_html_token;
}
/**
* Return the standard string that says whether you are logged in (and switched
* roles/logged in as another user).
+ *
* @return string HTML fragment.
*/
public function login_info() {
/**
* Return the 'back' link that normally appears in the footer.
+ *
* @return string HTML fragment.
*/
public function home_link() {
/**
* Renders and outputs the page layout file.
+ *
+ * This is done by preparing the normal globals available to a script, and
+ * then including the layout file provided by the current theme for the
+ * requested layout.
+ *
* @param string $layoutfile The name of the layout file
* @return string HTML code
*/
/**
* Outputs the page's footer
+ *
* @return string HTML fragment
*/
public function footer() {
* Close all but the last open container. This is useful in places like error
* handling, where you want to close all the open containers (apart from <body>)
* before outputting the error message.
+ *
* @param bool $shouldbenone assert that the stack should be empty now - causes a
* developer debug warning if it isn't.
* @return string the HTML required to close any open containers inside <body>.
/**
* Returns lang menu or '', this method also checks forcing of languages in courses.
- * @return string
+ *
+ * @return string The lang menu HTML or empty string
*/
public function lang_menu() {
global $CFG;
/**
* Output the row of editing icons for a block, as defined by the controls array.
+ *
* @param array $controls an array like {@link block_contents::$controls}.
- * @return HTML fragment.
+ * @return string HTML fragment.
*/
public function block_controls($controls) {
if (empty($controls)) {
* Prints a nice side block with an optional header.
*
* The content is described
- * by a {@link block_contents} object.
+ * by a {@link core_renderer::block_contents} object.
*
* <div id="inst{$instanceid}" class="block_{$blockname} block">
* <div class="header"></div>
* @param string $region the region the block is appearing in.
* @return string the HTML to be output.
*/
- function block(block_contents $bc, $region) {
+ public function block(block_contents $bc, $region) {
$bc = clone($bc); // Avoid messing up the object passed in.
if (empty($bc->blockinstanceid) || !strip_tags($bc->title)) {
$bc->collapsible = block_contents::NOT_HIDEABLE;
/**
* Calls the JS require function to hide a block.
+ *
* @param block_contents $bc A block_contents object
- * @return void
*/
protected function init_block_hider_js(block_contents $bc) {
if (!empty($bc->attributes['id']) and $bc->collapsible != block_contents::NOT_HIDEABLE) {
/**
* Render the contents of a block_list.
+ *
* @param array $icons the icon for each item.
* @param array $items the content of each item.
* @return string HTML
/**
* Output all the blocks in a particular region.
+ *
* @param string $region the name of a region on this page.
* @return string the HTML to be output.
*/
/**
* Output a place where the block that is currently being moved can be dropped.
+ *
* @param block_move_target $target with the necessary details.
* @return string the HTML to be output.
*/
* @param string $text HTML fragment
* @param component_action $action
* @param array $attributes associative array of html link attributes + disabled
- * @return HTML fragment
+ * @return string HTML fragment
*/
public function action_link($url, $text, component_action $action = null, array $attributes=null) {
if (!($url instanceof moodle_url)) {
}
/**
- * Implementation of action_link rendering
+ * Renders an action_link object.
+ *
+ * The provided link is renderer and the HTML returned. At the same time the
+ * associated actions are setup in JS by {@link core_renderer::add_action_handler()}
+ *
* @param action_link $link
* @return string HTML fragment
*/
/**
- * Similar to action_link, image is used instead of the text
+ * Renders an action_icon.
+ *
+ * This function uses the {@link core_renderer::action_link()} method for the
+ * most part. What it does different is prepare the icon as HTML and use it
+ * as the link text.
*
* @param string|moodle_url $url A string URL or moodel_url
* @param pix_icon $pixicon
}
/**
- * Internal implementation of single_button rendering
+ * Renders a single button widget.
+ *
+ * This will return HTML to display a form containing a single button.
+ *
* @param single_button $button
* @return string HTML fragment
*/
/**
* Returns a form with a single select widget.
+ *
* @param moodle_url $url form action target, includes hidden fields
* @param string $name name of selection field - the changing parameter in url
* @param array $options list of options
* @param string $formid
* @return string HTML fragment
*/
- public function single_select($url, $name, array $options, $selected='', $nothing=array(''=>'choosedots'), $formid=null) {
+ public function single_select($url, $name, array $options, $selected = '', $nothing = array('' => 'choosedots'), $formid = null) {
if (!($url instanceof moodle_url)) {
$url = new moodle_url($url);
}
/**
* Internal implementation of single_select rendering
+ *
* @param single_select $select
* @return string HTML fragment
*/
/**
* Returns a form with a url select widget.
+ *
* @param array $urls list of urls - array('/course/view.php?id=1'=>'Frontpage', ....)
* @param string $selected selected element
* @param array $nothing
* @param string $formid
* @return string HTML fragment
*/
- public function url_select(array $urls, $selected, $nothing=array(''=>'choosedots'), $formid=null) {
+ public function url_select(array $urls, $selected, $nothing = array('' => 'choosedots'), $formid = null) {
$select = new url_select($urls, $selected, $nothing, $formid);
return $this->render($select);
}
/**
* Internal implementation of url_select rendering
- * @param single_select $select
+ *
+ * @param url_select $select
* @return string HTML fragment
*/
protected function render_url_select(url_select $select) {
/**
* Returns a string containing a link to the user documentation.
* Also contains an icon by default. Shown to teachers and admin only.
+ *
* @param string $path The page link after doc root and language, no leading slash.
* @param string $text The text to be displayed for the link
* @return string
}
/**
- * Render icon
+ * Return HTML for a pix_icon.
+ *
* @param string $pix short pix name
* @param string $alt mandatory alt attribute
* @param string $component standard compoennt name like 'moodle', 'mod_forum', etc.
}
/**
- * Render icon
+ * Renders a pix_icon widget and returns the HTML to display it.
+ *
* @param pix_icon $icon
* @return string HTML fragment
*/
}
/**
- * Render emoticon
+ * Return HTML to display an emoticon icon.
+ *
* @param pix_emoticon $emoticon
* @return string HTML fragment
*/
}
/**
- * Produces the html that represents this rating in the UI
- * @param $page the page object on which this rating will appear
- */
+ * Produces the html that represents this rating in the UI
+ *
+ * @param rating $rating the page object on which this rating will appear
+ * @return string
+ */
function render_rating(rating $rating) {
global $CFG, $USER;
return $ratinghtml;
}
- /*
+ /**
* Centered heading with attached help button (same title text)
- * and optional icon attached
+ * and optional icon attached.
+ *
* @param string $text A heading text
* @param string $helpidentifier The keyword that defines a help page
* @param string $component component name
* @param string $iconalt icon alt text
* @return string HTML fragment
*/
- public function heading_with_help($text, $helpidentifier, $component='moodle', $icon='', $iconalt='') {
+ public function heading_with_help($text, $helpidentifier, $component = 'moodle', $icon = '', $iconalt = '') {
$image = '';
if ($icon) {
$image = $this->pix_icon($icon, $iconalt, $component, array('class'=>'icon'));
}
/**
- * Print a help icon.
+ * Returns HTML to display a help icon.
*
* @deprecated since Moodle 2.0
- * @param string $page The keyword that defines a help page
+ * @param string $helpidentifier The keyword that defines a help page
* @param string $title A descriptive text for accessibility only
* @param string $component component name
* @param string|bool $linktext true means use $title as link text, string means link text value
/**
* Implementation of user image rendering.
- * @param help_icon $helpicon
+ *
+ * @param old_help_icon $helpicon A help icon instance
* @return string HTML fragment
*/
protected function render_old_help_icon(old_help_icon $helpicon) {
}
/**
- * Print a help icon.
+ * Returns HTML to display a help icon.
*
* @param string $identifier The keyword that defines a help page
* @param string $component component name
/**
* Implementation of user image rendering.
- * @param help_icon $helpicon
+ *
+ * @param help_icon $helpicon A help icon instance
* @return string HTML fragment
*/
protected function render_help_icon(help_icon $helpicon) {
}
/**
- * Print scale help icon.
+ * Returns HTML to display a scale help icon.
*
* @param int $courseid
- * @param object $scale instance
- * @return string HTML fragment
+ * @param stdClass $scale instance
+ * @return string HTML fragment
*/
public function help_icon_scale($courseid, stdClass $scale) {
global $CFG;
/**
* Creates and returns a spacer image with optional line break.
*
- * @param array $attributes
- * @param boo spacer
+ * @param array $attributes Any HTML attributes to add to the spaced.
+ * @param bool $br Include a BR after the spacer.... DON'T USE THIS. Don't be
+ * laxy do it with CSS which is a much better solution.
* @return string HTML fragment
*/
public function spacer(array $attributes = null, $br = false) {
}
/**
- * Print the specified user's avatar.
+ * Returns HTML to display the specified user's avatar.
*
* User avatar may be obtained in two ways:
* <pre>
* $OUTPUT->render($userpic);
* </pre>
*
- * @param object Object with at least fields id, picture, imagealt, firstname, lastname
+ * @param stdClass $user Object with at least fields id, picture, imagealt, firstname, lastname
* If any of these are missing, the database is queried. Avoid this
* if at all possible, particularly for reports. It is very bad for performance.
* @param array $options associative array with user picture options, used only if not a user_picture object,
/**
* Internal implementation of user image rendering.
+ *
* @param user_picture $userpicture
* @return string
*/
/**
* Internal implementation of file tree viewer items rendering.
+ *
* @param array $dir
* @return string
*/
return $result;
}
+
/**
- * Print the file picker
+ * Returns HTML to display the file picker
*
* <pre>
* $OUTPUT->file_picker($options);
$fp = new file_picker($options);
return $this->render($fp);
}
+
/**
* Internal implementation of file picker rendering.
+ *
* @param file_picker $fp
* @return string
*/
}
/**
- * Prints the 'Update this Modulename' button that appears on module pages.
+ * Returns HTML to display the 'Update this Modulename' button that appears on module pages.
*
* @param string $cmid the course_module id.
* @param string $modulename the module name, eg. "forum", "quiz" or "workshop"
}
/**
- * Prints a "Turn editing on/off" button in a form.
+ * Returns HTML to display a "Turn editing on/off" button in a form.
+ *
* @param moodle_url $url The URL + params to send through when clicking the button
* @return string HTML the button
*/
}
/**
- * Prints a simple button to close a window
+ * Returns HTML to display a simple button to close a window
*
* @param string $text The lang string for the button's label (already output from get_string())
* @return string html fragment
/**
* Output an error message. By default wraps the error message in <span class="error">.
* If the error message is blank, nothing is output.
+ *
* @param string $message the error message.
* @return string the HTML to output.
*/
}
/**
- * Print a continue button that goes to a particular URL.
+ * Returns HTML to display a continue button that goes to a particular URL.
*
* @param string|moodle_url $url The url the button goes to.
* @return string the HTML to output.
}
/**
- * Prints a single paging bar to provide access to other pages (usually in a search)
+ * Returns HTML to display a single paging bar to provide access to other pages (usually in a search)
*
* @param int $totalcount The total number of entries available to be paged through
* @param int $page The page you are currently viewing
/**
* Internal implementation of paging bar rendering.
+ *
* @param paging_bar $pagingbar
* @return string
*/
/**
* Output the place a skip link goes to.
+ *
* @param string $id The target name from the corresponding $PAGE->requires->skip_link_to($target) call.
* @return string the HTML to output.
*/
/**
* Outputs a heading
+ *
* @param string $text The text of the heading
* @param int $level The level of importance of the heading. Defaulting to 2
* @param string $classes A space-separated list of CSS classes
/**
* Outputs a box.
+ *
* @param string $contents The contents of the box
* @param string $classes A space-separated list of CSS classes
* @param string $id An optional ID
/**
* Outputs the opening section of a box.
+ *
* @param string $classes A space-separated list of CSS classes
* @param string $id An optional ID
* @return string the HTML to output.
/**
* Outputs the closing section of a box.
+ *
* @return string the HTML to output.
*/
public function box_end() {
/**
* Outputs a container.
+ *
* @param string $contents The contents of the box
* @param string $classes A space-separated list of CSS classes
* @param string $id An optional ID
/**
* Outputs the opening section of a container.
+ *
* @param string $classes A space-separated list of CSS classes
* @param string $id An optional ID
* @return string the HTML to output.
/**
* Outputs the closing section of a container.
+ *
* @return string the HTML to output.
*/
public function container_end() {
* <</ul>>
* </pre>
*
- * @param array[]tree_item $items
- * @param array[string]string $attrs html attributes passed to the top of
- * the list
+ * @param array $items
+ * @param array $attrs html attributes passed to the top ofs the list
* @return string HTML
*/
- function tree_block_contents($items, $attrs=array()) {
+ public function tree_block_contents($items, $attrs = array()) {
// exit if empty, we don't want an empty ul element
if (empty($items)) {
return '';
/**
* Return the navbar content so that it can be echoed out by the layout
+ *
* @return string XHTML navbar
*/
public function navbar() {
return $navbarcontent;
}
+ /**
+ * Renders a navigation node object.
+ *
+ * @param navigation_node $item The navigation node to render.
+ * @return string HTML fragment
+ */
protected function render_navigation_node(navigation_node $item) {
$content = $item->get_content();
$title = $item->get_title();
* If the theme does not set characters, appropriate defaults
* are set automatically. Please DO NOT
* use < > » - these are confusing for blind users.
+ *
* @return string
*/
public function rarrow() {
* If the theme does not set characters, appropriate defaults
* are set automatically. Please DO NOT
* use < > » - these are confusing for blind users.
+ *
* @return string
*/
public function larrow() {
* The custom menu this method produces makes use of the YUI3 menunav widget
* and requires very specific html elements and classes.
*
- * @see render_custom_menu()
+ * @see core:renderer::render_custom_menu()
*
* @staticvar int $submenucount
* @param custom_menu_item $menunode
}
}
-/// RENDERERS
-
/**
* A renderer that generates output for command-line scripts.
*
* The implementation of this renderer is probably incomplete.
*
* @copyright 2009 Tim Hunt
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class core_renderer_cli extends core_renderer {
+
/**
* Returns the page header.
+ *
* @return string HTML fragment
*/
public function header() {
/**
* Returns a template fragment representing a Heading.
+ *
* @param string $text The text of the heading
* @param int $level The level of importance of the heading
* @param string $classes A space-separated list of CSS classes
/**
* Returns a template fragment representing a fatal error.
+ *
* @param string $message The message to output
* @param string $moreinfourl URL where more info can be found about the error
* @param string $link Link for the Continue button
/**
* Returns a template fragment representing a notification.
+ *
* @param string $message The message to include
* @param string $classes A space-separated list of CSS classes
* @return string A template fragment for a notification
* encoded error messages, all other output is ignored.
*
* @copyright 2010 Petr Skoda
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
*/
class core_renderer_ajax extends core_renderer {
+
/**
* Returns a template fragment representing a fatal error.
+ *
* @param string $message The message to output
* @param string $moreinfourl URL where more info can be found about the error
* @param string $link Link for the Continue button
return json_encode($e);
}
- public function notification($message, $classes = 'notifyproblem') {
- }
+ /**
+ * Used to display a notification.
+ * For the AJAX notifications are discarded.
+ *
+ * @param string $message
+ * @param string $classes
+ */
+ public function notification($message, $classes = 'notifyproblem') {}
- public function redirect_message($encodedurl, $message, $delay, $debugdisableredirect) {
- }
+ /**
+ * Used to display a redirection message.
+ * AJAX redirections should not occur and as such redirection messages
+ * are discarded.
+ *
+ * @param moodle_url|string $encodedurl
+ * @param string $message
+ * @param int $delay
+ * @param bool $debugdisableredirect
+ */
+ public function redirect_message($encodedurl, $message, $delay, $debugdisableredirect) {}
+ /**
+ * Prepares the start of an AJAX output.
+ */
public function header() {
// unfortunately YUI iframe upload does not support application/json
if (!empty($_FILES)) {
@header('Content-type: application/json; charset=utf-8');
}
- /// Headers to make it not cacheable and json
+ // Headers to make it not cacheable and json
@header('Cache-Control: no-store, no-cache, must-revalidate');
@header('Cache-Control: post-check=0, pre-check=0', false);
@header('Pragma: no-cache');
@header('Accept-Ranges: none');
}
- public function footer() {
- }
-
- public function heading($text, $level = 2, $classes = 'main', $id = null) {
- }
-}
+ /**
+ * There is no footer for an AJAX request, however we must override the
+ * footer method to prevent the default footer.
+ */
+ public function footer() {}
+ /**
+ * No need for headers in an AJAX request... this should never happen.
+ * @param string $text
+ * @param int $level
+ * @param string $classes
+ * @param string $id
+ */
+ public function heading($text, $level = 2, $classes = 'main', $id = null) {}
+}
\ No newline at end of file
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
-
/**
* Library functions to facilitate the use of JavaScript in Moodle.
*
- * @package core
- * @subpackage lib
- * @copyright 2009 Tim Hunt, 2010 Petr Skoda
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * Note: you can find history of this file in lib/ajax/ajaxlib.php
+ *
+ * @copyright 2009 Tim Hunt, 2010 Petr Skoda
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package core
+ * @category output
*/
defined('MOODLE_INTERNAL') || die();
-// note: you can find history of this file in lib/ajax/ajaxlib.php
-
/**
* This class tracks all the things that are needed by the current page.
*
* individual methods for details.
*
* @copyright 2009 Tim Hunt, 2010 Petr Skoda
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
* @since Moodle 2.0
+ * @package core
+ * @category output
*/
class page_requirements_manager {
- /** List of string available from JS */
+
+ /**
+ * @var array List of string available from JS
+ */
protected $stringsforjs = array();
- /** List of JS variables to be initialised */
+
+ /**
+ * @var array List of JS variables to be initialised
+ */
protected $jsinitvariables = array('head'=>array(), 'footer'=>array());
- /** Included JS scripts */
+
+ /**
+ * @var array Included JS scripts
+ */
protected $jsincludes = array('head'=>array(), 'footer'=>array());
- /** List of needed function calls */
+
+ /**
+ * @var array List of needed function calls
+ */
protected $jscalls = array('normal'=>array(), 'ondomready'=>array());
+
/**
- * List of skip links, those are needed for accessibility reasons
- * @var array
+ * @var array List of skip links, those are needed for accessibility reasons
*/
protected $skiplinks = array();
+
/**
- * Javascript code used for initialisation of page, it should be relatively small
- * @var array
+ * @var array Javascript code used for initialisation of page, it should
+ * be relatively small
*/
protected $jsinitcode = array();
+
/**
- * Theme sheets, initialised only from core_renderer
- * @var array of moodle_url
+ * @var array of moodle_url Theme sheets, initialised only from core_renderer
*/
protected $cssthemeurls = array();
+
/**
- * List of custom theme sheets, these are strongly discouraged!
+ * @var array of moodle_url List of custom theme sheets, these are strongly discouraged!
* Useful mostly only for CSS submitted by teachers that is not part of the theme.
- * @var array of moodle_url
*/
protected $cssurls = array();
+
/**
- * List of requested event handlers
- * @var array
+ * @var array List of requested event handlers
*/
protected $eventhandlers = array();
+
/**
- * Extra modules
- * @var array
+ * @var array Extra modules
*/
protected $extramodules = array();
- /** Flag indicated head stuff already printed */
+
+ /**
+ * @var bool Flag indicated head stuff already printed
+ */
protected $headdone = false;
- /** Flag indicating top of body already printed */
+
+ /**
+ * @var bool Flag indicating top of body already printed
+ */
protected $topofbodydone = false;
- /** YUI PHPLoader instance responsible for YUI2 loading from PHP only */
+ /**
+ * @var YAHOO_util_Loader YUI PHPLoader instance responsible for YUI2 loading
+ * from PHP only
+ */
protected $yui2loader;
- /** YUI PHPLoader instance responsible for YUI3 loading from PHP only */
+
+ /**
+ * @var stdClass YUI PHPLoader instance responsible for YUI3 loading from PHP only
+ */
protected $yui3loader;
- /** YUI loader information for YUI3 loading from javascript */
+
+ /**
+ * @var stdClass YUI loader information for YUI3 loading from javascript
+ */
protected $M_yui_loader;
- /** some config vars exposed in JS, please no secret stuff there */
+
+ /**
+ * @var array Some config vars exposed in JS, please no secret stuff there
+ */
protected $M_cfg;
- /** stores debug backtraces from when JS modules were included in the page */
+
+ /**
+ * @var array Stores debug backtraces from when JS modules were included in the page
+ */
protected $debug_moduleloadstacktraces = array();
/**
}
/**
- * This method adds yui2 modules into the yui3 JS loader-
- * @return void
+ * This method adds yui2 modules into the yui3 JS loader so that they can
+ * be easily included for use in JavaScript.
*/
protected function add_yui2_modules() {
//note: this function is definitely not perfect, because
* @param string|moodle_url $url The path to the .js file, relative to $CFG->dirroot / $CFG->wwwroot.
* For example '/mod/mymod/customscripts.js'; use moodle_url for external scripts
* @param bool $inhead initialise in head
- * @return void
*/
- public function js($url, $inhead=false) {
+ public function js($url, $inhead = false) {
$url = $this->js_fix_url($url);
$where = $inhead ? 'head' : 'footer';
$this->jsincludes[$where][$url->out()] = $url;
* is put into the page header, otherwise it is loaded in the page footer.
*
* @param string|array $libname the name of the YUI2 library you require. For example 'autocomplete'.
- * @return void
*/
public function yui2_lib($libname) {
$libnames = (array)$libname;
/**
* Returns the actual url through which a script is served.
+ *
* @param moodle_url|string $url full moodle url, or shortened path to script
* @return moodle_url
*/
/**
* Find out if JS module present and return details.
+ *
* @param string $component name of component in frankenstyle, ex: core_group, mod_forum
* @return array description of module or null if not found
*/
$module = null;
-
if (strpos($component, 'core_') === 0) {
// must be some core stuff - list here is not complete, this is just the stuff used from multiple places
// so that we do nto have to repeat the definition of these modules over and over again
/**
* Append YUI3 module to default YUI3 JS loader.
- * The structure of module array is described at http://developer.yahoo.com/yui/3/yui/:
+ * The structure of module array is described at {@link http://developer.yahoo.com/yui/3/yui/}
+ *
* @param string|array $module name of module (details are autodetected), or full module specification as array
* @return void
*/
/**
* Add theme stylkesheet to page - do not use from plugin code,
* this should be called only from the core renderer!
+ *
* @param moodle_url $stylesheet
* @return void
*/
* @param array $arguments and array of arguments to be passed to the function.
* When generating the function call, this will be escaped using json_encode,
* so passing objects and arrays should work.
- * @param bool $ondomready
- * @param int $delay
- * @return void
+ * @param bool $ondomready If tru the function is only called when the dom is
+ * ready for manipulation.
+ * @param int $delay The delay before the function is called.
*/
public function js_function_call($function, array $arguments = null, $ondomready = false, $delay = 0) {
$where = $ondomready ? 'ondomready' : 'normal';
* already loaded.
* @param bool $ondomready wait for dom ready (helps with some IE problems when modifying DOM)
* @param array $module JS module specification array
- * @return void
*/
public function js_init_call($function, array $extraarguments = null, $ondomready = false, array $module = null) {
$jscode = js_writer::function_call_with_Y($function, $extraarguments);
* @param string $jscode
* @param bool $ondomready wait for dom ready (helps with some IE problems when modifying DOM)
* @param array $module JS module specification array
- * @return void
*/
public function js_init_code($jscode, $ondomready = false, array $module = null) {
$jscode = trim($jscode, " ;\n"). ';';
* alert(M.str.moodle.fullnamedisplay);
*
* To substitute the placeholder at client side, use M.util.get_string()
- * function. It implements the same logic as {@see get_string()}:
+ * function. It implements the same logic as {@link get_string()}:
*
* // require the string in PHP but keep {$a} as it is
* $PAGE->requires->string_for_js('fullnamedisplay', 'moodle');
* @param string $event A valid DOM event (click, mousedown, change etc.)
* @param string $function The name of the function to call
* @param array $arguments An optional array of argument parameters to pass to the function
- * @return void
*/
public function event_handler($selector, $event, $function, array $arguments = null) {
$this->eventhandlers[] = array('selector'=>$selector, 'event'=>$event, 'function'=>$function, 'arguments'=>$arguments);
/**
* Returns js code to be executed when Y is available.
- * @return unknown_type
+ * @return string
*/
protected function get_javascript_init_code() {
if (count($this->jsinitcode)) {
/**
* Returns html tags needed for inclusion of theme CSS
+ *
* @return string
*/
protected function get_css_code() {
/**
* Adds extra modules specified after printing of page header
+ *
* @return string
*/
protected function get_extra_modules_code() {
}
/**
- * @return boolean Have we already output the code in the <head> tag?
+ * Have we already output the code in the <head> tag?
+ *
+ * @return bool
*/
public function is_head_done() {
return $this->headdone;
}
/**
- * @return boolean Have we already output the code at the start of the <body> tag?
+ * Have we already output the code at the start of the <body> tag?
+ *
+ * @return bool
*/
public function is_top_of_body_done() {
return $this->topofbodydone;
/**
* Invalidate all server and client side JS caches.
- * @return void
*/
function js_reset_all_caches() {
global $CFG;
set_config('jsrev', empty($CFG->jsrev) ? 1 : $CFG->jsrev+1);
fulldelete("$CFG->cachedir/js");
-}
-
+}
\ No newline at end of file
