MoodleDocs - User contributions [en]

Moodle forms library

2021-06-11T15:01:10Z

Demsley: /* display */

{{obsolete}}

'''This was a proposal for discussion that was not used.

==Former discussions about documentation of the forms library that is used in Moodle==

The [[lib/formslib.php]] page is about the documentation of the forms library that was implemented as a result of old discussions and is archived here.

==And now, on with the history ...==

The OU has developed quite a nice in-house library to simplify creating Moodle editing forms. We would like to contribute it back to the community, and then as part of the accessibility work we are comissioning, get all Moodle forms modified to use it. However, before we can contribute it back, we need to get consensus withing the community that it is right for Moodle, and we need to tidy up the code a bit.

This document outlines how the library should work after cleaning up, so the community can see whether they like it, and OU developers know what is involved in the cleanup.

==What the system will be capable of==

The library allows developers to create editing forms by creating a high-level representation of the form as a data-structure in memory, configuring all necessary options, and setting initial values of fields, and then the library generates the actual HTML of the form to include in the page.

We are not planning to change significantly the way that Moodle editing forms look and function. However, by putting all the HTML (and JavaScript, CSS, ...) generation in one place, we make it much easier to make systematic improvements to accessibility, usability, client-side validation, etc. in future. Indeed, the OU's code already generates HTML that is a bit more accessible that most Moodle forms.

By allowing developers to think at a higher level, we make their life easier, in the same way that datalib saves them from worrying about the details of SQL most of the time.

The general way the library will work is that it will assume sensible defaults for everything to reduce the amount that has to be typed. So for a lot of input fields, you will only have to specify

# the field type (e.g. text, think <input type="" ... />, However the hope would be to move towards higher-level types, such as integer, path, url, as in require_param, etc.)
# the field name (think <input name="" ... />).

Everything else that is needed will be derived from these using sensible defaults. We need label text? We'll look up the field name in the lang file (each form will specify which lang file to use). We need a help link? Well, use /lang/en_utf8/help$langfile/$name.html. We need a field size? Each type will have a sensible default.

However, if you want to override any of these defaults, you can by setting that option explicitly. Because there will be lots of options, and normally you will only need to change a few, the library will use a named attribute style, so example code would look like:

<code php>
$field = new text_field('fieldname');
$field->set_set('size', 30);
$field->set_set('label', 'lablestring');

// or

$field = new text_field('fieldname');
$field->set_set(array('size' => 30, 'label' => 'lablestring'));

// or

$field = new text_field('fieldname', array(
'size' => 30,
'label' => 'lablestring'
));
</code>

In this example, 'lablestring' would again get looked up in the lang file automatically.

For this situation, where there are lots of options available, but most people only need to change a few, I think this style of API works better than PHP function calls with lots of optional parameters. The options available for each field type will be documented in the comment where that class is defined.

The library is designed to make it easy to add new field types, or new options to existing field types. Indeed, that is how the library has evolved so far: a bit at a time as needed.

New field types are just new PHP classes, and they are likely to be subclasses of a base class that only change a few things. They don't even have to be defined in the central form library. If you need an specialist field type only within one (e.g. contrib) module, you can create a new field-type subclass in that module code and use it in that modules forms without having to touch core code. And if we later want to move that field type into core, it is trivial to move the class definition.

Since we will have to tidy up the code anyway, all the function/class/method/option names in the API are potentially changable.

==PHP API==

Each thing in the API will be a PHP class, these basically fall into three categories: the whole form, groupings of form fields, and individual field types. Note that the groupings are currently only used for functional reasons, like showing or hiding groups of elements. Logical groupings, that would correspond to <fieldset> tags for accessibility, are not included yet, but could be added.

I am just going to list all the possible method calls. I will assume that it is clear what they do from their names (and I am running out of time).

===The whole form===

There is a class to represent a form, and most of the time you will be able to do everything you want to do by calling methods on this class, and you don't have to worry about the rest of the API.

<code php>
$mf = new moodle_form($langfile);

$field = &$mf->add($fieldtype, $fieldname, $fieldoptions, $insertbefore);
$field = &$mf->add_item($fieldobject, $insertbefore); // $insertbefore is optional. By default things are inserted at the end of the form.
$field = &$mf->remove($fieldname);
$field = &$mf->get($fieldname);
</code>

These let you add or remove things from the form. The field you have just done stuff to is returned, but most of the time you will not bother to do anything with the return value. These method work with groups, etc. not just fields.

<code php>
$mf->set_action($url);
$mf->set_init_html_editor(); // There was a reason why the library can't guess this from the list of fields.
$mf->set_submit_caption($langstringid);
$mf->set_hidden($fieldname, $value);
$mf->set_value($fieldname, $value); // The initial value for this field. (or use the $form attribute on show()).
$mf->set_error($fieldname, $message); // Error message to be displayed in red next to this field if you are doing server-side validation.

$mf->show($action, $form);
</code>

Show the form. $form is an object holding the default value of each field that has not already been set using set_value().

<code php>
$mf->add_xhtml($htmlphpcode, $insertbefore);
$mf->set_xhtml_param($name, $value);
</code>

You can insert arbitrary bits of HTML or PHP code into the form using this. When outputting the form, the library does '''eval('?>'.$htmlphpcode.'<?php ');''' in a place where $form is in scope, and the variables passed in via set_xhtml_param are available from an array as $xmlform[$name].

<code php>
$new_mf = moodle_form::loadfile($xmlfilename);
$new_mf = moodle_form::loadstring($xmlstring);
</code>

Create a whole form using the XML syntax mentioned below.

===Fields===

The library also has classes representing the different field types, which you can use if you want.

$field = new xxxx_field($name, $options_array); // where xxxx is one of the field types below.
$field->set($optionname, $optionvalue);
$field->set($optionarray); // Array of $optionname => $optionvalue pairs.
$optionvalue = $field->get($optionname);

$field->set_value($value); // Sets the initial value of this field.

$field->output($form); // Print this form element.

Normally you won't call output() directly. You will call $mf->output, which will call $field->output on each field for you, but you can use this yourself if you just want to print one form control anywhere you like, not as part of a form.

===Groups===

Groups (which will probably get renamed to conditionalshow, but I don't want to change all the examples just now) allow you to show or hide a collection of fields, depending on the setting of another field.

groups have basically the same methods as fields, but $name is optional. $name has no function, unless you need to identify the group later for a call the $mf->get($groupname);

There are a few extra methods they have over fields:

<code php>
$field = &$group->add($fieldtype, $fieldname, $fieldoptions, $insertbefore);
$field = &$group->add_item($fieldobject, $insertbefore);
$field = &$group->remove($fieldname);
$field = &$group->get($fieldname);

$group->set_condition($conditionfield, $conditionvalue);
</code>

The elements within the group will only be visible when the field $conditionfield elsewhere in the form has value $conditionvalue. This works best when $conditionfield is a dropdown.

Do we also want a conditionalenable group that enables/disables a bunch of fields, rather than showing or hiding them?

===Multiples===

This lets you do things like enter multiple usernames, as in the 'working example' below. You would also use it on the editing form for multiple choice questions, to enter any number of answers with matching grades.

Again, they support the same methods as fields, and also:

<code php>
$field = &$multiple->add($fieldtype, $fieldname, $fieldoptions, $insertbefore);
$field = &$multiple->add_item($fieldobject, $insertbefore);
$field = &$multiple->remove($fieldname);
$field = &$multiple->get($fieldname);

$multiple->set_max($number);
</code>

For accessibility reasons, multiples work by printing a certain number of copies into the HTML, and these are then shown or hidden by the JavaScript. This is for accessibility reasons, and so the forms work without JavaScript. max is the number of copies that are printed. It defaults to 10.

==Field types initially supported==

All field will support the options:

'''lable''' the field lable. This is a string that is looked up in the language file. Or, if the string starts with an '=' character, then this is trimmed off, and the rest of the string is used literally. Defaults to name.

'''help''' the name of the help file to link to. Defaults to name. Setting to '' removes the help icon.

'''helpalt''' the langstring to use for the tooltip of the help icon.

'''optional''' if set to 'yes', then adds a checkbox before the field to enable or diable it. The checkbox's name is name is constructed by taking the field name and appending 'enable'. If you want another name, set this option to the checkbox name, instead of 'yes'.

'''needcapability''' this is mainly aimed at 1.7 roles and permissions. Will hide this field unless the user has the named capability. At first, this will only recognise the values admin, teacher, student, noneditingteacher, guest, and translate these into the obvious isadmin() type calls.

More options will probably get added in future.

===display===

Just display a value with a label, the value can't be edited.

===text===

Text input box.

Supports the additional options:

'''required''' a regexp that is used for client-side validation against that regexp.

'''size''' as in <input size="" ... />

===file===

File upload box.

===date===

Date, like quiz open and close dates.

===html===

The standard HTML editor, or just a text area, depending on the settings. (This calls print_textarea).

===dropdown===

A dropdown menu. This field has the additional methods:

$dropdown->add_option($value, $label);
$dropdown->remove_option($value);

$label is optional. By default: if $value is an integer, use that integer as the label, otherwise look $value up in the langfile.

Dropdown supports the additional option:

'''default''' which option to select by default.

===radio===

A set of linked radio buttons, which are defined in the same way as dropdown menu options.

===multiselect===

A list box where you can select multiple options, which are defined in the same way as dropdown menu options.

Actually, I think we should change the implementation of this to use a set of checkboxes when there are fewer than about a dozen options, and automatically switch to useing a list box when there are more than that. And maybe add an optional parameter to force the listbox/checkbox decision one way or the other.

===yesno===

A dropdown menu with just the two options 'yes' and 'no'.

===user===

A flashy text box where you can enter user's names, and it does AJAX stuff to help you auto-complete them.

===visible===

This generates the standard "Visible to students" field that appears on add/update module forms.

===groupmode===

This generates the standard "Group mode" field that appears on add/update module forms.

==XML form definition format==

This provides the quickest way to create most forms. It should be clear how this translates into the PHP API calls defined above. XML elements $mf->add() calls. XML attributes correspond either to required information, or to set_opt calls. Form filds, like dropdowns, that need extra information get it from child elements. See the examples below for what it looks like.

==A working example==

Here is an example of a form produced with the current (un-cleaned-up) version of the OU's library. The form looks like this:

[[Image:Formproposal_Add_newsfeed_form.png]]

There is some OU-specific stuff here, like presentation and authids, and the fact that we reveal $user->username to teachers. I am assuming you can filter that out.

More interestingly, notice that

* The required field Name has not been filled it, so its label is red, and the create button is disabled. Below, you will see that anything typed into this field will actually be validated against a regular expression.
* The user field type does cool AJAX to save you typing the whole name.
* After you have added one user as a poster, a second box appeared where we could type a second user name. And when we finish typing here, a third box will appear.

The XML defining the form looks like this:

<code php>
<editform langfile='block_newsfeed'>
<text name='location'/>
<text name='name' required='\S'/>
<text name='pres' required='^([0-9]{2}[a-zA-Z]?)?$'/>
<html name='summary'/>
<dropdown name='type'>
<option value='internal'>type_internal</option>
<option value='external'>type_external</option>
</dropdown >
<group requiredname="type" requiredvalue="external">
<item type='text' name='url'/>
</group>
<group requiredname="type" requiredvalue="internal">
<date name='startdate'/>
<dropdown name='public'>
<option value='1'>access_public</option>
<option value='0'>access_private</option>
</dropdown >
<text name='defaultauthid'/>
<multiple>
<text name='optionalauthids' required='^([A-Z0-9]+)?$'/>
</multiple>
<multiple>
<user name='posters'/>
</multiple>
<multiple>
<user name='approvers'/>
</multiple>
</group>
</editform>
</code>

The PHP code that creates the form definition ($xf), and the object with all the current values ($form) and sets all the default values looks like this:

<code php>
$xf=xml_form::load_file('editfeed.xml');
$xf->set_init_html_editor(true);
$form=new stdClass;
$newsfeedid=optional_param('newsfeedid',0,PARAM_INT);
if($newsfeedid) {
$nf=feed_system::$inst->get_feed($newsfeedid);
$form->location=$nf->get_folder()->get_path();
$xf->set_hidden('newsfeedid',$newsfeedid);

$form->name=$nf->get_name();
$form->pres=$nf->get_pres();
if($form->pres==null) {
$form->pres='';
}
$form->summary=$nf->get_summary();
if(is_a($nf,'external_news_feed')) {
$form->type='external';
$form->url=$form->get_url();
} else {
$form->type='internal';
$form->startdate=$nf->get_start_date();
$form->public=$nf->is_public();
$form->defaultauthid=$nf->get_default_authid();
xml_form::set_multiple($form,'optionalauthids',$nf->get_optional_authids());
xml_form::set_multiple($form,'posters',$nf->get_poster_usernames());
xml_form::set_multiple($form,'approvers',$nf->get_approver_usernames());
$form->newsfeedid=$newsfeedid;
}

} else {
$folderid=required_param('folderid',PARAM_INT);
$lf=feed_system::$inst->get_location_folder($folderid,null);
$nf=null;
$xf->set_submit_caption(get_string('create'));
$form->location=$lf->get_path();
$xf->set_hidden('newsfeedid',0);
}

// ... print_header and other boring bits.

print_simple_box_start('center');
$xf->show(basename(__FILE__), $form);
print_simple_box_end();
</code>

==Examples of converting existing Moodle forms==

These are four example forms that Marting Dougiamas asked to see how we would handle.

===Add resource -> Link to a file or web site===

[[Image:Formproposal_Add link resource.png]]

I have taken the liberty of changing the way the window options work on this form. Instead of having a show/hide window settings button, and when that is turned on showing all the options for both same window and new window, I have changed it to be a same window/popup window dropdown, and depending on the setting there, showing or hiding the particular set of options. It would also be possible to use the library to generate the existing form.

This form contains some very specific bits, namely the location field and the parameters sections. For now I have kept the existing code to generate these bits. If fields like the location field were used in other places, we could add a url field type. I don't see any future in generalising the parameters bit, though the code to generate it could be cleaned up. I just copied and pasted the existing code, and made the minimal changes.

I've used a multiselect for the window options. That will require a small change to the response processing code.

<pre>
$mf = moodle_form::loadstring('
<editform langfile="resource">
<text name="name" help=""/>
<htmlarea name="summary"/>
<xhtml label="location"><![CDATA[
echo "<input type=\"text\" name=\"reference\" size=\"90\" value=\"$form->reference\" alt=\"reference\" /><br />";
button_to_popup_window ("/files/index.php?id=$form->course&choose=form.reference", "coursefiles", $xmlform['strchooseafile'], 500, 750, $xmlform['strchooseafile']);
echo "<input type=\"button\" name=\"searchbutton\" value=\"$xmlform['strsearch'] ...\" ".
"onclick=\"return window.open('$CFG->resource_websearch', 'websearch', 'menubar=1,location=1,directories=1,toolbar=1,scrollbars,resizable,width=800,height=600');\" />\n";
if ($CFG->resource_allowlocalfiles) {
button_to_popup_window ("/mod/resource/type/file/localfile.php?choose=form.reference",
"localfiles", get_string('localfilechoose', 'resource'), 400, 600,
get_string('localfilechoose', 'resource'));
}
]]></xhtml>
<url name="location" showuploadbutton="1" showsearchbutton="1" help=""/>
<dropdown name="windowpopup">
<option value='0'>pagewindow</option>
<option value='1'>newwindow</option>
</dropdown>
<group requiredname="newwindow" requiredvalue="0">
<hidden name="hframepage" value="0"/>
<multiselect name="framepage" help="">
<option value="1">frameifpossible</option>
</multiselect>
</group>
<group requiredname="newwindow" requiredvalue="1">
<multiselect name="windowoptions">
</multiselect>
<integer name="resource_popupwidth" label="resource_popupwidth"/>
<integer name="resource_popupheight" label="resource_popupheight"/>
</group>
<yesno name="parameters"/>
<group requiredname="newwindow" requiredvalue="1">
<xhtml><![CDATA[
<table align="center">

<tr>
<td align="center"><?php print_string("parameter", "resource") ?></td>
<td align="center"><?php print_string("variablename", "resource") ?></td>
</tr>

<?php

for ($i=0; $i < $xmlform['maxparameters']; $i++) {
echo "<tr>\n";
echo "<td valign=\"top\">\n";
echo "<select name=\"parameter$i\">\n";
echo "<option value=\"-\">-- ".get_string('chooseparameter', 'resource')." --</option>\n";
foreach ($xmlform['parameters'] as $field=>$fieldarr) {
if ($fieldarr['value'] === "optgroup") {
echo "<optgroup label=\"{$fieldarr['langstr']}\">\n";
} elseif ($fieldarr['value'] === "/optgroup") {
echo "</optgroup>\n";
} else {
echo "<option value=\"$field\"";
if ($xmlform['alltextfield'][$i]['parameter'] == $field) {
echo " selected=\"selected\"";
}
echo ">{$fieldarr['langstr']}</option>\n";
}
}
echo "</select>\n";
echo "</td>\n";
echo "<td valign=\"top\">\n";
echo "<input type=\"text\" name=\"parse$i\" value=\"{$xmlform['alltextfield'][$i]['parse']}\" alt=\"parameter$i\"/>\n";
echo "</td>\n";
echo "</tr>\n";
}

?>
</table>
]]></xhtml>
</group>
')
$mf->set_xhtml_param('strchooseafile', get_string(...));
$mf->set_xhtml_param('strsearch', get_string(...));

$mf->set_xhtml_param('maxparameters', $this->maxparameters);
$mf->set_xhtml_param('parameters', $this->parameters);
$mf->set_xhtml_param('alltextfield', $alltextfield); // Assuming that this code is after the end of setup() in mod\resource\type\file\resource.class.php

$winopt = $mf->get('windowoptions');
foreach ($RESOURCE_WINDOW_OPTIONS as $optionname) {
$defaultvalue = "resource_popup$optionname";
$form->$optionname = $CFG->$defaultvalue;
if ($optionname != 'height' && $optionname != 'width') {
$winopt->add_option($optionname, "str$optionname");
}
}
</pre>

===Add quiz===

[[Image:Formproposal_Add quiz form.png]]

To convert this form, we need to do something special for the "students may review" bit. You could either invent an new <optiongrid> type, which would be quite easy to implement. That is the option used below. Alternatively, you could use the feature for including arbitrary HTML and PHP in the form, and keep the existing code for generating this part of the form. Since the existing layout breaks when you make the browser window narrow, as in the screenshot, I would be inclined to redo it.

<code php>
$mf = moodle_form::loadstring('
<editform langfile="quiz" help="">
<text name="name"/>
<htmlarea name="introduction"/>
<date name="available" label="quizopen" optional="yes"/>
<date name="due" label="quizclose" optional="yes"/>
<real name="timelimit" lableafter="minutes" helpalt="quiztimer" optional="yes"/>
<dropdown name="questionsperpage">
<option value='0'>unlimited</option>

</dropdown>
<yesno name="shufflequestions"/>



<optiongrid name="reviewoptions">
<col name="responses"/>
<col name="scores"/>
<col name="feedback"/>
<col name="answers"/>
<row name="immediately" lable="reviewimmediately"/>
<row name="open" lable="reviewopen"/>
<row name="closed" lable="reviewclosed"/>
</optiongrid>



<groupmode/>
<visible/>
')
$questionsperpage =& $mf->get('questionsperpage');
for ($i = 1; $i <= 50; $i += 1) {
$questionsperpage->add_option($i);
}
</code>

This does not take into account the settings on http://''example.com''/moodle/admin/module.php?module=quiz, which lets the admin move certain quiz options to be hidden behind an "advanced" option. To implement this you would need to add a show/hide advanced control (I would do this as a <yesno name="showadvanced"/>, and an empty advanced group, then use some PHP code like

<code php>
$fix = 0;
$advgroup = $mf->get_field('advanced');

if ($CFG->quiz_fix_timelimit) {
$item = &$mf->remove('timelimit');
$advgroup->add($item)
$fix = 1;
}
// ... and so on, for all the other options. Or you could try to be clever
// and do this as a loop over an array of field names ... then
if (!$fix) {
$form->remove('showadvanced');
$form->remove('advanced');
}
</code>

===Add database===

[[Image:Formproposal_Add_database_form.png]]

I won't type out full code for this example most of it is simple, and it should be clear how to do it given the above examples, just comment on a couple of things:

'''Entries required before viewing''' I assume this is only indented because the label is so long that having it all lined up would break the table layout. I think our code using CSS for layout just word-wraps long labels and keeps everything aligned, which I think is better.

'''Allow posts to be rated?''' I would put the disabled controls in a group that only appears if the checkbox is checked, so that those controls show and hide, rather than enabling or disabling. However, if we want to keep this the same as it is now, you could implemnt the conditionalenable group type.

===Manage groups for a course===

This sort of form is currently beyond what the form library was designed to produce. I would leave this as hand-coded HTML. In time, the form library may gain some AJAX field types for selecting students, and such like, that could usefully be within a redesigned version of this form. Since the form field types just output HTML and Javascript, it should be possible to use them within hand-crafted forms.

[[Image:Formproposal_Groups_form.png]]

==Questions==

Do we need a syntax like lable='langfile:langstring' for using lang strings from other lang files where necessary? '''yes'''

Where does this live. I think the main library file that people have to include should be lib/formlib.php, and that is all anyone needs to include. However, to we break each field type into its own PHP file, perhaps in a lib/formlib directory, to make it easier to add new field types in future? '''Probably all in one file'''

Some form fields will need bits of CSS and JavaScript to work. Do we add the CSS to the standard theme, and combine all the javascript into a single library somewhere, or do we break it up into the individual field types, and recombine it dynamically at runtime? I think I favour breaking up the PHP code, but keeping all the JS and CSS in one place. '''Should use YUI were possible. We will still need some custom JavaScript and CSS though. Where?'''

Do we use this for vaidation as well? '''Yes.''' Currently Moodle PHP files that do forms tend to look like:

<pre>
$var1 = require/optional_param(...);
// etc. for all the other form variables.

if (data_submitted && confirm_sesskey()) {
// Try to process submitted data.
if (/*processing ok*/)
// Redirect away
} else {
// Set initial form values.
}

// Lots of code to output the form HTML. Of maybe include(somthing.html);
</pre>

The proposal is to change this to something like

<pre>
$mf = new moodle_form();
// Setup $mf with the form structure

$form = new stdClass;
if ($mf->validate_submitted_data($form)) { // Pass by reference to get data back.
// Try to process submitted data in $form
if (/*processing ok*/)
// Redirect away
} else {
// Set initial values in $form
}

$mf->display($form)
</pre>

AMD Modal

2021-05-19T11:52:37Z

Demsley:

{{Moodle 3.2}}

This is currently (2017) the recommended way to create various sorts of pop-up dialogue boxes in JavaScript.

= Why should you use it? =
The AMD modal modules provide a simple interface for creating a modal within Moodle. The module will ensure all accessibility requirements are met including applying the correct aria roles, focus control, aria hiding background elements and locking keyboard navigation.

The modals will fire events for common actions that occur within the modal, e.g. show / hide, for other code to listen to and react accordingly.

Moodle ships with a couple of standard modal types for you to re-use including a simple cancel modal, and a save/cancel modal. Hopefully with more to come!

= How do you create a basic modal? =
If you'd simply like to display a modal with some simple content then all you'll need is the modal factory. The factory provides a create function that accepts some configuration for your modal that the factory will use to create the modal and optionally a trigger element (the element that will open the modal when activated). The create function will return a promise that is resolved with the created modal.

The configuration is provided as an object with key/value pairs. The options are:
{| class="nicetable"
|-
! '''key'''
! '''description'''
|-
| title
| the title to display in the modal header - note: this will render HTML
|-
| body
| the main content to be rendered in the modal body
|-
| footer
| the content to be rendered in the modal footer
|-
| type
| one of the modal types registered with the factory
|-
| large
| a boolean to indicate if the modal should be wider than the default size
|}

Example 1
<code javascript>
define(['jquery', 'core/modal_factory'], function($, ModalFactory) {
var trigger = $('#create-modal');
ModalFactory.create({
title: 'test title',
body: '<p>test body content</p>',
footer: 'test footer content',
}, trigger)
.done(function(modal) {
// Do what you want with your new modal.
});
});
</code>
NB - When I tried this with Moodle 3.10 it did not work but changing the initial "define" to '''require''' worked as per [[https://docs.moodle.org/dev/Useful_core_Javascript_modules#Modal_.28core.2Fmodal.29]]

The modals will also accept a promise for the body and footer content. It is expected that the promise will be resolved with two strings, the html content and any associated javascript. This allows the modal module to work natively with the templates module, such as in the example below.

Example 2
<code javascript>
define(['jquery', 'core/modal_factory', 'core/templates'], function($, ModalFactory, Templates) {
var trigger = $('#create-modal');
ModalFactory.create({
title: 'test title',
// Can include JS which is run when modal is attached to DOM.
body: Templates.render('core/modal_test_3', {}),
footer: 'test footer content',
}, trigger)
.done(function(modal) {
// Do what you want with your modal.
});
});
</code>

Since the modals aren't actually added to the DOM until they are made visible any javascript resolved with the promise is cached and only run after all of the elements are added to the DOM, so you don't have to worry about any special handling in the javascript that is being loaded from the template.

= How to manually trigger a Modal =

If your trigger is (say) a class that covers a number of actual elements, you may want to grab the actual element that caused the event. Unfortunately, ModalEvents do not capture this and you need to approach the modal a different way. Here is an example - the scenario is a list of items with delete buttons. You need to know which delete button in order to get the item id. Note that code is somewhat simplified for clarity.

<code javascript>
$('a.item-delete').on('click', function(e) {
var clickedLink = $(e.currentTarget);
ModalFactory.create({
type: ModalFactory.types.SAVE_CANCEL,
title: 'Delete item',
body: 'Do you really want to delete?',
})
.then(function(modal) {
modal.setSaveButtonText('Delete');
var root = modal.getRoot();
root.on(ModalEvents.save, function() {
var elementid = clickedLink.data('id');
// Do something to delete item
});
modal.show();
});
</code>

'Normal' javascript is used to trap the event and the required element can be captured. No 'trigger' is passed to the ModalFactory so the resulting modal cannot display itself. The modal save event (in this case clicking the delete button) is handled as normally and will still trigger as expected. 'modal.show()' is called to display the modal.

= How do you create a different type of modal? =
Moodle comes with a few specialised types of modals for common use cases. Look at lib/amd/src/modal_factory.js to see what is available. These can be created using the factory, similar to the examples above, by specifying the type of modal in the configuration provided to the create function. Each of the modal types may have different configuration options, for example the save/cancel modal doesn't allow you to set the footer content.

Example 3
<code javascript>
define(['jquery', 'core/modal_factory', 'core/templates'], function($, ModalFactory, Templates) {
var trigger = $('#create-modal');
ModalFactory.create({
type: ModalFactory.types.SAVE_CANCEL,
title: 'Modal save cancel',
body: 'This modal is a save/cancel modal',
}, trigger)
.done(function(modal) {
// Do what you want with your modal.
});
});
</code>

Each type of modal may fire additional events to allow your code to handle the new functionality being offered. See the modal_events.js module for a list of events that can be fired. For example, if you wanted to have a save/cancel modal that you did some form validation on before saving you could do something like the example below.

Example 4
<code javascript>
define(['jquery', 'core/modal_factory', 'core/modal_events', 'core/templates'],
function($, ModalFactory, ModalEvents, Templates) {

var trigger = $('#create-modal');
ModalFactory.create({
type: ModalFactory.types.SAVE_CANCEL,
title: 'Modal save cancel',
body: 'This modal is a save/cancel modal',
}, trigger)
.done(function(modal) {
modal.getRoot().on(ModalEvents.save, function(e) {
// Stop the default save button behaviour which is to close the modal.
e.preventDefault();
// Do your form validation here.
});
});
});
</code>

= How do you write a new type of modal? =
If you'd like to write a new type of modal to be re-used throughout your code you can extend the default modal implementation and make any customisations you require. In order to create a new modal type you'll need to create a new AMD module and import the core/modal module to extend. You can also optionally create a new modal template that builds upon the core/modal template. Finally, you can register your new type with the modal registry to allow you to create your new type using the modal factory.

For example, let's create a modal that opens a login form:
First we can create the HTML for out modal by including and extending the core modal template. All we need to do is override the block defined in that template with our new title, body and footer content.

Let's assume the file is <your_module>/templates/modal_login.mustache

<code>
{{< core/modal }}
{{$title}}{{#str}} login {{/str}}{{/title}}
{{$body}}
<div class="container">
<form>
<div class="form-group row">
<label for="inputEmail" class="col-sm-2 col-form-label">{{#str}} email {{/str}}</label>
<div class="col-sm-10">
<input type="email" class="form-control" id="inputEmail" placeholder="{{#str}} email {{/str}}">
</div>
</div>
<div class="form-group row">
<label for="inputPassword" class="col-sm-2 col-form-label">{{#str}} password {{/str}}</label>
<div class="col-sm-10">
<input type="password" class="form-control" id="inputPassword" placeholder="{{#str}} password {{/str}}">
</div>
</div>
</form>
</div>
{{/body}}
{{$footer}}
<button type="button" class="btn btn-primary" data-action="login">{{#str}} login {{/str}}</button>
<button type="button" class="btn btn-secondary" data-action="cancel">{{#str}} cancel {{/str}}</button>
{{/footer}}
{{/ core/modal }}
</code>

Next we can create the new AMD module for the login modal. You can extend the existing modal module which will give you all of the core modal functionality for free allowing you to focus on writing only the specific logic you need. In this example we would only need to write the logic for handling the login.

Let's assume the file is <your_module>/amd/src/modal_login.js

<code javascript>
define(['jquery', 'core/notification', 'core/custom_interaction_events', 'core/modal', 'core/modal_registry'],
function($, Notification, CustomEvents, Modal, ModalRegistry) {

var registered = false;
var SELECTORS = {
LOGIN_BUTTON: '[data-action="login"]',
CANCEL_BUTTON: '[data-action="cancel"]',
};

/**
* Constructor for the Modal.
*
* @param {object} root The root jQuery element for the modal
*/
var ModalLogin = function(root) {
Modal.call(this, root);

if (!this.getFooter().find(SELECTORS.LOGIN_BUTTON).length) {
Notification.exception({message: 'No login button found'});
}

if (!this.getFooter().find(SELECTORS.CANCEL_BUTTON).length) {
Notification.exception({message: 'No cancel button found'});
}
};

ModalLogin.TYPE = 'your_module-login';
ModalLogin.prototype = Object.create(Modal.prototype);
ModalLogin.prototype.constructor = ModalLogin;

/**
* Set up all of the event handling for the modal.
*
* @method registerEventListeners
*/
ModalLogin.prototype.registerEventListeners = function() {
// Apply parent event listeners.
Modal.prototype.registerEventListeners.call(this);

this.getModal().on(CustomEvents.events.activate, SELECTORS.LOGIN_BUTTON, function(e, data) {
// Add your logic for when the login button is clicked. This could include the form validation,
// loading animations, error handling etc.
}.bind(this));

this.getModal().on(CustomEvents.events.activate, SELECTORS.CANCEL_BUTTON, function(e, data) {
// Add your logic for when the cancel button is clicked.
}.bind(this));
};

// Automatically register with the modal registry the first time this module is imported so that you can create modals
// of this type using the modal factory.
if (!registered) {
ModalRegistry.register(ModalLogin.TYPE, ModalLogin, '<your_module>/modal_login');
registered = true;
}

return ModalLogin;
});
</code>

Once you have both your template and javascript ready to go then all you need to do is tie them into where ever you'd like to launch the modal. For the purpose of this example let's assume that we've got a page with a login button with id="login" then you might add this javascript to the page.

<code javascript>
define(['jquery', 'core/templates', 'core/modal_factory', '<your_module>/modal_login'], function($, Templates, ModalFactory, ModalLogin) {
var trigger = $('#login');

ModalFactory.create({type: ModalLogin.TYPE}, trigger);
});
</code>

= Related =
* AMD and [[Javascript Modules]]

[[Category:Javascript]]

AMD Modal

2021-05-19T11:50:51Z

Demsley:

{{Moodle 3.2}}

This is currently (2017) the recommended way to create various sorts of pop-up dialogue boxes in JavaScript.

= Why should you use it? =
The AMD modal modules provide a simple interface for creating a modal within Moodle. The module will ensure all accessibility requirements are met including applying the correct aria roles, focus control, aria hiding background elements and locking keyboard navigation.

The modals will fire events for common actions that occur within the modal, e.g. show / hide, for other code to listen to and react accordingly.

Moodle ships with a couple of standard modal types for you to re-use including a simple cancel modal, and a save/cancel modal. Hopefully with more to come!

= How do you create a basic modal? =
If you'd simply like to display a modal with some simple content then all you'll need is the modal factory. The factory provides a create function that accepts some configuration for your modal that the factory will use to create the modal and optionally a trigger element (the element that will open the modal when activated). The create function will return a promise that is resolved with the created modal.

The configuration is provided as an object with key/value pairs. The options are:
{| class="nicetable"
|-
! '''key'''
! '''description'''
|-
| title
| the title to display in the modal header - note: this will render HTML
|-
| body
| the main content to be rendered in the modal body
|-
| footer
| the content to be rendered in the modal footer
|-
| type
| one of the modal types registered with the factory
|-
| large
| a boolean to indicate if the modal should be wider than the default size
|}

Example 1
<code javascript>
define(['jquery', 'core/modal_factory'], function($, ModalFactory) {
var trigger = $('#create-modal');
ModalFactory.create({
title: 'test title',
body: '<p>test body content</p>',
footer: 'test footer content',
}, trigger)
.done(function(modal) {
// Do what you want with your new modal.
});
});
</code>
NB - When I tried this with Moodle 3.10 it did not work but changing the initial "define" to '''require''' worked.

The modals will also accept a promise for the body and footer content. It is expected that the promise will be resolved with two strings, the html content and any associated javascript. This allows the modal module to work natively with the templates module, such as in the example below.

Example 2
<code javascript>
define(['jquery', 'core/modal_factory', 'core/templates'], function($, ModalFactory, Templates) {
var trigger = $('#create-modal');
ModalFactory.create({
title: 'test title',
// Can include JS which is run when modal is attached to DOM.
body: Templates.render('core/modal_test_3', {}),
footer: 'test footer content',
}, trigger)
.done(function(modal) {
// Do what you want with your modal.
});
});
</code>

Since the modals aren't actually added to the DOM until they are made visible any javascript resolved with the promise is cached and only run after all of the elements are added to the DOM, so you don't have to worry about any special handling in the javascript that is being loaded from the template.

= How to manually trigger a Modal =

If your trigger is (say) a class that covers a number of actual elements, you may want to grab the actual element that caused the event. Unfortunately, ModalEvents do not capture this and you need to approach the modal a different way. Here is an example - the scenario is a list of items with delete buttons. You need to know which delete button in order to get the item id. Note that code is somewhat simplified for clarity.

<code javascript>
$('a.item-delete').on('click', function(e) {
var clickedLink = $(e.currentTarget);
ModalFactory.create({
type: ModalFactory.types.SAVE_CANCEL,
title: 'Delete item',
body: 'Do you really want to delete?',
})
.then(function(modal) {
modal.setSaveButtonText('Delete');
var root = modal.getRoot();
root.on(ModalEvents.save, function() {
var elementid = clickedLink.data('id');
// Do something to delete item
});
modal.show();
});
</code>

'Normal' javascript is used to trap the event and the required element can be captured. No 'trigger' is passed to the ModalFactory so the resulting modal cannot display itself. The modal save event (in this case clicking the delete button) is handled as normally and will still trigger as expected. 'modal.show()' is called to display the modal.

= How do you create a different type of modal? =
Moodle comes with a few specialised types of modals for common use cases. Look at lib/amd/src/modal_factory.js to see what is available. These can be created using the factory, similar to the examples above, by specifying the type of modal in the configuration provided to the create function. Each of the modal types may have different configuration options, for example the save/cancel modal doesn't allow you to set the footer content.

Example 3
<code javascript>
define(['jquery', 'core/modal_factory', 'core/templates'], function($, ModalFactory, Templates) {
var trigger = $('#create-modal');
ModalFactory.create({
type: ModalFactory.types.SAVE_CANCEL,
title: 'Modal save cancel',
body: 'This modal is a save/cancel modal',
}, trigger)
.done(function(modal) {
// Do what you want with your modal.
});
});
</code>

Each type of modal may fire additional events to allow your code to handle the new functionality being offered. See the modal_events.js module for a list of events that can be fired. For example, if you wanted to have a save/cancel modal that you did some form validation on before saving you could do something like the example below.

Example 4
<code javascript>
define(['jquery', 'core/modal_factory', 'core/modal_events', 'core/templates'],
function($, ModalFactory, ModalEvents, Templates) {

var trigger = $('#create-modal');
ModalFactory.create({
type: ModalFactory.types.SAVE_CANCEL,
title: 'Modal save cancel',
body: 'This modal is a save/cancel modal',
}, trigger)
.done(function(modal) {
modal.getRoot().on(ModalEvents.save, function(e) {
// Stop the default save button behaviour which is to close the modal.
e.preventDefault();
// Do your form validation here.
});
});
});
</code>

= How do you write a new type of modal? =
If you'd like to write a new type of modal to be re-used throughout your code you can extend the default modal implementation and make any customisations you require. In order to create a new modal type you'll need to create a new AMD module and import the core/modal module to extend. You can also optionally create a new modal template that builds upon the core/modal template. Finally, you can register your new type with the modal registry to allow you to create your new type using the modal factory.

For example, let's create a modal that opens a login form:
First we can create the HTML for out modal by including and extending the core modal template. All we need to do is override the block defined in that template with our new title, body and footer content.

Let's assume the file is <your_module>/templates/modal_login.mustache

<code>
{{< core/modal }}
{{$title}}{{#str}} login {{/str}}{{/title}}
{{$body}}
<div class="container">
<form>
<div class="form-group row">
<label for="inputEmail" class="col-sm-2 col-form-label">{{#str}} email {{/str}}</label>
<div class="col-sm-10">
<input type="email" class="form-control" id="inputEmail" placeholder="{{#str}} email {{/str}}">
</div>
</div>
<div class="form-group row">
<label for="inputPassword" class="col-sm-2 col-form-label">{{#str}} password {{/str}}</label>
<div class="col-sm-10">
<input type="password" class="form-control" id="inputPassword" placeholder="{{#str}} password {{/str}}">
</div>
</div>
</form>
</div>
{{/body}}
{{$footer}}
<button type="button" class="btn btn-primary" data-action="login">{{#str}} login {{/str}}</button>
<button type="button" class="btn btn-secondary" data-action="cancel">{{#str}} cancel {{/str}}</button>
{{/footer}}
{{/ core/modal }}
</code>

Next we can create the new AMD module for the login modal. You can extend the existing modal module which will give you all of the core modal functionality for free allowing you to focus on writing only the specific logic you need. In this example we would only need to write the logic for handling the login.

Let's assume the file is <your_module>/amd/src/modal_login.js

<code javascript>
define(['jquery', 'core/notification', 'core/custom_interaction_events', 'core/modal', 'core/modal_registry'],
function($, Notification, CustomEvents, Modal, ModalRegistry) {

var registered = false;
var SELECTORS = {
LOGIN_BUTTON: '[data-action="login"]',
CANCEL_BUTTON: '[data-action="cancel"]',
};

/**
* Constructor for the Modal.
*
* @param {object} root The root jQuery element for the modal
*/
var ModalLogin = function(root) {
Modal.call(this, root);

if (!this.getFooter().find(SELECTORS.LOGIN_BUTTON).length) {
Notification.exception({message: 'No login button found'});
}

if (!this.getFooter().find(SELECTORS.CANCEL_BUTTON).length) {
Notification.exception({message: 'No cancel button found'});
}
};

ModalLogin.TYPE = 'your_module-login';
ModalLogin.prototype = Object.create(Modal.prototype);
ModalLogin.prototype.constructor = ModalLogin;

/**
* Set up all of the event handling for the modal.
*
* @method registerEventListeners
*/
ModalLogin.prototype.registerEventListeners = function() {
// Apply parent event listeners.
Modal.prototype.registerEventListeners.call(this);

this.getModal().on(CustomEvents.events.activate, SELECTORS.LOGIN_BUTTON, function(e, data) {
// Add your logic for when the login button is clicked. This could include the form validation,
// loading animations, error handling etc.
}.bind(this));

this.getModal().on(CustomEvents.events.activate, SELECTORS.CANCEL_BUTTON, function(e, data) {
// Add your logic for when the cancel button is clicked.
}.bind(this));
};

// Automatically register with the modal registry the first time this module is imported so that you can create modals
// of this type using the modal factory.
if (!registered) {
ModalRegistry.register(ModalLogin.TYPE, ModalLogin, '<your_module>/modal_login');
registered = true;
}

return ModalLogin;
});
</code>

Once you have both your template and javascript ready to go then all you need to do is tie them into where ever you'd like to launch the modal. For the purpose of this example let's assume that we've got a page with a login button with id="login" then you might add this javascript to the page.

<code javascript>
define(['jquery', 'core/templates', 'core/modal_factory', '<your_module>/modal_login'], function($, Templates, ModalFactory, ModalLogin) {
var trigger = $('#login');

ModalFactory.create({type: ModalLogin.TYPE}, trigger);
});
</code>

= Related =
* AMD and [[Javascript Modules]]

[[Category:Javascript]]

Javascript Modules

2020-06-23T10:50:20Z

Demsley: /* Install grunt */

{{Moodle 2.9}}

= Javascript Modules =

== What is a Javascript module and why do I care? ==

A Javascript module is nothing more than a collection of Javascript code that can be used (reliably) from other pieces of Javascript.

== Why should I package my code as a module? ==

By packaging your code as a module you break your code up into smaller reusable pieces. This is good because:

a) Each smaller piece is simpler to understand / debug

b) Each smaller piece is simpler to test

c) You can re-use common code instead of duplicating it

= How do I write a Javascript module in Moodle? =

Since version 2.9, Moodle supports Javascript modules written using the Asynchronous Module Definition ([https://github.com/amdjs/amdjs-api/wiki/AMD AMD]) API. This is a standard API for creating Javascript modules and you will find many useful third party libraries that are already using this format.

To edit or create an AMD module in Moodle you need to do a couple of things.

Since version 3.8, Moodle supports [https://github.com/lukehoban/es6features#readme ECMAScript 2015 features] (aka ES6) in a cross browser compatible way thanks to [https://babeljs.io/ Babel JS]. In order to achieve the compatibility with older browsers Babel will compile the newer ES6 features back into ES5 Javascript. Unfortunately this means that in order for your Javascript changes to show in the browser they must be compiled by running [[Grunt]], even with the cachejs config setting set to false (i.e. "Development mode").

== Install NVM and Node ==

The recommended way of installing NodeJS is via the [https://github.com/nvm-sh/nvm Node Version Manager], or NVM. NVM allows you to have several different versions of NodeJS installed at and in-use at any once on your computer. Supported versions of Moodle all use version {{NodeJSExactVersion}} of NodeJS.

https://github.com/nvm-sh/nvm#installing-and-updating

Confirm it is working:

$ nvm --version
0.35.3

After you have installed '''nvm''', you should install the correct version of NodeJS by running the following commands from your Moodle directory:

nvm install
nvm use

If your primary use of NodeJS is for Moodle then we recommend that you set NodeJS version {{NodeJSExactVersion}} as your default version. You can do this by running:

nvm alias default {{NodeJSExactVersion}}

== Install grunt ==

The AMD modules in Moodle must be processed by some build tools before they will be visible to your web browser. We use "[[grunt]]" as a build tool to wrap our different processes. Grunt is a build tool written in Javascript that runs in the "[http://nodejs.org/ nodejs]" environment.

Once this is done, you can run the the following commands from your Moodle directory:

npm install

'''This may mention vulnerabilities, that's fine and doesn't apply.'''

npm install -g grunt-cli

== Development mode (Moodle v2.9 to v3.7) ==

To avoid having to constantly run grunt, make sure you set the following in your config.php

<code php>
// Prevent JS caching
$CFG->cachejs = false;
</code>

Moodle will now run your module from the amd/src module. Don't forget to switch this off and run 'grunt' before deploying the new version!

In this mode - if you get a strange message in your javascript console like "No define call for core/first" it means you have a syntax error in the javascript you are developing.
Or, "No define call for theme_XXX/loader" as you are probably missing the 'src' folder with relevant JS files. which might happen when you turn debugging ON on a theme that was bought, without 'src' folder :-(

== Development mode (Moodle v3.8 and above) ==

All Javascript code is now compiled using Babel which means Moodle will only ever serve minified Javascript to the browser, even in development mode. However in development mode Moodle will also send the browser the corresponding source map files for each of the Javascript modules. The source map files will tell the browser how to map the minified source code back to the unminified original source code so that the original source files will be displayed in the sources section of the browser's development tools.

While in development mode each of the Javascript modules will appear in the browser's source tree as separate modules (no more giant first.js file!) and they will also be loaded with individual network requests (this is a compromise we had to make thanks to some browser bugs with source map files).

To enable development mode set the '''cachejs''' config value to '''false''' in the admin settings or directly in your config.php file:
<code php>
// Prevent JS caching
$CFG->cachejs = false;
</code>

Since all Javascript must now be compiled you must run [[Grunt]] in order for you changes to appear in the browser. However rather than running Grunt manually each time on either the whole project or each file you modified, it is recommended that you just run the '''grunt watch''' task at the root of your Moodle directory. The grunt watch task will listen for changes to the Javascript files in the Moodle directory and will automatically lint and compile only the file that is changed after each change is detected. This removes the need to manually run grunt after each change.

== Running grunt ==

You can run grunt in your plugin's 'amd' directory and it will only operate on your modules. If you're having problems or just want to check your work it is worth running for the 'lint' feature. This can find basic problems. This sub-directory support wont work on Windows unfortunately but there is an alternative: Run grunt from the top directory with the --root=path/to/dir to limit execution to a sub-directory.

See [[Grunt#Running_grunt]] for more details of specific grunt commands which can be used.

If you get the error message

/usr/bin/env: node: No such file or directory

Then see the thread https://github.com/nodejs/node-v0.x-archive/issues/3911

On Ubuntu 14.04 this fixed it for me:

sudo ln -fs /usr/bin/nodejs /usr/local/bin/node

Note: Once you have run grunt and built your code, you will then need to purge Moodle caches otherwise the changes made to your minified files may not be picked up by Moodle.

== ES6 Modules (Moodle v3.8 and above) ==

In addition to AMD module syntax Moodle now supports the [https://github.com/lukehoban/es6features#modules ES6 syntax] for writing Javascript modules. All modules (defined using either syntax) are compatible with one another. Behind the scenes the ES6 module syntax is converted into an AMD syntax as part of the Babel compiling process.

=== Export default ===
There is one slight difference between the ES6 definition for exporting modules and the RequireJS (AMD) definition.

ES6 allows you to export a “default” value which is actually no different to exporting a named value where the name is “default”. Unfortunately, RequireJS allows for unnamed default exports (e.g. you can do "return SomeClass;") which can be imported by just requiring them in other AMD modules.

That’s a bit confusing, get to the point! Well, it basically means that in Moodle you won’t be able to write an ES6 module that exports both a default and named exports, e.g. "export default function() {...}" and "export const FOO = 'bar'" in the same module. The export default will simply override all other exports in that module.

=== Inline Javascript ===
Another important note is that ES6 support is only for stand alone Javascript files because it relies on the compilation from Babel and Grunt. That means any inline Javascript (either in PHP or in Mustache templates) won't support the ES6 features. Instead it would be best to keep the inline Javascript as minimal as possible and only use it to load a stand alone Javascript module.

== Minimum (getting started) module for plugins ==

This shows the absolute minimum module you need to get started adding modules to your plugins. It's actually quite simple...

<code javascript>
// Put this file in path/to/plugin/amd/src
// You can call it anything you like

define(['jquery'], function($) {

return {
init: function() {

// Put whatever you like here. $ is available
// to you as normal.
$(".someclass").change(function() {
alert("It changed!!");
});
}
};
});
</code>

This code passes the jquery module into our function (parameter $). There are a number of other useful modules available in Moodle, some of which you'll probably need in a practical application. See [[Useful_core_Javascript_modules]]. Simply list them in both the define() first parameter and the function callback. E.g.,
<code javascript>
define(['jquery', 'core/str', 'core/ajax'], function($, str, ajax) {
</code>

The idea here is that we will run the 'init' function from our (PHP) code to set things up. This is called from PHP like this...

<code php>
$PAGE->requires->js_call_amd('frankenstyle_path/your_js_filename', 'init');
</code>

Don't forget to supply the complete '[[Frankenstyle]]' path. The .js is not needed.

js_call_amd takes a third parameter which is an ''array'' of parameters. These will translate to individual parameters in the 'init' function call. For example...

<code php>
$PAGE->requires->js_call_amd('block_iomad_company_admin/department_select', 'init', array($first, $last));
</code>

...calls

<code javascript>
return {
init: function(first, last) {
}
</code>

A more comprehensive explanation follows...

== "Hello World" I am a Javascript Module ==
Lets now create a simple Javascript module so we can see how to lay things out.

Each Javascript module is contained in a single source file in the <componentdir>/amd/src folder. The final name of the module is taken from the file name and the component name. E.g. block_overview/amd/src/helloworld.js would be a module named "block_overview/helloworld". the name of the module is important when you want to call it from somewhere else in the code.

After running grunt - the minified Javascript files are stored in the <componentdir>/amd/build folder. The javascript files are renamed to show that they are minified (helloworld.js becomes helloworld.min.js).

Don't forget to add the built files (the ones in amd/build) to your git commits, or in production no-one will see your changes.

Lets create a simple module now:

blocks/overview/amd/src/helloworld.js
<code javascript>
// Standard license block omitted.
/*
* @package block_overview
* @copyright 2015 Someone cool
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

/**
* @module block_overview/helloworld
*/
define(['jquery'], function($) {

/**
* Give me blue.
* @access private
* @return {string}
*/
var makeItBlue = function() {
// We can use our jquery dependency here.
return $('.blue').show();
};

/**
* @constructor
* @alias module:block_overview/helloworld
*/
var greeting = function() {
/** @access private */
var privateThoughts = 'I like the colour blue';

/** @access public */
this.publicThoughts = 'I like the colour orange';

};

/**
* A formal greeting.
* @access public
* @return {string}
*/
greeting.prototype.formal = function() {
return 'How do you do?';
};

/**
* An informal greeting.
* @access public
* @return {string}
*/
greeting.prototype.informal = function() {
return 'Wassup!';
};
return greeting;
});
</code>

The most interesting line above is:
<code>
define(['jquery'], function($) {
</code>

All AMD modules must call "define()" as the first and only global scoped piece of code. This ensures the javascript code contains no global variables and will not conflict with any other loaded module. The name of the module does not need to be specified because it is determined from the filename and component (but it can be listed in a comment for JSDoc as shown here).

The first argument to "define" is the list of dependencies for the module. This argument must be passed as an array, even if there is only one. In this example "jquery" is a dependency. "jquery" is shipped as a core module is available to all AMD modules.

The second argument to "define" is the function that defines the module. This function will receive as arguments, each of the requested dependencies in the same order they were requested. In this example we receive JQuery as an argument and we name the variable "$" (it's a JQuery thing). We can then access JQuery normally through the $ variable which is in scope for any code in our module.

The rest of the code in this example is a standard way to define a Javascript module with public/private variables and methods. There are many ways to do this, this is only one.

It is important that we are returning 'greeting'. If there is no return then your module will be declared as undefined.

== Loading modules dynamically ==
What do you do if you don't know in advance which modules will be required? Stuffing all possible required modules in the define call is one solution, but it's ugly and it only works for code that is in an AMD module (what about inline code in the page?). AMD lets you load a dependency any time you like.
<code javascript>

// Load a new dependency.
require(['mod_wiki/timer'], function(timer) {
// timer is available to do my bidding.
});
</code>

== Including an external javascript/jquery library ==
If you want to include a javascript / jquery library downloaded from the internet you can do so as follows:

'''Warning: if the library you download, supports AMD but is already "named" you will not be able to include it directly'''
e.g.
<code javascript>
define("typeahead.js", *[ "jquery" ], function(a0) {
return factory(a0);
});
</code>
will not work, as moodle injects it's own define name when loading the library.

If the library is in AMD format and has a define:
e.g. i want to include the jquery final countdown timer on my page ( hilios.github.io/jQuery.countdown/ )
* download the module in both normal and minified versions
* place the modules in your moodle install e.g. your custom theme dir, or plugin dir
* /theme/mytheme/amd/src/jquery.countdown.js

you can now include the module and initialise it (there are multiple ways to do this)
php:

1. Create your own AMD module and initialise it:

In your PHP file:
<code php>
$this->page->requires->js_call_amd('theme_mytheme/countdowntimer', 'initialise', $params);
</code>

Javascript module:
<code javascript>
// /theme/mytheme/amd/src/countdowntimer.js
define(['jquery', 'theme_mytheme/jquery.countdown'], function($, c) {
return {
initialise: function ($params) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
}
};
});
</code>

2. Put the javascript into a mustache template:
<code javascript>
// /theme/mytheme/templates/countdowntimer.mustache
<span id="clock"></span>
{{#js}}
require(['jquery', 'theme_mytheme/jquery.countdown'], function($) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
});
{{/js}}
</code>

3. Call the javascript directly from php (although who would want to put javascript into php? ergh):
<code php>
$PAGE->requires->js_amd_inline('
require(['theme_mytheme/jquery.countdown'], function(min) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
});
');
</code>
<br>
Note: It could be useful when you wish to pass a big chunk of data from php directly into a JS variable, to workaround MDL-62468 .<br>
Example: https://github.com/moodle/moodle/blob/master/media/player/videojs/classes/plugin.php#L386

===More examples of including 3rd-party JS modules===
* [https://moodle.org/mod/forum/discuss.php?d=327579#p1317252 Adding custom js via AMD (highcharts) to essential theme]

== Embedding AMD code in a page ==
So you have created lots of cool Javascript modules. Great. How do we actually call them? Any javascript code that calls an AMD module must execute AFTER the requirejs module loader has finished loading. We have provided a function "js_call_amd" that will call a single function from an AMD module with parameters.

<code php>
$PAGE->requires->js_call_amd($modulename, $functionname, $params);
</code>

that will "do the right thing" with your block of AMD code and execute it at the end of the page, after our AMD module loader has loaded.
Notes:
* the $modulename is the 'componentname/modulename' discussed above
* the $functionname is the name of a public function exposed by the amd module.
* the $params is an array of params passed as arguments to the function. These should be simple types that can be handled by json_encode (no recursive arrays, or complex classes please).
* if the size of the params array is too large (> 1Kb), this will produce a developer warning. Do not attempt to pass large amounts of data through this function, it will pollute the page size. A preferred approach is to pass css selectors for DOM elements that contain data-attributes for any required data, or fetch data via ajax in the background.

AMD / JS code can also be embedded on a page via mustache templates
see here: https://docs.moodle.org/dev/Templates#What_if_a_template_contains_javascript.3F

== Troubleshooting ==

=== npm-shrinkwrap.json sha1 / sha512 changes ===

If grunt changes all the hashes in npm-shrinkwrap.json then try this:

rm -rf node_modules && npm i

== But I have a mega JS file I don't want loaded on every page? ==
Loading all JS files at once and stuffing them in the browser cache is the right choice for MOST js files, there are probably some exceptions. For these files, you can rename the javascript file to end with the suffix "-lazy.js" which indicates that the module will not be loaded by default, it will be requested the first time it is used. There is no difference in usage for lazy loaded modules, the require() call looks exactly the same, it's just that the module name will also have the "-lazy" suffix.

== Useful links ==
* [https://assets.moodlemoot.org/sites/15/20171004085436/JavaScript-AMD-with-RequireJS-presented-by-Daniel-Roperto-Catalyst.pdf JavaScript AMD with RequireJS] presented by Daniel Roperto, Catalyst. (MoodleMOOT AU 2017)
* [[Useful_core_Javascript_modules]]
*[[Guide_to_adding_third_party_jQuery_for_AMD]] by Patrick Thibaudeau
*[https://moodle.org/mod/forum/discuss.php?d=378112#p1524459 How to get variables from PHP into javascript AMD modules in M3.5] Justin Hunt, on Moodle forums.
*MDL-67327 JavaScript issues when not following the official documentation, since Moodle 3.8

[[Category:AJAX]]
[[Category:Javascript]]

Setting up your development environment for the Moodle App

2020-06-10T11:03:09Z

Demsley: /* Open the app in the browser */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

Note: These instructions do work (give or take) for the current 3.5.x version of the Moodle Mobile app.

== Overview ==

The structure of this page is
* the first part, up to the point where you get the 'ionic serve' command to work is what you need to be able to do development on the app and test it in a browser.
* the second part is about how to build a version of the app that can be run on a device.
* then at the end is a list of troubleshooting advice. If you encouter a problem that is not already listed, please consider adding it.

The majority of your development will be done using a browser. You will probably on begin to use an emulator once you need to simulate a real mobile device.

If you are just [[Mobile support for plugins|adding mobile support to plugins]], remember that most of your development can be done using the online pre-built version at https://mobileapp.moodledemo.net/ (with Chrome or Chromium). However, if you want to be able to to write [[Acceptance_testing_for_the_mobile_app|automated acceptance tests for the app]] then you need to follow this page at least as far as getting the ionic serve command to work on this page.

== Requirements ==

Windows tip: ingore any use of the sudo command below. Just use the command without it. Most things work that way, and if they don't try in a Powershell window that you have opened with 'Run as administrator ...'.

===Install a browser for development===

We recommend Chromium browser (Google Chrome open source version) https://download-chromium.appspot.com/
Please, read [[Moodle_Mobile_development_using_Chrome_or_Chromium]] for more information

===Install git===

https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

===Install Node.js===

On Linux we recommend you use [https://github.com/creationix/nvm nvm] - this lets you switch Node versions, and makes the install a bit easier than the official installation route.

nvm install node
nvm use 11.12.0 # Or whatever number nvm install reported.

(Exact version is probably not critical. Moodle HQ devs report using both 8.12.x and 11.12.0 as of 2019-03-25.)

On Windows we recommend you use https://github.com/coreybutler/nvm-windows. Same nvm commands as for Linux.

On Mac users we recommend to install NodeJS via Macports.

(It may seem simpler and easier to install directly from http://nodejs.org, but actually it seems to me more tricky to get that to work. If you have previously installed Node directly, and want to switch to nvm, you need to un-install node completely before installing nvm - or Google for trouble-shooting instructions, for example https://github.com/coreybutler/nvm-windows/issues/58#issuecomment-272608696.)

===Install ionic===
npm cache clean
npm install -g cordova@8.1.2 ionic # (If it throws an EACCESS error, run it again with sudo)

===Install the npm required packages===
sudo npm install -g gulp # (This will install gulp in a folder that should be in the PATH)

===Windows only: Native build dependencies===

node-gyp requires native build tools for your platform. If you're developing on Mac or Linux, you'll probably have these already ([https://github.com/nodejs/node-gyp/blob/master/README.md refer to the docs if not]), on Windows, run the following command as administrator (in cmd or Powershell):

npm install --global --production windows-build-tools

Warning! this installer can take a very, very long time to run. We were seeing it take hours. Literally. Be prepared to be very patient. Don't just make the natural assumption that it has crashed.

===Mac only: Push notifications===

Phonegap plugin push 1.9.0 requires CocoaPods to work on a Mac. The installation steps can be found in https://cocoapods.org/

sudo gem install cocoapods
pod setup

Please note that for compiling the app in Mac you need to open the '''Moodle.xcworkspace''' file, more information here: MOBILE-1970

== Clone the app base code ==

Clone the code base into a local directory in your computer.
It may be an idea to work from the integration branch rather than master.
git clone https://github.com/moodlehq/moodleapp.git moodlemobiledirectory
cd moodlemobiledirectory
git checkout integration

== Setup the environment ==

Please, note that if you are creating a custom app with a custom URL scheme, you should edit the /package.json and /config.xml files and specify there your custom URL_SCHEME (replacing the existing value) and your [https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/INSTALLATION.md GCMPN SENDER_ID].

The following command must be run in the project's root folder:
npm run setup

If this fails, you can see what it is doing by looking at the 'scripts' section in package.json. At the moment it is doing <tt>npm install && cordova prepare && gulp</tt>. That is, running three commands back-to-back, but only carrying on if the previous one succeeds completely. You can try running the three commands separately. If you do, <tt>ionic serve</tt> (see below) may work, even if <tt>cordova prepare</tt> gives errors. You only really need <tt>cordova prepare</tt> to work if you are going to go on and build the app.

== Open the app in the browser ==
First start Chromium via the command line using the custom parameters as is mentioned here: [[Moodle Mobile development using Chrome or Chromium]]

and then, start the Ionic server:

ionic serve --browser chromium # or chrome or whatever browser.

If you don't want to open any browser you should run:

ionic serve -b

Congratulations! Now that you have got to the point where the 'ionic serve' command works, you can start doing development on the app. You only need to read the rest of the page if you want to build packaged versions of the app.

== Updating ionic and cordova ==

sudo npm update -g cordova
sudo npm update -g ionic

Update project platforms:

ionic cordova platform remove android
ionic cordova platform remove ios
ionic cordova platform add android
ionic cordova platform add ios

== Updating plugins ==

cordova plugin remove your_plugin_id
cordova plugin add your_plugin_id

== Building for Android and iOS ==

Please see the guides below to be able to build for Android and iOS using the command line:

Android: https://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html

iOS: https://cordova.apache.org/docs/en/latest/guide/platforms/ios/index.html

If the build fails, please run <code>cordova requirements</code> to check that you fulfilled all requirements for the platform.

If you get errors while building, please see the Troubleshooting section below.

If using '''Ubuntu''' you should install the packages: gradle and libgradle-android-plugin-java (and all its dependencies) to build.

== Compiling using AOT ==

Angular has 2 ways of compiling: JIT and AOT. Running "ionic serve" or "ionic build" compiles using JIT by default, which is faster to compile but the app takes longer to start.

When building for release you should always compile using AOT, otherwise the app can take too long to start in some devices. The default AOT compiling causes some issues with the database activity and the [[Mobile support for plugins]], so you have to modify a couple of files in order to make this work.

First you need to open the file: ''node_modules/@angular/platform-browser-dynamic/esm5/platform-browser-dynamic.js''. Search the variable called "''_NO_RESOURCE_LOADER''", you'll see it has a function named "''get''" with this line:

<code javascript>
throw new Error("No ResourceLoader implementation has been provided. Can't read the url \"" + url + "\"");</code>

Remove that line and put this code instead:

<code javascript>
url = 'templates/' + url;

var resolve;
var reject;
var promise = new Promise(function (res, rej) {
resolve = res;
reject = rej;
});
var xhr = new XMLHttpRequest();
xhr.open('GET', url, true);
xhr.responseType = 'text';
xhr.onload = function () {
// responseText is the old-school way of retrieving response (supported by IE8 & 9)
// response/responseType properties were introduced in ResourceLoader Level2 spec (supported by IE10)
var response = xhr.response || xhr.responseText;
// normalize IE9 bug (http://bugs.jquery.com/ticket/1450)
var status = xhr.status === 1223 ? 204 : xhr.status;
// fix status code when it is 0 (0 status is undocumented).
// Occurs when accessing file resources or on Android 4.1 stock browser
// while retrieving files from application cache.
if (status === 0) {
status = response ? 200 : 0;
}
if (200 <= status && status <= 300) {
resolve(response);
}
else {
reject("Failed to load " + url);
}
};
xhr.onerror = function () { reject("Failed to load " + url); };
xhr.send();
return promise;
</code>

We tried to replace the default loader with our own implementation, but we weren't able to make the compiler work so the only solution left was to modify the default one.

Now you need to open the file: ''node_modules/@ionic/app-scripts/dist/util/config.js''. In that file you need to remove the ''context.isProd'' condition from the options ''optimizeJs''. So the final code for that part should be like this:

<code javascript>
context.optimizeJs = [
context.optimizeJs,
hasArg('--optimizeJs')
].find(function (val) { return typeof val === 'boolean'; });
</code>

We want to compile in production mode but without optimizing Javascript because that breaks our plugins support. However, Ionic doesn't let you do that, so the only option is to do this change.

With these changes done you can now compile using production mode:

<code php>
npm run ionic:build -- --prod</code>

This command will generate the app files and put them inside ''www'' folder. If you now want to install that app in a real device you can run "''cordova run android''" or "''cordova build ios''" (please don't use "''ionic cordova ...''" or "''ionic serve''" because it will override your build files!).

== Troubleshooting ==

=== Strange NPM errors ===

To get more debug output from npm commands, see https://docs.npmjs.com/misc/config#shorthands-and-other-cli-niceties. In particular try adding <tt>--loglevel verbose</tt> (or <tt>--loglevel info</tt> or <tt>--loglevel silly</tt>) to the command-line.

=== Error: libsass bindings not found. Try reinstalling node-sass? ===

Please read: http://fettblog.eu/gulp-and-node4-first-aid/, alternatively you must be sure that you installed Node v0.12

=== node-gyp\src\win_delay_load_hook.c(34): error C2373: '__pfnDliNotifyHook2': redefinition; different type modifiers ===

Try updating npm to the latest version using:

npm install -g npm@latest

=== com.android.dex.DexException: Multiple dex files define XXX ===
Open the file ''platforms/android/build.gradle'' and add this code at the end:

configurations {
all*.exclude group: 'com.android.support', module: 'support-v4'
}

=== Could not resolve all dependencies for configuration ':_debugCompile'. ===
Open the Android SDK Manager and make sure you have installed: Android Support Repository, Android Support Library, Google Play Services and Google Repository.

=== Could not find com.android.support:support-v4:XXX ===
Open the file ''platforms/android/build.gradle'' and add this code at the end:

configurations.all {
resolutionStrategy.force 'com.android.support:support-v4:24.0.0'
}

=== ERROR: In <declare-styleable> FontFamilyFont, unable to find attribute android:font ===

Open the file ''platforms/android/build.gradle'' and add this code at the end:

android {
compileSdkVersion 26
buildToolsVersion "26.0.1"
}

=== Error: Could not find gradle wrapper within Android SDK. Might need to update your Android SDK. ===

1. Download Android studio - https://developer.android.com/studio/

2. Copy the folder android-studio/plugins/android/lib/templates

3. Paste in the folder android-sdk-folder/Sdk/tools

=== Could not find com.android.support:support-v4:27.1.0 ===

Open the file ''platforms/android/build.gradle'' and configure like this:

allprojects {
repositories {
jcenter()
maven {
url "https://maven.google.com"
}
}
}

=== Error: not found: make ===

If you see this error in Ubuntu, run <tt>sudo apt-get install build-essential</tt> and retry.

=== Current working directory is not a Cordova-based project. ===

If you see this error during <tt>npm setup</tt>, run <tt>mkdir www</tt> and retry.

=== ReferenceError: internalBinding is not defined ===

This [https://stackoverflow.com/questions/53146394/node-app-fails-to-run-on-mojave-referenceerror-internalbinding-is-not-defined seems to be] an error with 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

=== ReferenceError: internalBinding is not defined ===

This [https://stackoverflow.com/questions/53146394/node-app-fails-to-run-on-mojave-referenceerror-internalbinding-is-not-defined seems to be] an error with 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

=== npm update check failed===

I got the error

│ npm update check failed │
│ Try running with sudo or get access │
│ to the local update config store via │
│ sudo chown -R $USER:$(id -gn $USER) C:\Users\username\.config │

on Windows because I installed too much as admin, and the suggested command does not work on Windows. The is to manually check the ownership of all the files in C:\Users\username\.config\configstore. In my case it was update-notifier-npm.json which got changed to be owned by Administrator.

===Unhandled rejection Error: Command failed: C:\cygwin64\bin\git.EXE ...===

You need to heed the advice at https://www.npmjs.com/package/npm#installing-on-cygwin. Cygwin users are not welcome in the Node world. However, you just need to ensure that Msysgit is on your windows path and that the cygwin bin folder is not. Then always use another shell like Powershell for your Moodle mobile development. (You don't need your Cygwin bin folder on the Windows path. It automatically gets added to the path when you lauch Cygwin bash.)

===The product name change (<name> tag) in config.xml is not supported dynamically===

According to Google, this happens when you create the iOS platform with a certain <name> and then you change that name in config.xml. It's weird that the installation process does that, it should create the platform with the right name unless it was changed manually.

The solution seems to be removing and adding the iOS platform again:

ionic platform remove ios
ionic platform add ios

Note that this does not seem to prevent <tt>ionic --serve</tt> from serving a working app if you run gulp after <tt>npm run setup</tt> has failed with this error.

===Failed to install 'cordova-plugin-file-transfer': CordovaError: Version of installed plugin: "cordova-plugin-file@4.3.3" does not satisfy dependency plugin requirement "cordova-plugin-file@>=5.0.0".===

The ''cordova-plugin-file'' version specified in config.xml is 6.0.1, for some reason the installation process installed a wrong version for that plugin. You can manually install the ''cordova-plugin-file'' plugin like this:

cordova plugin remove cordova-plugin-file
cordova plugin add cordova-plugin-file@6.0.1

Please notice that if there is any plugin installed that depends on ''cordova-plugin-file'' you'll have to remove and re-add them too.

Note that this does not seem to prevent <tt>ionic --serve</tt> from serving a working app if you run gulp after <tt>npm run setup</tt> has failed with this error.

===Cannot download "https://github.com/sass/node-sass/releases/download/v4.11.0/linux-x64-72_binding.node"===
Force using node 11, since node-sass for node 12 is not yet avalaible. See [https://tracker.moodle.org/browse/MOBILE-2999|MOBILE-2999] for more info.

===Mac: linker code failed with exit code 1===
If you get this error when trying to build the Moodle app with XCode, some dependencies might not have installed correctly.

Ensure you have followed the [https://docs.moodle.org/dev/Setting_up_your_development_environment_for_Moodle_Mobile_2#Mac_only:_Push_notifications| Mac only: Push notifications] steps above (particularly opening the .xcworkspace file rather than the .xcodeproj file). Then run the following:

npm run setup
cd platforms/ios
pod install

Now try running the build again in XCode.

===Windows: <code>npm run ionic:serve</code> hangs after "Starting 'watch'"===
This appears to have happened since the move to npx. Try running the npx commands generated by npm run directly in bash:
npx gulp watch & npx ionic-app-scripts serve -b --devapp --address=0.0.0.0

== See also ==

http://ionicframework.com/docs/cli/

SCSS

2020-05-21T13:52:47Z

Demsley: /* Using in a theme */

{{Moodle 3.2}}
== Overview ==

[https://en.wikipedia.org/wiki/Sass_(stylesheet_language) SCSS] or SASS Sass (Syntactically Awesome Stylesheets) is a style sheet language initially designed by Hampton Catlin and developed by Natalie Weizenbaum. It's an advanced way of writing CSS that we use in some themes within Moodle.

Browsers don't interpret it themselves, however, so SCSS files need to be converted into normal CSS before use.

==Using in a theme==

Moodle includes a built in SCSS compiler so to use SCSS in your theme, you only need to set the theme scss variable, in your theme's config.php file, to point to the main scss file for your theme:
<code php>
// Points to the file theme/themename/scss/main.scss.
$THEME->scss = 'main';
</code>

Moodle will look for a file named 'main.scss' in the 'theme/themename/scss' folder and compile it. If you don't see the affect of your changes right away, try purging the caches or enabling theme designer mode.

===Inheriting from a parent===

Even if your theme is inheriting from a parent, the SCSS file itself will not inherit from anything, this is something you should do manually. For instance, if you want your SCSS file to include all of the SCSS code provided by ''theme_boost'', usually to change the variables, you need to manually import the file like this:

<code>
// In your theme's SCSS file
@import "../../boost/scss/moodle";
</code>

The path needs to be relative and not absolute. You would use it like this:

<code>
$brand-primary: #00acdf !default;
$my-color: #ff9900 !default;

@import "../../boost/scss/moodle";

body {
background-color: $my-color;
}
</code>

NOTICE: At the moment, Moodle is using a PHP sass compiler which does not support '@import url' at-rule MDL-57875, which is a challenge when you wish to use bootswatch presets or Google fonts directly. so it is advise to use the OS level sass binary compiler (by installing libsass via 'yum install libsass', or other means) and then setting the admin $CFG->pathtosassc to use the 'sassc' binary.

=== Advance usage ===

==== On-the-fly injections ====

The following settings allow themers to point to a function which will either prepend, or append, SCSS code to content gotten from ''$THEME->scss''.

<code php>
// The content returned by this function is added before the main SCSS.
$THEME->prescsscallback = 'theme_themename_scss_to_prepend';

// The content returned by this function is added after the main SCSS.
$THEME->extrascsscallback = 'theme_themename_scss_to_append';
</code>

The functions will receive the ''theme config'' as first argument.

==== Dynamic $THEME->scss ====

Rather than giving the name of your SCSS file in ''$THEME->scss'', you can make it a function which returns the SCSS content.

<code php>
$THEME->scss = function($themeconfig) {
$scsscontent = '$my-var: red;';
$scsscontent .= body { color: $my-var; }';
return $scsscontent;
}
</code>

== Example ==

Moodle's Boost theme has rules written using SCSS.

== See also ==

* Using 'sassc' binary sass compiler as an alternative to Moodle PHP sass compiler. MDL-61394 ($CFG->pathtosassc)
* [http://sass-lang.com/ Sass official website]

[[Category:Themes]]

Using the Moodle App in a browser

2019-08-22T09:32:09Z

Demsley: /* Differences between Chromium and Google Chrome */

Chromium or Google Chrome browser are the recommended tools for Moodle Mobile development. But remember that if you are going to use functions provided by Phonegap you should use the Android SDK or iOs developer tools.
{{Moodle Mobile}}
{{Work in progress}}

== Differences between Chromium and Google Chrome ==

Google Chrome is the Chromium open source project built, packaged, and distributed by Google. We can say that Chromium is Google Chrome without the "Google" add-ons

See https://code.google.com/p/chromium/wiki/ChromiumBrowserVsGoogleChrome for more information

We recommend using Chromium instead Google Chrome

== Advantages and disadvantages of using Chromium/Google Chrome ==

Main advantages
* Quick development
* DOM inspector
* Network monitor
* Database (local storage) inspector
* Emulation options

Disadvantages
* You can't test/develop using Phonegap APIs and Plugins
* If you use custom Phonegap code (including plugins) you will need to edit the mm.cordova.js for "emulate" those APIs in a browser
* You will always need to test in a real device and emulator prior to a production release
* You will need to verify that your CSS/layout works the same in an Android/iOs device

== Installation ==

Install the “Chromium” browser just downloading it from https://download-chromium.appspot.com/

In order to be able to access any domain via AJAX from the local file:/// protocol, you must run Chromium or Google Chrome in Unsafe mode adding this param:

--allow-file-access-from-files --disable-web-security --user-data-dir --allow-running-insecure-content

NOTE: Since Moodle 3.0 an onwards this shouldn't be necessary since the Web Service layer supports CORS requests.

IMPORTANT: I strongly recommend you create a new link or application launch called "Chrome Unsafe" and use it only for testing the app. Better if you only use this browser for development

How to open the browser:

"Path to chrome\chrome.exe" --allow-file-access-from-files --disable-web-security --user-data-dir --allow-running-insecure-content

or in Mac (you can use Automator for creating an app bundle)

open -a "Google Chrome" --args --allow-file-access-from-files --disable-web-security --user-data-dir --allow-running-insecure-content

or for Chromium

open -a /Applications/Chromium.app --args --allow-file-access-from-files --disable-web-security --user-data-dir --allow-running-insecure-content

In Mac you can use Automator for creating a launching app

Now, you can open the application running:
ionic serve --browser chromium
it should open a new tab in the current Chromium instance with the app, (remember that you have to open first the Chromium so it's started with all the additional arguments).

If the ionic serve command open a new browser window, you should copy the URL and then paste it in the Chromium instance you opened using the command shell.

== Sites for testing ==

You can test the application using existing sites configured to have the Mobile services enabled.

Real test site: If you type "student" or "teacher" in the "Site URL" field and then tap on "Add site" the app will connect to http://school.demo.moodle.net. This site is reset every hour so you may find unexpected behaviors

== Browser Settings ==
[[{{ns:file}}:moodlemobile_developer.png|thumb|300px]]
You should develop always with the "Developer tools" panel open, you can open that panel with F12 (cmd + alt + i in Mac) or "Developer tools" in the Tools menu.

[[{{ns:file}}:moodlemobile_options.png|left]] Once opened, click on the wheel top-right corner to see the General options, you must Disable the cache there (this setting will work only if you have the Developer tools panel open)

You can dock or undock into a separate window the developer panel using the "Dock" option just at the right of the settings wheel, you can move the developer panel to your right and resize the main browser window to emulate a Mobile device

== Inspecting and changing the DOM ==

Using the "Elements" option you can manipulate the DOM:

* Add/modify style to elements
* Delete elements
* Move elements
* Inject HTML code

You have complete information here: https://developer.chrome.com/devtools/index

And also a free interactive course here: https://www.codeschool.com/courses/discover-devtools

== Monitor XHR (ajax) requests ==
[[{{ns:file}}:moodlemobile_network.png|thumb|300px]]

With the network panel you can check and filter all the HTTP request send from the app to your Moodle server.

You can preserve the log in the navigation, filter by type of requests and also see complete information of all the requests made to the server where is hosted your Moodle installation.

You can also identify with resources takes long to load

== Console, log and errors ==
[[{{ns:file}}:moodlemobile_log.png|thumb|300px]]

The console panel is used for displaying the app log and errors, you can also configure Chrome for displaying there XHR requests

In order to view the app log, you need first to enable Logging in the app (Options / Developers / Enable logging)

You can use the console also for executing javascript commands, the console has access to the complete MM global object so you can call from there to core APIs functions of the app

== Browsing the data base ==
[[{{ns:file}}:moodlemobile_localstorage.png|thumb|300px]]

The Mobile app stores information in the local HTML5 IndexedDB

You can inspect the local database in the Resources tab.

== File system ==
[[{{ns:file}}:moodlemobile_filesystem.png|thumb|300px]]

The first time you open the browser with the special flags you will see a couple of warnings, one asking you to accept to store information.

You have to "Accept" that warning because it means that you will be able to emulate the device file system using the browser.

For example, you will be able to download files to the browser storage (like the user profiles images, any resource in the course, etc..)

You can browse the files stored in the application going to Settings > About and clicking the Filesystem root link.

== Emulating devices ==
[[{{ns:file}}:moodlemobile_emulation.png|thumb|300px]]

You can emulate mobile devices changing orientation, resolution, geo-location, touch events... It's not recommended to use de "Emulation Device" option because it just changes the user-agent and you could get some fails because of the jQuery Swipe library.

The best option to test with the browser is just rescaling the window to get a new viewport size or use the screen settings in the "Emulation" screen.

== See also ==

[https://developer.chrome.com/devtools/index Chrome Developer Tools help]

[[Category: Mobile]]

Moodle App Customisation

2019-08-22T09:31:14Z

Demsley: /* Configuring how the app should work via Moodle site settings */

{{Moodle Mobile}}

== Overview ==

Moodle Mobile can be customized in different ways:
* Changing the app appearance for your site.
* Adding support in your plugin for the mobile app.
* Configuring how the app should work via Moodle site settings.
* Creating a custom application (with your custom name and icon) based on the Moodle Mobile code.

With the first three options you are not required to compile or build your custom application, with the last one you are required to compile and publish your custom app in the stores.

== Changing the app appearance for your site ==

The Mobile app can retrieve your custom styles from your Moodle site. Since is an HTML5 app, you can apply safely CSS3 styles.

In your Moodle installation go to Plugins / Web services / Mobile and enter in the mobilecssurl field a valid URL pointing to a CSS file containing your custom styles (theme).

The CSS should be placed inside your Moodle installation (in your custom theme or inside a local plugin)

Once the user is logged in the app, there is a periodical process that retrieves your remote CSS files for applying your custom styles into the app.

Notice that on the first time a user opens the app, he will see the default "orange" style. Your custom styles will be applied once the user has added a site in the app.

Notice also that styles comes from a site, there is no way for changing the initial Add site / Manage account pages styles.

See [[Moodle Mobile Themes]] for additional information.

== Mobile support for plugins ==

You can create Moodle plugins to change how the app works, see [[Mobile support for plugins]] for complete information.

== Creating a custom application ==

See [[Moodle Mobile custom apps]] or [https://moodle.com/mobileapp/ The Branded Moodle Mobile App service] by Moodle HQ

=== Building ===

There are two options for building the app, aka compile it to different devices:

'''Phonegap Build'''

[http://build.phonegap.com Phonegap Build] is an online service that lets you build the app automatically for different platforms. The main advantage is that it simplifies a lot the process of building.

You just put your www/ folder in a github account and Phonegaps automatically builds the app for different platforms pulling your github code.

Notice that the free version is for open repositories, but you can use the non-free version for private repositories.

In order to build your app using Phonegap Build you need to place a special config.xml file into the www/ folder, see [https://github.com/moodlehq/moodlemobile-phonegapbuild/blob/master/config.xml the config.xml file for Moodle Mobile 2] (Please, note that this file is different from the one created by Ionic in the app root folder). Please follow the tutorial mentioned in [[Moodle Mobile custom apps]] to view all the steps required for building the app using Phonegap Build service.

'''Ionic CLI'''

You can also build the app using the Ionic CLI tools, see: http://ionicframework.com/docs/cli/run.html

== Configuring how the app should work via Moodle site settings ==

The app can be configured via Moodle site settings. You can disable features, rename strings, add new elements to the main menu or change how log out works in the app. This requires Moodle 3.3 or the [[https://docs.moodle.org/en/Moodle_Mobile_additional_features Moodle Mobile additional features plugin]].

Please refer to the Configuring the app from your site section in this page: https://docs.moodle.org/en/Moodle_Mobile_guide_for_admins

== Testing and developing ==

=== Chromium or Google Chrome browser ===

See [[Moodle Mobile development using Chrome or Chromium]]

== Moodle Desktop ==

Refer to [[Moodle Desktop]]

== See also ==

[https://moodle.com/mobileapp/ Branded Moodle Mobile app service by Moodle HQ]

XMLDB defining an XML structure

2019-06-18T12:10:11Z

Demsley: Minor grammatical error corrected

[[XMLDB Documentation|XMLDB Documentation]] > [[XMLDB roadmap|Roadmap]] > Defining one XML structure
----

== Justification ==

Before Moodle 1.7, all the DB install and upgrade was developed twice (once to handle MySQL installations and another to handle PostgreSQL installations). This approach, although working, has caused some headaches in the past, mainly because it was really difficult to keep both lines of development 100% on sync. Some developers do they work against one RDBMS and it was complex to develop to the other one (two test environments, skills on both databases, slower development cycle...). And all this was happening with ''only'' two supported RDBMS!

One of the main objectives of Moodle 1.7 is to extend the the number of supported RDBMS to other flavours (more exactly, to Oracle and MSSQL). And the old approach (one line of development for each DB) could become an absolute nightmare.

Because of this we have planned to build one structure to define all the DB objects used by Moodle. This structure will provide the necessary level of abstraction to be shared by all the RDBMS systems, so the "multiple lines of development" explained in the previous paragraph will be out forever, giving us one robust and well defined way to handle DB objects independently of the underlying RDBMS being used.

== Implementation ==

Initially all our best wishes were to use the [http://phplens.com/lens/adodb/docs-datadict.htm#xmlschema AdoDB XML Schema]. As Moodle is using ADOdb libraries to communicate with databases it sounded like the natural approach to solve the problem. But, finally, two reasons prevented us to use it:

# Although working, it seems to be one feature in progress, with important changes/evolutions arriving at the time of write this document.
# Its lack of support for "prefixes" (one Moodle key feature, to allow multiple instances to run in the same server), would force us to create some awful tricks to generate the objects.

So, finally, we decided to build our own XML files, with everything we need to define every object present in the DB.

== The XMLDB editor ==
[[XMLDB_editor | Main article]]

Although the XML is pretty simple to read (and to write), one of the major drawbacks was its easy and error-prone adoption by the developers. Also some problems with versioning systems getting crazy with XML files (thanks ML!) pointed us to the requirement to use one high-density format (it means, physically '''long lines''') in our XML files.

After some intense thoughts we decided to build one specialised editor for our XML format. This editor should be easy to use and provide support for all the objects present one Moodle DB. And it's done (and will support future enhancements easily, we hope).

The XMLDB Editor makes the addition of tables/fields/keys/indexes practically a trivial task, allowing the developer to spend the time coding and improving things instead of fighting against XML files and the errors caused by manual editing (of course, the developer is free to use such extra-time as desired, beers, dance, books, music...) ;-)

All the new '''install.xml''' files, present under each '''db''' directory in Moodle can be edited (and we recommend it) with just some clicks and keystrokes. Those '''install.xml''' will contain all the info needed to generate the specific objects needed for each RDBMS supported. Obviously, such files, are the neutral replacement for all the *.sql files used until now.

=== Launching ===

Just login to your server as an administrator and, under the Development tab of the Administration Block, you'll see a new link pointing to the "XMLDB Editor".

One '''important note''' is that, to be able to handle files properly, the web server needs write access to all those "db" directories where the "install.xml" files reside (and to the files themselves, of course). ;-)

That's all!

=== Use===

We really think the XMLDB Editor is pretty easy to use, so here you won't see a complete guide to use it. We highly recommend you to play with it for a while, viewing how it works and how it modifies the '''install.xml''' files.

It's organised in a top-botton structure, where you start '''loading''' (or '''creating''') a new XMLDB file. Then, you can '''edit''' such file and its '''general structure''' will be showed. This structure have two type of elements, '''tables''' and '''statements''' and the XMLDB Editor allows you to '''add''', '''edit''', '''delete''', and '''move''' them easily. Also, for initial creation of tables, one small but effective '''reverse-enginery''' tool has been developed (only under MySQL) allowing you to retrofit any table from the DB to the XMLDB Editor.

'''Note: If you can't click on the create links....''' you must first create the /db folder (as shown in the list, but it may not really exist) and then make sure it is writeable by the webserver

While editing tables you will see their '''fields''', '''keys''' and '''indexes''' and you'll be able to handle all them easily. Note that some fields can be no-editable. It uses to be because they are being used in some way (part of one key or index) and the idea is to warn you about that.

Fields can be edited and you can specify their '''name''', '''type''', '''length''', '''decimals''', '''null-ability''', '''defaults''' and so one. Exactly the same for both '''keys''' and '''indexes'''.

While editing statements, you must think about them like "collections of sentences". Once you select the '''type''' (only inserts are allowed for now) and '''table''' you are interested you'll be able to introduce the exact values easily, being able to '''duplicate''' them easily to gain some speed if you have a lot of sentences in your development. Sentences can be '''edited''' and '''deleted''' easily too.

One interesting feature is that all the XMLDB Editor pages allow you to enter one '''comment''' about the item being modified (table, index, key, field, statement...). Use it at your entire needs, sure it helps other developers to understand a bit more the DB model.

Please, don't forget to read and understand the next section, where we talk about '''some important guidelines''' to create and handle XMLDB files.

== Conventions ==

Apart of the [[Database| Database Structures guidelines]], some more conventions should be followed:

# About names:
## All lowercase names (tables, indexes, keys and fields).
## Table names and field names must use only a-z, 0-9 and _ chars. Table names can be at most 28 characters long; column names at most 30 characters.
## Key and index names under the XMLDB Files must be formed by concatenating the name of the fields present in the key/index with the '"-" (minus) character.
## Primary key always must be named "primary" (this is one exception to the previous convention).
## It's highly recommended to avoid [[XMLDB_reserved_words|reserved words]] completely. We know we have some of them now but they should be completely out for next releases.
# About NULLS
## Avoid creating all the fields as NOT NULL with the ''silly'' default value <nowiki>''</nowiki> (empty string). The underlying code used to create tables will handle it properly but the XMLDB structure must be REAL. Read more in the [[XMLDB_Problems#NOT_NULL_fields_using_a_DEFAULT_.27.27_clause|Problems Page]].
# About FOREIGN KEYS
## Under the tables of every XMLDB file, you must define the existing '''Foreign Keys''' (FK) properly. This will allow everybody to know a bit better the structure, allow to evolve to a better constrained system in the future and will provide the underlying code with the needed info to create the proper indexes.
## Note that, if you define any field combination as FK you won't have to create any index on that fields, the code will do it automatically!
## Respect Convention 1.3
# About UNIQUE KEYS
## Declare any fields as UNIQUE KEY (UK) only if they are going to be used as target for one FK. Create unique indexes instead.
## Respect Convention 1.3

== One example: the assignment module ==

Here we are going to examine the [http://cvs.moodle.org/moodle/mod/assignment/db/install.xml?view=markup current implementation of the XMLDB Schema for the assignment module] (a simple one). It has been completely generated with the XMLDB Editor but it's nice to know a bit more about the XML internals.

As you can see the structure is pretty simple:

* XMLDB
** TABLES, one or more, each one with
*** FIELDS
*** KEYS
*** INDEXES
** STATEMENTS, none or more, each one with
*** SENTENCES

First of all you should note that all the elements contain the '''PREVIOUS''' and '''NEXT''' attributes. They allow us to keep everything ordered although it isn't meaningful at all from the RDBMS perspective. Also the '''COMMENT''' field is present everywhere to be used as desired.

=== The TABLE element ===

We can ignore the TABLE element, as it's simply one container for the internals (FIELDS, KEYS and INDEXES). Let's go to examine them a bit more:

==== The FIELD element ====

It maps with one field in the DB (obviously). For each field you can define its '''name''', '''type''' (from a list of [[XMLDB column types|neutral types]]), '''length''', '''decimals''' (for some types), '''notnull''' (true/false), '''unsigned''' (true/false), '''sequence''' (if it's autonumeric or serial, true/false) and '''default''' (to assign a default value).

So, in our example, we have two tables, assignment and assignment_submissions, each one with its own fields, defining all the information related above. Please note that naming conventions are followed.

==== The KEY element ====

Here is where all the PRIMARY KEYS (PK), UNIQUE KEYS (UK) and FOREIGN KEYS (FK) will be defined. For each key we define its '''name''', '''type''', '''fields''' (that belongs to it) and optionally (if the key is one FK) the target '''reftable''' and '''reffields'''.

In our example, the assignment table has one (mandatory!) PK (called, "primary", rules are rules) built with the "id" field.

The other table, the "assignment_submissions" one, also has its PK (called "primary" once more) and one FK, with the field "assignment" pointing to the field "id" of the table "assignment". Note that the FK follows the name conventions and its name is, simply, the name of the fields being part of it ("assignment"). Also, the FK has as target to one PK of the same module.

Finally, note that there isn't any index created for all these keys. Moodle will generate them automatically when the table is created. All the keys will have their corresponding index. Point. ;-)

==== The INDEX element ====

Where all the indexes will be defined. For each index you can define its '''name''', '''unique''' (true/false) and the '''fields''' (as a comma-separated string) that it comprises. Please note that naming conventions are followed.

Also, some "obvious index", like the one based in the "assignment" field of the "assignment_submissions" table doesn't exist. Yes, you know why: Because such column has been defined as a FK and the index will be automatically created (see previous section).

=== The STATEMENT element ===

This is the other '''big container''' in the XMLDB Schema (at the same level as the '''TABLES''' one) and we can define its '''name''', '''type''' (only insert allowed for now) and '''table''' (against the sentences will be executed).

Every statement is a collection of '''sentences'''

==== The SENTENCE element ====

Each sentence implies one simple action to be performed against the DB and it can be defined as the "missing part of the SQL statement". In our example, we have one statement, of type "insert" on table "log_display". With this Moodle knows the initial part of the sentence, i.e:

INSERT INTO log_display

and then the text will be added to create this:

INSERT INTO log_display
(module, action, mtable, field)
VALUES
('assignment', 'view', 'assignment', 'name')

There is one important trick when handling sentences, although they aren't in the assignment example. Take a look to the [http://cvs.moodle.org/moodle/lib/db/install.xml?view=co Core Tables XML Schema] (it's a huge one!). If you go near the end, to the statements section, you will see some sentences like this:

<SENTENCE TEXT="....VALUES ('user', 'view', 'user', 'CONCAT(firstname," ",lastname)')"/>

Such "CONCAT" function isn't standard at all (only MySQL supports it), but don't worry, we'll transform it to the correct concatenation operators for other RDBMS. Just be sure to use the syntax showed above.

== DTD and XML schema ==

Not sure if this will be usable for somebody but here you can find one [http://cvs.moodle.org/moodle/lib/xmldb/xmldb.dtd?view=co automatically generated DTD] for the XMLDB files. Also one [http://cvs.moodle.org/moodle/lib/xmldb/xmldb.xsd?view=co automatically generated XML Schema] is available. Any improvement/fix to them will be welcome!

== See also ==

* [[XMLB List of files to create|List of files to create]]: The list of files to be created from scratch. Used to follow the progress.
* http://www.hitsw.com/xml_utilites/: One online XML-DTD-Schema converter.

[[Category:XMLDB]]
[[Category:DB]]

File API internals

2017-12-19T13:28:11Z

Demsley: /* File storage on disk */

{{Infobox Project
|name = File API
|state = Implemented
|tracker = MDL-14589
|discussion = n/a
|assignee = [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]]
}}
{{Moodle 2.0}}

==Objectives==

The goals of the new File API are:

* allow files to be stored within Moodle, as part of the content (as we do now).
* use a consistent and flexible approach for all file handling throughout Moodle.
* give modules control over which users can access a file, using capabilities and other local rules.
* make it easy to determine which parts of Moodle use which files, to simplify operations like backup and restore.
* track where files originally came from.
* avoid redundant storage, when the same file is used twice.
* fully support Unicode file names, irrespective of the capabilities of the underlying file system.

==Overview==

The File API is a set of core interfaces to allow the rest of Moodle to store, serve and manage files. It applies only to files that are part of the Moodle site's content. It is not used for internal files, such as those in the following subdirectories of dataroot: temp, lang, cache, environment, filter, search, sessions, upgradelogs, ...

To learn how to use File API, please visit [[Using the File API]].

The API can be subdivided into the following parts:
; File storage
: Low level file storage without access control information. Stores the content of files on disc, with metadata in associated database tables.
; File serving
: Lets users accessing a Moodle site get the files (file.php, draftfile.php, pluginfile.php, userfile.php, etc.)
:* Serve the files on request
:* with appropriate security checks
; File related user interfaces
: Provides the interface for (lib/form/file.php, filemanager.php, filepicker.php and files/index.php, draftfiles.php)
:* Form elements allowing users to select a file using the file picker, and have it stored within Moodle.
:* UI for users to manage their files, replacing the old course files UI
; File browsing API
: Allows code to browse and optionally manipulate the file areas
:* find information about available files in each area.
:* print links to files.
:* optionally move/rename/copy/delete/etc.

== File API internals ==

=== File storage on disk ===

Files are stored in $CFG->dataroot (also known as moodledata) in the filedir subfolder.

Files are stored according to the SHA1 hash of their content. This means each file with particular contents is stored once, irrespective of how many times it is included in different places, even if it is referred to by different names. (This idea comes from the git version control system.) To relate a file on disc to a user-comprehensible path or filename, you need to use the ''files'' database table. See the next section.

Suppose a file has SHA1 hash 081371cb102fa559e81993fddc230c79205232ce in the files table contenthash field. Then it will be stored in on disc as moodledata/filedir/08/13/081371cb102fa559e81993fddc230c79205232ce.

This means Moodle can not store two files with the same SHA1 hash, luckily it is extremely unlikely that this would ever happen. Technically it is also possible to implement reliable collision tests (with some performance cost), for now we just test file lengths in addition to SHA1 hash.

As files on-disk are named with their sha1 hash, there is a simple way of validating files have not been corrupted since upload by using the 'sha1sum' command available in most GNU/Linux distributions.
In the below example, the user changed directory to the known location of a file on disk (sourced by finding the contenthash of the relevant file in the mdl_files database table).
Then, in this directory the 'sha1sum' command is issued with the file that you wish to hash the content of. Returned from the command is the hash of the content (on the left) and the file name (on the right).

Where a file is NOT corrupted after upload, these two strings will match.

$ cd /moodlepath/moodledata/filedir/1d/df/
$ sha1sum 1ddf5b375fcb74929cdd7efda4f47efc61414edf
1ddf5b375fcb74929cdd7efda4f47efc61414edf 1ddf5b375fcb74929cdd7efda4f47efc61414edf

Where a file IS corrupted after upload, these will differ:

$ cd /moodlepath/moodledata/filedir/42/32/
$ sha1sum 42327aac8ce5741f51f42be298fa63686fe81b7a
9442188152c02f65267103d78167d122c87002cd 42327aac8ce5741f51f42be298fa63686fe81b7a
This is a very handy trick as in the case of any disk corruption (shared storage issues, hard drive issues, disk sector issues etc) the corrupted files can be detected without resorting to manually comparing to previous backups.

=== Files table ===

This table contains one entry for each usage of a file. Enough information is kept here so that the file can be fully identified and retrieved again if necessary. It is necessary because some databases have hard limit on index size.

If, for example, the same image is used in a user's profile, and a forum post, then there will be two rows in this table, one for each use of the file, and Moodle will treat the two as separate files, even though the file is only stored once on disc.

{| class="nicetable"
! Field
! Type
! Default
! Info
|-
| '''id'''
| int(10)
| auto-incrementing
| The unique ID for this file.
|-
| '''contenthash'''
| varchar(40)
|
| The sha1 hash of content.
|-
| '''pathnamehash'''
| varchar(40)
|
| The sha1 hash of "/contextid/component/filearea/itemid/filepath/filename.ext" - prevents file duplicates and allows fast lookup. It is necessary because some databases have hard limit on index size.
|-
| '''contextid'''
| int(10)
|
| The context id defined in context table - identifies the instance of plugin owning the file.
|-
| '''component'''
| varchar(50)
|
| Like "mod_forum", "course", "mod_assignment", "backup"
|-
| '''filearea'''
| varchar(50)
|
| Like "submissions", "intro" and "content" (images and swf linked from summaries), etc.; "blogs" and "userfiles" are special case that live at the system context.
|-
| '''itemid'''
| int(10)
|
| Some plugin specific item id (eg. forum post, blog entry or assignment submission or user id for user files)
|-
| filepath
| text
|
| relative path to file from module content root, useful in Scorm and Resource mod - most of the mods do not need this
|-
| filename
| varchar(255)
|
| The full Unicode name of this file (case sensitive)
|-
| '''userid'''
| int(10)
| NULL
| (optional) Almost always this is the user that created the file, although some modules may choose to use this field for other purposes.
|-
| filesize
| int(10)
|
| size of file - bytes
|-
| mimetype
| varchar(100)
| NULL
| type of file
|-
| status
| int(10)
|
| general file status flag - will be used for lost or infected files
|-
| source
| text
|
| file source - usually url
|-
| author
| varchar(255)
|
| original author of file, used when importing from other systems
|-
| license
| varchar(255)
|
| license type, empty means site default
|-
| timecreated
| int(10)
|
| The time this file was created
|-
| timemodified
| int(10)
|
| The last time the file was last modified
|}

Indexes:
* non-unique index on (contextid, component, filearea, itemid)
* non-unique index on (contenthash)
* unique index on (pathnamehash).

The plugin type does not need to be specified because it can be derived from the context. Items like blog that do not have their own context will use their own file area inside a suitable context. In this case, the user context.

Entries with filename = '.' represent directories. Directory entries like this are created automatically when a file is added within them.

Note: 'files' plural is used even thought that goes against the [[Database|coding guidelines]] because 'file' is a reserved word in some SQL dialects.

===Implementation of basic operations===

'''Each plugin may directly access only files in own context and areas!'''

Low level access API is defined in ''file_storage'' class which is obtained from <code>get_file_storage()</code>.

====Storing a file====

# Calculate the SHA1 hash of the file contents.
# Check if a file with this SHA1 hash already exists on disc in file directory or file trash. If not, store the file there.
# Add the record for this file to the files table using the low level address

====Reading a file====

# Fetch the record (which includes the SHA1 hash) for the file you want from the files table. You can fetch either all area files or quickly get one file with a specific contenthash.
# Retrieve the contents using the SHA1 hash from the file directory.

====Deleting a file====

# Delete the record from the files table.
# Verify if some other file is still needing the content, if not move the content file into file trash
# Later, admin/cron.php deletes content files from trash directory

== File serving ==

Deals with serving of files - browser requests file, Moodle sends it back. We have three main files. It is important to setup slasharguments on server properly (file.php/some/thing/xxx.jpg), any content that relies on relative links can not work without it (scorm, uploaded html pages, etc.).

=== legacy file.php ===

Serves legacy course files, the file name and parameter structure is critical for backwards compatibility of existing course content.

/file.php/courseid/dir/dir/filename.ext

Internally the files are stored in <code>array('contextid'=>$coursecontextid, 'component;=>'course', 'filearea'=>'legacy', 'itemid'=>0)</code>

The legacy course files are completely disabled in all new courses created in 2.0. The major problem here is to how to educate our users that they can not make huge piles of files in each course any more.

=== pluginfile.php ===
All plugins should use this script to serve all files.
* plugins decide about access control
* optional XSS protection - student submitted files must not be served with normal headers, we have to force download instead; ideally there should be second wwwroot for serving of untrusted files
* links to these files are constructed on the fly from the relative links stored in database, this means that plugin may link only own files

Absolute file links need to be rewritten if html editing allowed in plugin. The links are stored internally as relative links. Before editing or display the internal link representation is converted to absolute links using simple str_replace() @@thipluginlink/summary@@/image.jpg --> /pluginfile.php/assignmentcontextid/intro/image.jpg, it is converted back to internal links before saving.

Script parameters are virtual file names, in most cases the parameters match the low level file storage, but they do not have to:

/pluginfile.php/contextid/areaname/arbitrary/params/or/dirs/filename.ext

pluginfile.php detects the type of plugin from context table, fetches basic info (like $course or $cm if appropriate) and calls plugin function (or later method) which does the access control and finally sends the file to user. ''areaname'' separates files by type and divides the context into several subtrees - for example ''summary'' files (images used in module intros), post attachments, etc.

==== Assignment example ====

/pluginfile.php/assignmentcontextid/mod_assignment/intro/someimage.jpg
/pluginfile.php/assignmentcontextid/mod_assignment/submission/submissionid/attachmentname.ext
/pluginfile.php/assignmentcontextid/mod_assignment/allsubmissions/groupid/allsubmissionfiles.zip

The last line example of virtual file that should created on the fly, it is not implemented yet.

====scorm example====

/pluginfile.php/scormcontextid/mod_scorm/intro/someimage.jpg
/pluginfile.php/scormcontextid/mod_scorm/content/revisionnumber/dir/somescormfile.js

The revision counter is incremented when any file changes in order to prevent caching problems.

====quiz example====

pluginfile.php/quizcontextid/mod_quiz/intro/niceimage.jpg

====questions example====

This section was out of date. See [[File_storage_conversion_Quiz_and_Questions]] for the latest thinking.

====blog example====
Blog entries or notes in general do not have context id (because they live in system context, SYSCONTEXTID below is the id of system context).
The note attachments are always served with XSS protection on, ideally we should use separate wwwroot for this. Access control can be hardcoded.

/pluginfile.php/SYSCONTEXTID/blog/attachment/blogentryid/attachmentname.ext

Internally stored in <code>array('contextid'=>SYSCONTEXTID, 'component'=>'blog', 'filearea'=>'attachment', 'itemid'=>$blogentryid)</code>

/pluginfile.php/SYSCONTEXTID/blog/post/blogentryid/embeddedimage.ext

Internally stored in <code>array('contextid'=>SYSCONTEXTID, 'component'=>'blog', 'filearea'=>'post', 'itemid'=>$blogentryid)</code>

=== Temporary files ===
Temporary files are usually used during the lifetime of one script only.
uses:
* exports
* imports
* processing by executable files (latex, mimetex)

These files should never use utf-8 file names.

=== Legacy file storage and serving ===
Going to use good-old separate directories in $CFG->dataroot.

file serving and storage:
# user avatars - user/pix.php
# group avatars - user/pixgroup.php
# tex, algebra - filter/tex/* and filter/algebra/*
# rss cache (?full rss rewrite soon?) - backwards compatibility only rss/file.php

only storage:
#sessions

== File browsing API ==

This is what other parts of Moodle use to access files that they do not own.

=== Class: file_browser ===

=== Class: file_info and subclasses ===

== File related user interfaces ==

All files are obtained through from the file repositories.

=== Formslib fields ===
* file picker
* file manager
* file upload (obsolete, do not use)

=== Integration with the HTML editor ===

Each instance of the HTML editor can be told to store related files in a particular file area.

During editing, files are stored in a draft files area. Then when the form is submitted they are moved into the real file area.

Files are selected using the repository file picker.

=== Legacy file manager ===

Available only for legacy reasons. It is not supposed to be used.

All the contexts, file areas and files now form a single huge tree structure, although each user only has access to certain parts of that tree. The file manager (files/index.php) allow users to browse this tree, and manage files within it, according to the level of permissions they have.

Single pane file manager is hard to implement without drag & drop which is notoriously problematic in web based applications. I propose to implement a two pane commander-style file manager. Two pane manager allows you to easily copy/move files between two different contexts (ex: courses).

File manager must not interact directly with filesystem API, instead each module should return traversable tree of files and directories with both real and localised names (localised names are needed for dirs like backupdata).

== Backwards compatibility ==

=== Content backwards compatibility ===

This should be preserved as much as possible. This will involve rewriting links in content during the upgrade to 2.0.

Some new features (like resource sharing - if implemented) may not work with existing data that still uses files from course files area.

There might be a breakage of links due to special characters stripping in uploaded files which will not match the links in uploaded html files any more. This should not be very common I hope.

===Code backwards compatibility===

Other Moodle code (for example plugins) will have to be converted to the new APIs. See [[Using_the_file_API]] for guidance.

It is not possible to provide backwards-compatibility here. For example, the old $CFG->dataroot/$courseid/ will no longer exist, and there is no way to emulate that, so we won't try.

== Upgrade and migration ==

When a site is upgraded to Moodle 2.0, all the files in moodledata will have to be migrated. This is going to be a pain, like DML/DDL was :-(

The upgrade process should be interruptible (like the Unicode upgrade was) so it can be stopped/restarted any time.

=== Migration of content ===

* resources - move files to new resource content file area; can be done automatically for pdf, image resources; definitely not accurate for uploaded web pages
* questions - image file moved to new area, image tag appended to questions
* moddata files - the easiest part, just move to new storage
* coursefiles - there might be many outdated files :-( :-(
* rss feeds links in readers - will be broken, the new security related code would break it anyway

=== Moving files to files table and file pool ===

The migration process must be interruptable because it might take a very long time. The files would be moved from old location, the restarting would be straightforward.

Proposed stages:
#migration of all course files except moddata - finish marked by some $CFG->files_migrated=true; - this step breaks the old file manager and html editor integration
#migration of blog attachments
#migration of question files
#migration of moddata files - each module is responsible to copy data from converted coursefiles or directly from moddata which is not converted automatically

Some people use symbolic links in coursefiles - we must make sure that those will be copied to new storage in both places, though they can not be linked any more - anybody wanting to have content synced will need to move the files to some repository and set up the sync again.

::Talked about a double task here, when migrating course files to module areas:
::# Parse html files to detect all the dependencies and move them together.
::# Fallback in pluginfile.php so, if something isn't found in module filearea, search for it in course filearea, copying it and finally, serving it.

:: Also we talked about the possibility of add a new setting to resource in order to define if it should work against old coursefiles or new autocontained file areas. Migrated resources will point to old coursefiles while new ones will enforce autocontained file areas.

:: it seems that only resource files will be really complex (because allow arbitrary HTML inclusion). The rest (labels, intros... doesn't) and should be easier to parse.

::[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 19:00, 29 June 2008 (CDT)

== Other issues ==

=== Unicode support in zip format ===

Zip format is an old standard for compressing files. It was created long before Unicode existed, and Unicode support was only recently added. There are several ways used for encoding of non-ASCII characters in path names, but unfortunately it is not very standardised. Most Windows packers use DOS encoding.

Client software:
* Windows built-in compression - bundled with Windows, non-standard DOS encoding only
* WinZip - shareware, Unicode option (since v11.2)
* TotalCommander - shareware, single byte(DOS) encoding only
* 7-Zip - free, Unicode or DOS encoding depending on characters used in file name (since v4.58beta)
* Info-ZIP - free, uses some weird character set conversions

PHP extraction:
* Info-ZIP binary execution - no Unicode support at all, mangles character sets in file names (depends on OS, see docs), files must be copied to temp directory before compression and after extraction
* PclZip PHP library - reads single byte encoded names only, problems with random problems and higher memory usage.
* Zip PHP extension - kind of works in latest PHP versions

Large file support:
PHP running under 32bit operating systems does not support files >2GB (do not expect fix before PHP 6). This might be a potential problem for larger backups.

Tar Alternative:
* tar with gzip compression - easy to implement in PHP + zlib extension (PclTar, Tar from PEAR or custom code)
* no problem with unicode in *nix, Windows again expects DOS encoding :-(
* seems suitable for backup/restore - yay!

Summary:
# added zip processing class that fully hides the underlying library
# using single byte encoding "garbage in/garbage out" approach for encoding of files in zip archives; add new 'zipencoding' string into lang packs (ex: cp852 DOS charset for Czech locale) and use it during extraction (we might support true unicode later when PHP Zip extension does that)

=== Tar packer ===

A .tar.gz format packer is available from Moodle 2.6 (requires zlib extension) and can be selected for use in Moodle backup via an experimental option. MDL-41838.

The packer is currently limited to ASCII filenames and individual files are limited to 8GB each, but unlike zip there is no limit on the total filesize. It uses the old POSIX format and is compatible with GNU tar using default options.

== Not implemented yet ==
* antivirus scanning - this needs a different api because the upload of files is now handled via repository plugins

== See also ==

* [[Using the File API]]
* [[Repository API]]
* [[Portfolio API]]
* [[Resource module file API migration]]
* MDL-14589 - File API Meta issue

[[Category:Files]]
[[Category:Interfaces]]

Grunt

2017-12-05T15:31:53Z

Demsley: /* Install grunt */

{{Moodle 2.9}}

Grunt is a command line tool used to prepare our javascript and less-generated css for production usage. After making any change to javascript or less files in Moodle, you must run grunt to lint, minify and package the javascript/css properly so that it can be served by Moodle.

== Install grunt ==
The Javascript modules (AMD and YUI) and less css in Moodle must be processed by some build tools before they will be visible to your web browser. We use "[http://gruntjs.com/ grunt]" as a build tool to wrap our different processes. Grunt is a build tool written in Javascript that runs in the "[http://nodejs.org/ nodejs]" environment. This means you first have to install nodejs - and it's package manager "[https://www.npmjs.com/ npm]". The details of how to install those packages will vary by operating system, but on Linux it's likely to be:
apt-get install nodejs npm
See also: [http://askubuntu.com/questions/594656/how-to-install-the-latest-versions-of-nodejs-and-npm-for-ubuntu-14-04-lts/711976 how to install the latest version of nodejs and npm for ubuntu 14.04]

There are downloadable packages for other operating systems here: http://nodejs.org/download/.

Once this is done, cd into your Moodle directory and run the command:
npm install
to install all of the required tools.

You also need to install the grunt-cli package globally in order to have a "grunt" command in your path. To do this run:
npm install -g grunt-cli

== Running grunt ==
Typical commands:

grunt amd # Short-cut for grunt jshint uglify, rebuild all AMD modules.
grunt shifter # Run shifter
grunt js # Short-cut for grunt amd shifter

grunt css # Run less
grunt # Try to do the right thing:
# * If you are in a folder called amd, do grunt amd
# * If you are in a folder called yui/src/something, do grunt shifter
# * Otherwise build everything (grunt css js).

grunt watch # Watch for changes and re-run grunt tasks depending on what file changes
grunt eslint --show-lint-warnings # Show pedantic lint warnings for JS

On Linux/Mac it will build everything in the current folder and below. On Windows, you need to specify the path on the command line like <tt>--root=admin/tool/templatelibrary</tt>.

== Using Grunt in additional plugins ==

You may want to use Grunt for performing tasks in your custom Moodle plugins. For building AMD and YUI modules in your plugin, the standard configuration Gruntfile.js located in the Moodle root should work well. For building CSS files from LESS templates, you will have to set up a separate Grunt installation in the root of your plugin.

If you do not have it yet, create the package.json file in the root of your plugin:

{
"name": "moodle-plugintype_pluginname"
}

Install grunt, grunt less and grunt watch modules. Note that you should put the folder node_modules into your plugin's .gitignore file, too.

$ cd /path/to/your/plugin/root
$ npm install --save-dev grunt grunt-contrib-less grunt-contrib-watch grunt-load-gruntfile

Create a Gruntfile.js in the root of your plugin and configure the task for building CSS files from LESS:

<code javascript>
"use strict";

module.exports = function (grunt) {

// We need to include the core Moodle grunt file too, otherwise we can't run tasks like "amd".
require("grunt-load-gruntfile")(grunt);
grunt.loadGruntfile("../../Gruntfile.js");

// Load all grunt tasks.
grunt.loadNpmTasks("grunt-contrib-less");
grunt.loadNpmTasks("grunt-contrib-watch");
grunt.loadNpmTasks("grunt-contrib-clean");

grunt.initConfig({
watch: {
// If any .less file changes in directory "less" then run the "less" task.
files: "less/*.less",
tasks: ["less"]
},
less: {
// Production config is also available.
development: {
options: {
// Specifies directories to scan for @import directives when parsing.
// Default value is the directory of the source, which is probably what you want.
paths: ["less/"],
compress: true
},
files: {
"styles.css": "less/styles.less"
}
},
}
});
// The default task (running "grunt" in console).
grunt.registerTask("default", ["less"]);
};
</code>

Now running "grunt" or "grunt less" in your plugin root folder will compile the file less/styles.less and saves it as styles.css. Running "grunt watch" will watch the less/*.less files and if some is changed, it will immediately rebuild the CSS file.

If you are working on a custom theme, you may have multiple less/*.less files that you want to compile to their style/*.css counterparts. You can either define an explicit list all such file pairs, or let that list be created for you by making use of [http://gruntjs.com/configuring-tasks#building-the-files-object-dynamically expand:true feature] of gruntfile.js:

<code javascript>
// This dynamically creates the list of files to be processed.
files: [
{
expand: true,
cwd: "less/",
src: "*.less",
dest: "style/",
ext: ".css"
}
]
</code>

== See also ==
* [[YUI/Shifter]]
* [[Javascript Modules]]
* [[LESS]]

[[Category:AJAX]]
[[Category:Javascript]]

Using images in a theme

2017-11-23T12:02:49Z

Demsley: /* Using your images within your layout files */

{{Template:Themes}}
==A little background==
Moodle a standard way of making use of images within its pages enabling theme designers to take full control over what images are being used and when possible ensures images are passed through Moodle's performance caching system to obtain the best possible performance.

==Before we start==

# Make sure you have a theme and images to work with, one that you have a backup of just in case.
# Take note of your theme's main layout file e.g. ''standard.php''.
# Take note of your theme's main CSS file e.g. ''core.css''.
# Turn on '''Theme designer mode'''.

==Image locations within Moodle==

There are three main areas in which images are located - core, plugin and theme.

Core images are used throughout Moodle and are stored in ''moodle/pix''.

The pix directory contains the following subdirectories:

:''a'' - Icons that are not widely used
:''c'' - Calendar-related icons
:"e" - Editor-related icons
:''f'' - File icons for different file types
:''g'' - Default user icons and thumbnails
:''i'' - General icons
:''m'' - Currency symbols
:''s'' - Smileys
:''t'' - General icons
:''u'' - User icons and thumbnails
:''y'' - YUI icons

Plugin images are used by plugins and are stored within the plugin's directory e.g. ''mod/forum/*'' or ''blocks/navigation/*''

Theme images are used in themes and are stored in the ''pix'' subdirectory of a theme.

==Adding new images to your theme==

To add new images to your theme, such as a background image or a logo, you should start by creating a pix directory within your themes directory.

Lets assume you have two images, gradient.png and logo.jpg. Copy both files to your themes pix directory.

The plan is to use gradient.png as the background image for your theme (in CSS) and use logo.jpg in the header (in your theme's layout file).

===Using images within CSS===

Moodle parses all CSS files. When theme designer mode is off, Moodle combines them into a handful of large CSS files that get cached and served. At the same time Moodle also looks at the CSS and replaces special syntax rules.

<div style='padding:10px;background-color:#f7f7f7;border:1px dashed #123456'><nowiki>[[pix:theme|</nowiki><span style='color:#336699;font-weight:bold;'><nowiki>path/to/image/</nowiki></span><span style='color:#33993A;font-weight:bold;'>imagename</span><nowiki>]]</nowiki></div>

The above pattern is looked for by Moodle and gets replaced with the correct image URL when found.
You should note the following things about this pattern when using your own images within CSS:

# The bits in black don't change
# The bit in blue is the path to your image within the pix directory. It shouldn't start with a / but should end with one.
# The bit in green is the filename ('''no need to include the file extension''')

To use gradient.png as the background for our pages, add the following line of CSS to the themes core.css.
<code css>
body {background-image:url([[pix:theme|gradient]]);}
</code>

Before we look at how to use your own images within your themes layout files we should first look at how this changes if the image is in a sub directory.

Lets assume gradient.png is located here: '''pix/myimages/gradients/gradient.png'''

The CSS would need to be as follows:
<code css>
body {background-image:url([[pix:theme|myimages/gradients/gradient]]);}
</code>

If you want to refer to an image belonging to a plugin, you can do it like this:

<code css>
body {background-image:url([[pix:quiz|icon]]);}
body {background-image:url([[pix:qtype_ddmarker|grid]]);}
</code>

That refers to mod/quiz/pix/icon.png/gif and question/type/ddmarker/pix/grid.png/gif respectively (or whatever icons you have put in your theme to override these).

===Using your images within your layout files===

To use logo.jpg within the a layout php file or layout mustache template you need to add the url for the image to the template context and then include an image tag in the template using the source from the context.

Images:
<code>
/pix/logo.jpg
/pix/myimages/logos/logo.png
</code>

''theme/yourtheme/layout/somelayout.php''
<code php>
...
$templatecontext = [
...
'imageone' => $OUTPUT->image_url('logo', 'theme'),
'imagetwo' => $OUTPUT->image_url('myimages/logos/logo', 'theme'),
...
];

echo $OUTPUT->render_from_template('theme_yourtheme/somelayout', $templatecontext);
</code>

''theme/yourtheme/templates/somelayout.mustache''
<code handlebars>
...
<img src="{{{imageone}}}" alt="Please give your image alt text or set the role to presentation" width="50" height="50">
<img src="{{{imagetwo}}}" alt="Please give your image alt text or set the role to presentation" width="50" height="50">
...
</code>

==Overriding images in your theme==

Overriding images within your theme can be an important part of creating and/or modifying themes.

As mentioned, there are three main areas for images within Moodle, core, plugins, and themes. Obviously we won't be overriding theme images as we are in a theme and have full control over that already which just leaves core and plugin images that you may want to override.

Within your theme create the following two directories:
; /pix_core/ : This is where your images to override core images will need to be.
; /pix_plugins/ : This is where images to override plugins will need to be.

Next, copy the images that you wish to override into either the pix_core or pix_plugins directory. You need to replicate the directory structure that the images are located in.

The following two examples illustrate how this works for both core and plugin images.

===Overriding core images===
For this example I am going to override the following two images:
# '''moodle/pix/help.gif''' This image is used for all help image icons and is shown throughout Moodle.
# '''moodle/pix/i/info.gif''' This image is used in several places, most notably the front page if the combo list is being displayed.

So first up help.gif. This is the most basic example of overriding an image. Because the image is directly within Moodle's pix directory we can simply place our new help image into our themes pix_core directory. There's nothing more to it!

The second example if not really any more difficult. Because the image is located within the subdirectory '''i''' we must create a sub directory within our pix_core directory into which we will copy our new help image. That is, the image ends up at '''/pix_core/i/info.png''' inside your theme folder. And again done!

You should also note that, as with any other image in Moodle, the extension doesn't matter. If you want to replace help.gif with a help.png you can just put the png into the correct directory. As long as the filename is the same Moodle will find it.

===Overriding plugin images===
This is a little bit more difficult than overriding core images, but not too much so. For this example, let's say I want to override the following two plugin images:
# '''moodle/mod/forum/icon.gif''' This is the icon that is used everywhere for the forum.
# '''moodle/blocks/customblock/activate.png''' This is an icon in a custom block I have installed.

Just as with core images, we need to put the image in the correct directory structure. In this case it is going to be within our theme's '''pix_plugins''' directory.
The correct path must use the plugin type [[Frankenstyle]] prefix and the plugin name.

For the examples above the paths to override the plugin images will be:
# '''pix_plugins/mod/forum/'''
# '''pix_plugins/block/customblock/'''

When looking for an overriding image the following path is used.

# theme (static)
# themename => mytheme
# area => pix_plugins for plugin images, pix_core for core images, pix for theme images.
# plugin type => booktool for the book tool sub plugin for example.
# plugin name => print for the name of the sub plugin.
# file name => book for the name of the image.

It then searches for the image with the following extensions gif, png, jpg, jpeg in that order.

So you end up with:
<code>
/theme/themename/area/plugintype/pluginname/filename.gif
</code>

==See also==

* [[Plugins]]
* [http://youtu.be/g_9VM9OMs3Y Adding Images to your Theme] MoodleBites video on YouTube

Using Moodle forum discussions:
* [http://moodle.org/mod/forum/discuss.php?d=151581 Using images within your themes (and the silk icon theme)]
* [http://moodle.org/mod/forum/discuss.php?d=151581#p689883 choosing images based on the users current language]
* [http://moodle.org/mod/forum/discuss.php?d=157935&parent=691903 how to add a category(categorias) img-bullet]

Using images in a theme

2017-05-22T14:29:24Z

Demsley: /* Using your images within your layout files */

{{Template:Themes}}
==A little background==
Moodle a standard way of making use of images within its pages enabling theme designers to take full control over what images are being used and when possible ensures images are passed through Moodle's performance caching system to obtain the best possible performance.

==Before we start==

# Make sure you have a theme and images to work with, one that you have a backup of just in case.
# Take note of your theme's main layout file e.g. ''standard.php''.
# Take note of your theme's main CSS file e.g. ''core.css''.
# Turn on '''Theme designer mode'''.

==Image locations within Moodle==

There are three main areas in which images are located - core, plugin and theme.

Core images are used throughout Moodle and are stored in ''moodle/pix''.

The pix directory contains the following subdirectories:

:''a'' - Icons that are not widely used
:''c'' - Calendar-related icons
:"e" - Editor-related icons
:''f'' - File icons for different file types
:''g'' - Default user icons and thumbnails
:''i'' - General icons
:''m'' - Currency symbols
:''s'' - Smileys
:''t'' - General icons
:''u'' - User icons and thumbnails
:''y'' - YUI icons

Plugin images are used by plugins and are stored within the plugin's directory e.g. ''mod/forum/*'' or ''blocks/navigation/*''

Theme images are used in themes and are stored in the ''pix'' subdirectory of a theme.

==Adding new images to your theme==

To add new images to your theme, such as a background image or a logo, you should start by creating a pix directory within your themes directory.

Lets assume you have two images, gradient.png and logo.jpg. Copy both files to your themes pix directory.

The plan is to use gradient.png as the background image for your theme (in CSS) and use logo.jpg in the header (in your theme's layout file).

===Using images within CSS===

Moodle parses all CSS files. When theme designer mode is off, Moodle combines them into a handful of large CSS files that get cached and served. At the same time Moodle also looks at the CSS and replaces special syntax rules.

<div style='padding:10px;background-color:#f7f7f7;border:1px dashed #123456'><nowiki>[[pix:theme|</nowiki><span style='color:#336699;font-weight:bold;'><nowiki>path/to/image/</nowiki></span><span style='color:#33993A;font-weight:bold;'>imagename</span><nowiki>]]</nowiki></div>

The above pattern is looked for by Moodle and gets replaced with the correct image URL when found.
You should note the following things about this pattern when using your own images within CSS:

# The bits in black don't change
# The bit in blue is the path to your image within the pix directory. It shouldn't start with a / but should end with one.
# The bit in green is the filename ('''no need to include the file extension''')

To use gradient.png as the background for our pages, add the following line of CSS to the themes core.css.
<code css>
body {background-image:url([[pix:theme|gradient]]);}
</code>

Before we look at how to use your own images within your themes layout files we should first look at how this changes if the image is in a sub directory.

Lets assume gradient.png is located here: '''pix/myimages/gradients/gradient.png'''

The CSS would need to be as follows:
<code css>
body {background-image:url([[pix:theme|myimages/gradients/gradient]]);}
</code>

If you want to refer to an image belonging to a plugin, you can do it like this:

<code css>
body {background-image:url([[pix:quiz|icon]]);}
body {background-image:url([[pix:qtype_ddmarker|grid]]);}
</code>

That refers to mod/quiz/pix/icon.png/gif and question/type/ddmarker/pix/grid.png/gif respectively (or whatever icons you have put in your theme to override these).

===Using your images within your layout files===

To use logo.jpg within the a layout php file or layout mustache template you need to add the url for the image to the template context and then include an image tag in the template using the source from the context.

Images:
<code>
/pix/logo.jpg
/pix/myimages/logos/logo.png
</code>

''theme/yourtheme/layout/somelayout.php''
<code php>
...
$templatecontext = [
...
'imageone' => $OUTPUT->pix_url('logo', 'theme'),
'imagetwo' => $OUTPUT->pix_url('myimages/logos/logo', 'theme'),
...
];

echo $OUTPUT->render_from_template('theme_yourtheme/somelayout', $templatecontext);
</code>

''theme/yourtheme/templates/somelayout.mustache''
<code handlebars>
...
<img src="{{{imageone}}}" alt="Please give your image alt text or set the role to presentation" width="50" height="50">
<img src="{{{imagetwo}}}" alt="Please give your image alt text or set the role to presentation" width="50" height="50">
...
</code>

==Overriding images in your theme==

Overriding images within your theme can be an important part of creating and/or modifying themes.

As mentioned, there are three main areas for images within Moodle, core, plugins, and themes. Obviously we won't be overriding theme images as we are in a theme and have full control over that already which just leaves core and plugin images that you may want to override.

Within your theme create the following two directories:
; /pix_core/ : This is where your images to override core images will need to be.
; /pix_plugins/ : This is where images to override plugins will need to be.

Next, copy the images that you wish to override into either the pix_core or pix_plugins directory. You need to replicate the directory structure that the images are located in.

The following two examples illustrate how this works for both core and plugin images.

===Overriding core images===
For this example I am going to override the following two images:
# '''moodle/pix/help.gif''' This image is used for all help image icons and is shown throughout Moodle.
# '''moodle/pix/i/info.gif''' This image is used in several places, most notably the front page if the combo list is being displayed.

So first up help.gif. This is the most basic example of overriding an image. Because the image is directly within Moodle's pix directory we can simply place our new help image into our themes pix_core directory. There's nothing more to it!

The second example if not really any more difficult. Because the image is located within the subdirectory '''i''' we must create a sub directory within our pix_core directory into which we will copy our new help image. That is, the image ends up at '''/pix_core/i/info.png''' inside your theme folder. And again done!

You should also note that, as with any other image in Moodle, the extension doesn't matter. If you want to replace help.gif with a help.png you can just put the png into the correct directory. As long as the filename is the same Moodle will find it.

===Overriding plugin images===
This is a little bit more difficult than overriding core images, but not too much so. For this example, let's say I want to override the following two plugin images:
# '''moodle/mod/forum/icon.gif''' This is the icon that is used everywhere for the forum.
# '''moodle/blocks/customblock/activate.png''' This is an icon in a custom block I have installed.

Just as with core images, we need to put the image in the correct directory structure. In this case it is going to be within our theme's '''pix_plugins''' directory.
The correct path must use the plugin type [[Frankenstyle]] prefix and the plugin name.

For the examples above the paths to override the plugin images will be:
# '''pix_plugins/mod/forum/'''
# '''pix_plugins/block/customblock/'''

When looking for an overriding image the following path is used.

# theme (static)
# themename => mytheme
# area => pix_plugins for plugin images, pix_core for core images, pix for theme images.
# plugin type => booktool for the book tool sub plugin for example.
# plugin name => print for the name of the sub plugin.
# file name => book for the name of the image.

It then searches for the image with the following extensions gif, png, jpg, jpeg in that order.

So you end up with:
<code>
/theme/themename/area/plugintype/pluginname/filename.gif
</code>

==See also==

* [[Plugins]]
* [http://youtu.be/g_9VM9OMs3Y Adding Images to your Theme] MoodleBites video on YouTube

Using Moodle forum discussions:
* [http://moodle.org/mod/forum/discuss.php?d=151581 Using images within your themes (and the silk icon theme)]
* [http://moodle.org/mod/forum/discuss.php?d=151581#p689883 choosing images based on the users current language]
* [http://moodle.org/mod/forum/discuss.php?d=157935&parent=691903 how to add a category(categorias) img-bullet]

Access API

2016-11-03T10:37:55Z

Demsley: /* isguestuser(), isloggedin() and is_siteadmin() */

{{Moodle_2.2}}The Access API gives you functions so you can determine what the current user is allowed to do. It also allows modules to extend Moodle with new capabilities.

==Overview==

Moodle is using a role based access control model. Most entities in Moodle (system, users, course categories, courses, modules and blocks) are represented by contexts that are arranged in a tree like hierarchy called context tree. Role is a set of capability definitions, each capability usually represents an ability of user to do something. Roles are defined at the top most system context level. Role definitions can be overridden at lower context levels. User access control is calculated from the definitions of roles assigned to users.

All users that did not log-in yet automatically get the default role defined in $CFG->notloggedinroleid, it is not possible to assign any other role to this non-existent user id. There is one special guest user account that is used when user logs in using the guest login button or when guest autologin is enabled. Again you can not assign any roles to the guest account directly, this account gets the $CFG->guestroleid automatically. All other authenticated users get the default user role specified in $CFG->defaultuserroleid and in the frontpage context the role specified in $CFG->defaultfrontpageroleid.

==How to define new capabilities in plugins==

Capabilities are defined by $capabilities array defined in db/access.php files. The name of the capability consists of "plugintype/pluginname:capabilityname".

For example:
<code php>
$capabilities = array(
'mod/folder:managefiles' => array(
'riskbitmask' => RISK_SPAM,
'captype' => 'write',
'contextlevel' => CONTEXT_MODULE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW
)
),
);
</code>

Where the meaning of array keys is:
* riskbitmask - associated risks. These are explained on [[Hardening new Roles system]].
* captype - ''read'' or ''write'' capability type, for security reasons system prevents all write capabilities for guest account and not-logged-in users
* contextlevel - specified as context level constant. Declares the typical context level where this capability is checked. It is the lowest level where this capability can be tweaked (overridden) via the permissions UI.
* archetypes - specifies defaults for roles with standard archetypes, this is used in installs, upgrades and when resetting roles (it is recommended to use only CAP_ALLOW here). Archetypes are defined in mdl_role table. See also [[Role archetypes]].
* clonepermissionsfrom - when you are adding a new capability, you can tell Moodle to copy the permissions for each role from the current settings for another capabilty. This may give better defaults than just using archetypes for administrators who have heavily customised their roles configuration. The full syntax is: <tt>'clonepermissionsfrom' => 'moodle/quiz:attempt',</tt>
* ''In releases before May 2012 clonepermissionsfrom works only inside individual plugins or only in core, in later releases plugins may also clone permissions from core, success of other cloning operations depends on upgrade order.''

It is necessary to bump up plugin version number after any change in db/access.php, so that the upgrade scripts can make the necessary changes to the database. To run the upgrade scripts, log in to Moodle as administrator, navigate to the site home page, and follow the instructions. (If you need to test the upgrade script without changing the plugin version, it is also possible to set back the version number in the mdl_block or mdl_modules table in the database.)

The capability names are defined in plugin language files, the name of the string consists of "pluginname:capabilityname", in the example above it would be:
<code php>
$string['folder:managefiles'] = 'Manage files in folder module';
</code>

==Useful functions and classes==

===Context fetching===

In plugins context instances are usually only instantiated because they are instantiated and deleted automatically by the system.

Fetching by object id:
<code php>
$systemcontext = context_system::instance();
$usercontext = context_user::instance($user->id);
$categorycontext = context_coursecat::instance($category->id);
$coursecontext = context_course::instance($course->id);
$contextmodule = context_module::instance($cm->id);
</code>

Fetching by context id:
<code php>
$context = context::instance_by_id($contextid);
</code>

Notes:
* by default exception is thrown if context can not be created
* deleted users do not have contexts any more

There are multiple deprecated context related functions since 2.2, it is not necessary to replace them immediately. The following two functions are equivalent to the context fetching examples above:
<code php>
function get_context_instance($contextlevel, $instance = 0, $strictness = IGNORE_MISSING)
function get_context_instance_by_id($id, $strictness = IGNORE_MISSING)
</code>

===Determining that a user has a given capability===

When implementing access control always ask "Does the user have capability to do something?". It is incorrect to ask "Does the user have a role somewhere?".

====has_capability()====
has_capability() is the most important function:
<code php>
function has_capability($capability, context $context, $user = null, $doanything = true)
</code>

Check whether a user has a particular capability in a given context. For example:
<code php>
$context = context_module::instance($cm->id);
has_capability('mod/folder:managefiles', $context)
</code>

By default checks the capabilities of the current user, but you can pass a different userid. By default will return true for admin users, it is not recommended to use false here.

====require_capability()====
Function require_capability() is very similar, it is throwing access control exception if user does not have the capability.

<code php>
function require_capability($capability, context $context, $userid = null, $doanything = true, $errormessage = 'nopermissions', $stringfile = '') {
</code>

===Enrolment functions===

See [[Enrolment API]].

===Other related functions===

<code php>
function require_login($courseorid = NULL, $autologinguest = true, $cm = NULL, $setwantsurltome = true, $preventredirect = false)
function require_course_login($courseorid, $autologinguest = true, $cm = NULL, $setwantsurltome = true, $preventredirect = false)
function get_users_by_capability(context $context, $capability, $fields = '', $sort = '', $limitfrom = '', $limitnum = '',
$groups = '', $exceptions = '', $doanything_ignored = null, $view_ignored = null, $useviewallgroups = false)
function isguestuser($user = null)
function isloggedin()
function is_siteadmin($user_or_id = null)
function is_guest(context $context, $user = null)
function is_viewing(context $context, $user = null, $withcapability = '')
</code>

====require_login()====

Each plugin script should include require_login() or require_course_login() after setting up PAGE->url.

This function does following:
* it verifies that user is logged in before accessing any course or activities (not-logged-in users can not enter any courses).
* user is logged in as gu
* verify access to hidden courses and activities
* verify experimental groupmembersonly access
* verify that user is either enrolled or has capability 'moodle/course:view' or some enrol plugin gives them temporary guest access
* logs access to courses

====require_course_login()====

This function is supposed to be used only in activities that want to allow read access to content on the frontpage without logging-in. For example view resource files, reading of glossary entries, etc.

====isguestuser(), isloggedin() and is_siteadmin()====

These function were previously needed for limiting of access of special accounts. It is usually not necessary any more, because any '''write''' or '''risky''' capabilities are now automatically prevented in has_capability().

It is strongly discouraged to use is_siteadmin() in activity modules, please use standard capabilities and enrolment status instead.

====is_guest(), is_viewing() and is_enrolled()====

In order to access course data one of these functions must return true for user:
* is_enrolled() - user has active record in user_enrolments table
* is_viewing() - user has 'moodle/course:view' capability (may access course, but is not considered to be participant)
* is_guest() - user was given temporary guest access by some enrolment plugin

====get_users_by_capability()====

This method returns list of users with given capability, it ignores enrolment status and should be used only above the course context.

==See also==
* [[Core APIs]]
* [[Roles]]
* [[Role archetypes]]
* [[Hardening new Roles system]]
* [[Roles and modules]]
* [[NEWMODULE Adding capabilities]]
* [[New permissions evaluation in 2.0]]

[[Category:API]]

lib/formslib.php Form Definition

2016-01-28T09:48:09Z

Demsley: /* select */

{{Formslib}}
== ''definition()'' ==

The definition of the elements to be included in the form, their 'types' (PARAM_*), helpbuttons included, etc. is all included in a function you must define in your class.

''definition()'' is used to define the elements in the form and '''this definition will be used for validating data submitted as well as for printing the form.''' For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the definition will be accepted as submitted data.

The ''definition()'' should include all elements that are going to be used on form, some elements may be removed or tweaked later in ''definition_after_data()''. Please do not create conditional elements in ''definition()'', the definition() should not directly depend on the submitted data.

Note that the definition function is called when the form class is instantiated. There is no option to (say) manipulate data in the class (that may affect the rendering of the form) between instantiating the form and calling any other methods.

<code php>
require_once("$CFG->libdir/formslib.php");

class simplehtml_form extends moodleform {

function definition() {
global $CFG;

$mform = $this->_form; // Don't forget the underscore!

$mform->addElement()... // Add elements to your form
...
} // Close the function
} // Close the class
</code>
===Passing parameters to the Form===

The constructor for ''moodleform'' allows a number of parameters including one (''$customdata'') to permit an array of arbitrary data to be passed to your form.

For example, you can pass the data "$email" and "$username" to the Form's class for use inside (say) the definition.
<code php>
...
$mform_simple = new simplehtml_form( null, array('email'=>$email, 'username'=>$username ) );
...
</code>
(the first parameter is $action, ''null'' will case the form action to be determined automatically)

Secondly, inside the form definition you can use those parameters to set the default values to some of the form's fields
<code php>
...
$mform->addElement('text', 'email', get_string('email'), 'maxlength="100" size="25" ');
$mform->setType('email', PARAM_NOTAGS);
$mform->addRule('email', get_string('missingemail'), 'required', null, 'server');
// Set default value by using a passed parameter
$mform->setDefault('email',$this->_customdata['email']);
...
</code>

==Use Fieldsets to group Form Elements==

You use code like this to open a fieldset with a ''legend''. <br />
('''Note''': Some themes turn off legends on admin setting pages by using CSS: <nowiki>#adminsettings legend {display:none;}</nowiki>.)

<code php>
$mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));
</code>

You can't yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.

{{Moodle 2.5}}
Since Moodle 2.5 fieldsets without any required fields are collapsed by default. To display these fieldsets on page load, use:
<code php>
$mform->setExpanded('foo')
</code>

You close a fieldset with moodle_form's closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :

<code php>
$mform->closeHeaderBefore('buttonar');
</code>

==addElement==

Use the addElement method to add an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.

Some examples are below :
=== button ===

<code php>
$mform->addElement('button', 'intro', get_string("buttonlabel"));
</code>

A button element. If you want a submit or cancel button see 'submit' element.

=== checkbox ===

<code php>
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));
</code>

This is a simple checkbox. The third parameter for this element is the label to display on the left side of the form. You can also supply a string as a fourth parameter to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.

You can have a 5th parameter $attributes, as on other elements.

'''BEWARE:''' Unchecked checkboxes return nothing at all (as if they didn't exist). This can surprise the unwary. You may wish to use advcheckbox instead, which does return a value when not checked. 'Advcheckbox' eliminates this problem.

==== advcheckbox ====
<code php>
$mform->addElement('advcheckbox', 'ratingtime', get_string('ratingtime', 'forum'), 'Label displayed after checkbox', array('group' => 1), array(0, 1));
</code>

Similar to the checkbox above, but with some important improvements:

# The (optional) 5th parameter is a normal $attributes array, normally used to set HTML attributes for the <input> element. However, a special value of 'group' can be given, which will add a class name to the element, and enable its grouping for a [[lib/formslib.php_add_checkbox_controller|checkbox controller]]
#The (optional) 6th parameter is an array of values that will be associated with the checked/unchecked state of the checkbox. With a normal checkbox you cannot choose that value, and in fact an unchecked checkbox will not even be sent with the form data.
#It returns a 0 value when unchecked. Compare with the ordinary checkbox which does not return anything at all.

=== choosecoursefile ===
{{Moodle 1.9}}
<code php>
$mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));
</code>

Choose a file from the course files area. The fourth option is a list of options for the element.

'''Note: This has been superceded by [[#filepicker|filepicker]] in Moodle 2.'''

<code php>
array('courseid' =>null, //if it is null (default then use global $COURSE
'height' =>500, // height of the popup window
'width' =>750, // width of the popup window
'options' =>'none'); //options string for the pop up window
//eg. 'menubar=0,location=0,scrollbars,resizable'
</code>

You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like
<code php>array('maxlength' => 255, 'size' => 48)</code>
to control the maxlength / size of the text box (note size will default to 48 if not specified)

Finally, as this element is a group containing two elements (button + value), you can add validation rules by using the '''addGroupRule()''' method in this (complex) way:

<code php>$mform->addGroupRule('elementname', array('value' => array(array(list, of, rule, params, but, fieldname))));</code>

Where: '''"elementname"''' is the name of the choosecoursefile group element, '''"value"''' is the name of the text field within the group and the '''"list, of, addrule, params, but, fieldname"''' is exactly that, the list of fields in the normal addRule() function but ommiting the first one, the fieldname.

For example, the [http://cvs.moodle.org/moodle/mod/resource/type/file/resource.class.php?view=markup file/url resource type], uses one "choosecoursefile" element, and it controls the maximum length of the field (255) with this use of addGroupRule():

<code php>$mform->addGroupRule('reference', array('value' => array(array(get_string('maximumchars', '', 255), 'maxlength', 255, 'client'))));</code>

=== date_selector ===

<code php>
$mform->addElement('date_selector', 'assesstimefinish', get_string('to'));
</code>

This is a date selector. You can select a Day, Month and Year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :

<code php>
array(
'startyear' => 1970,
'stopyear' => 2020,
'timezone' => 99,
'optional' => false
);
</code>

You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.

=== date_time_selector ===

<code php>
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));
</code>

This is a group of select boxes to select a date (Day Month and Year) and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form->get_data(); the fourth param here is an array of options. The defaults for the options are:

<code php>
array(
'startyear' => 1970,
'stopyear' => 2020,
'timezone' => 99,
'step' => 5
);
</code>

You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.

===duration===
{{Moodle 2.0}}

<code php>
$mform->addElement('duration', 'timelimit', get_string('timelimit', 'quiz'));
</code>
This field type lets the user input an interval of time. It comprises a text field, where you can type a number, and a dropdown for selecting a unit (days, hours, minutes or seconds). When submitted the value is converted to a number of seconds.

You can add a fourth parameter to give options. At the moment the only option supported is here is an array of options. The defaults for the options is:
<code php>array('optional' => true)</code>

You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like
<code php>array('size' => 5)</code>
to control the size of the text box.

=== editor ===

This replaces the old htmleditor field type. It allows the user to enter rich text content in a variety of formats.

<code php>
$mform->addElement('editor', 'fieldname', get_string('labeltext', 'langfile'));
$mform->setType('fieldname', PARAM_RAW);
</code>

NOTE: It won't work properly without the setType() as shown.

If you would like to let the user use the filepicker to upload images etc. that are used in the content, then see [[Using_the_File_API_in_Moodle_forms]].

You can supply a fourth param to htmleditor of an array of options that are mostly related to file handling:

<code php>
array(
'subdirs'=>0,
'maxbytes'=>0,
'maxfiles'=>0,
'changeformat'=>0,
'context'=>null,
'noclean'=>0,
'trusttext'=>0,
'enable_filemanagement' => true);
</code>

The option 'enable_filemanagement' will display the file management button on true and remove it on false.

To save the data if you don't care about files:
<code php>
$formdata = $mform->get_data();
$text = $formdata->fieldname['text'];
$format = $formdata->fieldname['format'];
</code>

Note: Because the text editor might be "Atto" (depending on user preferences) and Atto has an "autosave" feature - it requires that the combination of $PAGE->url and this elementid are unique. If not, the autosaved text for a different form may be restored into this form.

=== file ===

File upload input box with browse button. In the form definition type

<code php>
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
</code>

after form submission and validation use

<code php>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
...
}
</code>

If there is no requirement to save the file, you can read the file contents directly into a string as follows...

<code php>
$mform->get_file_content('attachment');
</code>

If you need advanced settings such as required file, different max upload size or name of uploaded file

<code php>
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
$mform->addRule('attachment', null, 'required');

</code>

<code php>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
$newfilename = $mform->get_new_filename();
...
}
</code>

When porting old code it is also possible to use the upload manager directly for processing of uploaded files.

Please note that if using set_upload_manager() it must be before addElement('file',..).

{{Moodle 2.0}}
File uploading was rewritten in 2.0. Please see inline docs for now. This page will be updated when the new API stabilises.

===filepicker===
{{Moodle 2.0}}
General replacement of ''file'' element.

<code php>
$mform->addElement('filepicker', 'userfile', get_string('file'), null, array('maxbytes' => $maxbytes, 'accepted_types' => '*'));
</code>
See also [[Using the File API in Moodle forms]]

=== hidden ===
<code php>
$mform->addElement('hidden', 'reply', 'yes');
</code>

A hidden element. Set the element name (in this case '''reply''') to the stated value (in this case '''yes''').

=== html ===
You can add arbitrary HTML to your Moodle form:

<code php>
$mform->addElement('html', '<div class="qheader">');
</code>

See [http://moodle.org/mod/forum/discuss.php?d=126935 "Question: Can I put a moodleform inside a table td?"] for a concrete example.

=== htmleditor & format ===

These elements are now deprecated. Please use the [[#editor|editor]] field type instead.

===modgrade===
<pre>
$mform->addElement('modgrade', 'scale', get_string('grade'), false);
</pre>
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.

A helpbutton is automatically added.

===modvisible===
<pre>
$mform->addElement('modvisible', 'visible', get_string('visible'));
</pre>
This is a custom element for selecting a grade visibility in an activity mod update form.

===password===
<pre>
$mform->addElement('password', 'password', get_string('label'), $attributes);
</pre>

A password element. Fourth param is an array or string of attributes.

===passwordunmask===
{{Moodle 1.9}}
<pre>
$mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);
</pre>

A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.

=== radio ===
{{Moodle 2.3}}
<code php>
$radioarray=array();
$radioarray[] = $mform->createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);
$radioarray[] = $mform->createElement('radio', 'yesno', '', get_string('no'), 0, $attributes);
$mform->addGroup($radioarray, 'radioar', '', array(' '), false);
</code>

Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it's own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.

It is possible to add help to individual radio buttons but this requires a custom template to be defined for the group elements. See MDL-15571.

Since 2.3 it cannot be statically called anymore, so we need to call createElement from $mform reference.

==== setDefault ====

To set the default for a radio button group as above use the following :

<code php>
$mform->setDefault('yesno', 0);
</code>

This would make the default 'no'.

===select===
<pre>
$mform->addElement('select', 'type', get_string('forumtype', 'forum'), $FORUM_TYPES, $attributes);
</pre>

The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.

It is also possible to create a select with certain options disabled, using [http://stackoverflow.com/questions/2138089/how-can-i-use-quickform-to-add-disabled-select-options/2150275#2150275 this technique].

You can set an 'onchange' attribute when adding or creating the select element:

$form->addElement('select', 'iselTest', 'Test Select:', $arrayOfOptions, array('onchange' => 'javascript:myFunctionToDoSomething();');

====multi-select====
<pre>
$select = $mform->addElement('select', 'colors', get_string('colors'), array('red', 'blue', 'green'), $attributes);
$select->setMultiple(true);
</pre>

=====setSelected=====

To set the default selected item in a select element, you can use the 'setSelected' method. The 'setSelected' can either get a value or an array of values.

<pre>
$options = array(
'ff0000' => 'Red',
'00ff00' => 'Green',
'0000ff' => 'Blue'
);
$select = $mform->addElement('select', 'colors', get_string('colors'), $options);
// This will select the colour blue.
$select->setSelected('0000ff');
</pre>

Or for multpi-selection:
<pre>
$skillsarray = array(
'val1' => 'Skill A',
'val2' => 'Skill B',
'val3' => 'Skill C'
);
$mform->addElement('select', 'md_skills', get_string('skills', 'metadata'), $skillsarray);
$mform->getElement('md_skills')->setMultiple(true);
// This will select the skills A and B.
$mform->getElement('md_skills')->setSelected(array('val1', 'val2'));
</pre>

However you probably don't want to do this. Instead you probably want to use setDefault, or set it using the form's setData method.

===selectyesno===
<pre>
$mform->addElement('selectyesno', 'maxbytes', get_string('maxattachmentsize', 'forum'));
</pre>

If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.

===selectwithlink===
<pre>
$options = array();
$mform->addElement('selectwithlink', 'scaleid', get_string('scale'), $options, null,
array('link' => $CFG->wwwroot.'/grade/edit/scale/edit.php?courseid='.$COURSE->id, 'label' => get_string('scalescustomcreate')));
</pre>
select type element with options containing link
===static===
<pre>
$mform->addElement('static', 'description', get_string('description', 'exercise'),
get_string('descriptionofexercise', 'exercise', $COURSE->students));
</pre>

This is a static element. It should be used with care if it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.

===submit, reset and cancel===

<pre>
//normally you use add_action_buttons instead of this code
$buttonarray=array();
$buttonarray[] = &$mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] = &$mform->createElement('reset', 'resetbutton', get_string('revert'));
$buttonarray[] = &$mform->createElement('cancel');
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
$mform->closeHeaderBefore('buttonar');
</pre>

A 'Submit' type element is a submit type form element which will submit the form. A 'Reset' will not submit the form but will reset any changes the user has made to form contents. A 'Cancel' element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.

You should name your submit and reset buttons 'submitbutton' and 'resetbutton' or something similar (not 'submit' and 'reset'). This avoids problems in JavaScript of collisions between form element names and names of JavaScript methods of the form object.

====add_action_buttons($cancel = true, $submitlabel=null);====

You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges'). Note the '''$this''' not '''$mform'''

<pre>
$this->add_action_buttons();
</pre>

===text===

<pre>
$mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);
</pre>
For a simple text element. Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :
<pre>
$attributes='size="20"';
$attributes=array('size'=>'20');
</pre>

Generally you are encouraged to use CSS instead of using attributes for styling.

A format element can be used as a format select box. It will be non-selectable if you're using an html editor.

The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.

===textarea===

<pre>
$mform->addElement('textarea', 'introduction', get_string("introtext", "survey"), 'wrap="virtual" rows="20" cols="50"');
</pre>

A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.

===recaptcha===
{{Moodle 1.9}}
<pre>
$mform->addElement('recaptcha', 'recaptcha_field_name', $attributes);
</pre>

Use this recaptcha element to reduce the spam risk in your forms. Third element here is a string or array of attributes. Take care to get an API key from http://recaptcha.net/api/getkey before using this element.

To check whether recaptcha is enabled at site level use:
<pre>
if (!empty($CFG->recaptchapublickey) && !empty($CFG->recaptchaprivatekey)) {
//recaptcha is enabled
}
</pre>

===tags===
{{Moodle 2.0}}

<pre>
$mform->addElement('tags', 'field_name', $lable, $options, $attributes);
</pre>

Used for editing a list of tags, for example on a blog post.

There is only one option available, 'display', which should be set to one of the contstants MoodleQuickForm_tags::ONLYOFFICIAL, NOOFFICIAL or DEFAULTUI. This controls whether the official tags are listed for easy selection, or a text area where arbitrary tags may be typed, or both. The default is both.

The value should be set/returned as an array of tags.

===grading===
<code php>
$mform->addElement('grading', 'advancedgrading', get_string('grade').':', array('gradinginstance' => $gradinginstance));
</code>

Custom element for advanced grading plugins.

When adding the 'grading' element to the form, developer must pass an object of class gradingform_instance as $attributes['gradinginstance']. Otherwise an exception will be thrown.

===questioncategory===
<code php>
$mform->addElement('questioncategory', 'category', get_string('category', 'question'),
array('contexts'=>$contexts, 'top'=>true, 'currentcat'=>$currentcat, 'nochildrenof'=>$currentcat));
</code>
Creates a drop down element to select a question category.

Options are:
'''contexts''' - (required) context in which question appears
'''currentcat''' - (optional) course category
'''top''' - (optional) if true will put top categories on top
'''nochildrenof''' - (optional) Format categories into an indented list reflecting the tree structure

==addGroup==

A 'group' in formslib is just a group of elements that will have a label and will be included on one line.

For example typical code to include a submit and cancel button on the same line :

<pre>
$buttonarray=array();
$buttonarray[] =& $mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] =& $mform->createElement('submit', 'cancel', get_string('cancel'));
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
</pre>

You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).

Here's a bad example (don't do this for real, use the 'optional' => true option of the date element): putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name 'availablefromgroup' but it doesn't disable the controlling element the 'availablefromenabled' checkbox:

<pre>
$availablefromgroup=array();
$availablefromgroup[] =& $mform->createElement('date_selector', 'availablefrom', '');
$availablefromgroup[] =& $mform->createElement('checkbox', 'availablefromenabled', '', get_string('enable'));
$mform->addGroup($availablefromgroup, 'availablefromgroup', get_string('availablefromdate', 'data'), ' ', false);
$mform->disabledIf('availablefromgroup', 'availablefromenabled');
</pre>

* If you want to put a group inside another array so that you can repeat items, use createElement instead of addGroup:

<pre>
$group = $mform->createElement('group', 'groupname', get_string('label'), $groupitems);
</pre>

* By default, groups modify the names of elements inside them by appending a number. This is often unhelpful, for example if you want to use disabledIf on the element. To prevent this behaviour, set the last parameter to false when creating a group.:

<pre>
$group = $mform->createElement('group', 'groupname', get_string('label'), $groupitems, null, false);
</pre>

==addRule==
<pre>
$mform->addRule('elementname', get_string('error'), 'rule type', 'extraruledata', 'server'(default), false, false);
</pre>

The first param(element) is an element name and second(message) is the error message that will be displayed to the user.
The third parameter(type) is the type of rule. The fourth param(format) is used for extra data needed with some rules such as minlength and regex. The fifth parameter(validation) validates input data on server or client side, if validation is done on client side then it will be checked on the server side as well.

<pre>
* @param string $element Form element name
* @param string $message Message to display for invalid data
* @param string $type Rule type, use getRegisteredRules() to get types
* @param string $format (optional)Required for extra rule data
* @param string $validation (optional)Where to perform validation: "server", "client"
* @param boolean $reset Client-side validation: reset the form element to its original value if there is an error?
* @param boolean $force Force the rule to be applied, even if the target form element does not exist
</pre>

'''Common Rule Types'''
* required
* maxlength
* minlength
* rangelength
* email
* regex
* lettersonly
* alphanumeric
* numeric
* nopunctuation
* nonzero
* callback
* compare

===Server side and Client side===
In case you use the ''Client side'' validation option, you can mainly check for an empty or not input field. unless you write some ''Client side'' code which will probably be JavaScript functions to verify the data inside the input fields before it is submitted to the server. It could save some time if those functions are short, simple and quick to compute.
In case you need a more complex validation checks which relay on Moodle's internal PHP libraries (or other/external PHP libraries) you better use the ''Server side'' validation checks. Where you can query the DB, write complex PHP validation functions and much much more, that are not available (easily) when using JavaScript on the client's side.

==setHelpButton==
{{Moodle 1.9}}

<pre>
$mform->setHelpButton('lessondefault', array('lessondefault', get_string('lessondefault', 'lesson'), 'lesson'));
</pre>
First param is an elementname and the second param is an array of params that are passed to helpbutton in weblib.php. Params are :

<pre>
* @param string $page The keyword that defines a help page
* @param string $title The title of links, rollover tips, alt tags etc
* 'Help with' (or the language equivalent) will be prefixed and '...' will be stripped.
* @param string $module Which module is the page defined in
* @param mixed $image Use a help image for the link? (true/false/"both")
* @param boolean $linktext If true, display the title next to the help icon.
* @param string $text If defined then this text is used in the page, and
* the $page variable is ignored.
* @param boolean $return If true then the output is returned as a string, if false it is printed to the current page.
* @param string $imagetext The full text for the helpbutton icon. If empty use default help.gif
</pre>
Make sure you don't set boolean $return to false.

You need to do use this method after addElement();

==addHelpButton==
{{Moodle 2.0}}

<code php>
$mform->addHelpButton('api_key_field', 'api_key', 'block_extsearch');
</code>

In Moodle 2.0 the "setHelpButton" method has been deprecated in favor of the "addHelpButton" method, which has a simplified interface and uses $OUTPUT->help_icon() on the back end. The following parameters are expected:

<code php>
/**
* @param $elementname The name of the form element to add the help button for
* @param $identifier The identifier for the help string and its title (see below)
* @param $component The component name to look for the help string in
*/
</code>
Unlike in Moodle 1.9, it is no longer necessary to put your help pages in separate HTML files. Instead, the function looks for two strings:

# get_string($identifier, $component) // The title of the help page
# get_string("{$identifier}_help", $component) // The content of the help page

So you will need to have '''$identifier''' and '''{$identifier}_help''' defined in order for the help button to be created properly. For example the multiple choice question editing form has a button for shuffling the answers.
<code php>
$mform->addHelpButton('shuffleanswers', 'shuffleanswers', 'qtype_multichoice');
</code>
and so the language file includes the strings
<code php>
$string['shuffleanswers'] = 'Shuffle the choices?';
$string['shuffleanswers_help'] = 'If enabled,.....';
</code>
You can also add the language string like
<code php>
$string['shuffleanswers_link'] = 'question/shuffleanswers';
</code>
to add a link to more help on Moodle docs. See [[String_API]] for more information about help icons.

==setDefault==

<pre>
$mform->addElement('select', 'grade', get_string('gradeforsubmission', 'exercise'), $grades);
$mform->setHelpButton('grade', array('grade', get_string('gradeforsubmission', 'exercise'), 'exercise'));
$mform->setDefault('grade', 100);
</pre>

Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an 'add' rather than 'update' function.

<pre>
$mform->addElement('editor', 'desc', get_string('description'));
$mform->setDefault('desc', array('text'=>$defaulttext));
</pre>

Note that when setting the default for an editor element you must use an array to define the default "text" value as shown above.

==disabledIf==

For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.

You can use $mform->disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value='1')

* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you've used as the second argument in addElement or addGroup.
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you're adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.
* $condition will be 'notchecked', 'checked', 'noitemselected', 'eq', 'in' or, if it is anything else, we test for 'neq'.
** If $condition is 'eq' or 'neq' then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js
** If $condition is 'checked' or 'notchecked' then we check to see if a checkbox is checked or not.
** If $condition is 'in' then we check to see if a selected item is in the given list or not. (This was introduced in Moodle 2.7+)
** If $condition is 'noitemselected' then we check to see whether nothing is selected in a dropdown list.

Examples:
// Disable my control unless a checkbox is checked.
$mform->disabledIf('mycontrol', 'somecheckbox');

// Disable my control if a checkbox '''is''' checked.
$mform->disabledIf('mycontrol', 'somecheckbox', 'checked');

// Disable my control when a dropdown has value 42.
$mform->disabledIf('mycontrol', 'someselect', 'eq', 42);

// Disable my control unless a dropdown has value 42.
$mform->disabledIf('mycontrol', 'someselect', 'neq', 42);

The possible choices here are in the dependency manager in lib/form/form.js.
===A tricky case===

You need to take care with disabledIf if you plan to use it with groups of checkboxes.

Let's say you have a group of 5 checkboxes and you want to enable a depending item such as a drop down menu only when the first and the last checkboxes are selected.

To fix ideas:

If the selection in the checkboxes group is:

mycheck_01 == 1
mycheck_02 == 0
mycheck_03 == 0
mycheck_04 == 0
mycheck_05 == 1

the depending item must be enabled while ANY OTHER COMBINATION must disable the drop down menu.

The following code will, apparently, fail:
<code php>
$mform->disabledIf('dropdownmenu', 'mycheck_01', 'neq', '1');
$mform->disabledIf('dropdownmenu', 'mycheck_02', 'neq', '0');
$mform->disabledIf('dropdownmenu', 'mycheck_03', 'neq', '0');
$mform->disabledIf('dropdownmenu', 'mycheck_04', 'neq', '0');
$mform->disabledIf('dropdownmenu', 'mycheck_05', 'neq', '1');
</code>

In fact, once you get the drop down menu enabled, you are free to unselect mycheck_01 whilst still having the depending item enabled.
This apparent bug occurs because a non-checked checkbox behaves like a non existing mform element. So the js code will not find the element "mycheck_01" and will not apply the corresponding rule.

A working solution for this kind of issue seems to be:
<code php>
$mform->disabledIf('dropdownmenu', 'mycheck_01', 'notchecked');
$mform->disabledIf('dropdownmenu', 'mycheck_02', 'checked');
$mform->disabledIf('dropdownmenu', 'mycheck_03', 'checked');
$mform->disabledIf('dropdownmenu', 'mycheck_04', 'checked');
$mform->disabledIf('dropdownmenu', 'mycheck_05', 'notchecked');
</code>
To see a failing example as the one described, try the attachments provided in MDL-38975. See also in MDL-38975 for the working solution in action with modifications suggested by Eloy.

==setType==

PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).

===Most Commonly Used PARAM_* Types===

These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.

* PARAM_CLEAN is deprecated and you should try to use a more specific type.
* PARAM_TEXT should be used for cleaning data that is expected to contain multi-lang content. It will strip all html tags. But will still let tags for multilang support through.
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().
* PARAM_INT should be used for integers. PARAM_FLOAT is also available for decimal numbers but is not recommended for user input since it does not work for languages that use , as a decimal separator.
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.

==disable_form_change_checker==

By default, any Moodle form will pop-up an "Are you sure?" alert if you make some changes and then try to leave the page without saving. Occasionally, that is undesirable, in which case you can call

$mform->disable_form_change_checker()

==References==

* [http://www.midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide] by Keith Edmunds of Midnighthax.com
* [http://pear.php.net/manual/en/package.html.html-quickform.php PEAR::HTML_QuickForm manual]

[[Category:Formslib]]
[[Category:Interfaces]]