MoodleDocs - User contributions [en]

Message API

2021-06-26T13:08:35Z

Plemaire: /* Changes in Moodle 3.5 */ very small correction

==What is this document?==

This document describes how to make use of the Moodle Messaging API to send messages to Moodle users.

If you are after a general introduction on using the Moodle Messaging system go to [[:en:Messaging|messaging user documentation]].

If you are looking for details of how the Messaging system's internal structure was implemented, go to [[Messaging 2.0]].

If you are looking for instructions on the implementation of a custom message processor (a component that receives messages sent to a user), go to [[Messaging custom components]].

If you are looking for instructions on sending messages programatically within Moodle then read on...

==Overview==

Moodle components have the ability to send messages to users via the Moodle messaging system. Any type of component, for example a plugin or block, can register as a message producer then send messages to users.

==File locations==

The Message API code is contained within lib/messagelib.php and is automatically included for you during page setup.

==Functions==

message_send() is the primary point of contact for the message API. Call it to send a message to a user. You can find a full description of the arguments that must be supplied at (link to phpdocs). There is also an example below.

==Message popup==
{{Moodle_2.9}}
A Javascript popup can be displayed through a link to invite a user to message another. In order to use this feature, you need to require the Javascript libraries using ''message_messenger_requirejs()'' and create a link with the attributes returned by ''message_messenger_sendmessage_link_params()''. More in the examples.

==Examples==

===How to register as a message producer===

The messages produced by a message provider is defined in the /db/messages.php file of a component. Below is code from the quiz module's messages.php file, shown as an example.
<code php>
defined('MOODLE_INTERNAL') || die();
$messageproviders = array (
// Notify teacher that a student has submitted a quiz attempt
'submission' => array (
'capability' => 'mod/quiz:emailnotifysubmission'
),
// Confirm a student's quiz attempt
'confirmation' => array (
'capability' => 'mod/quiz:emailconfirmsubmission'
)
);
</code>

The quiz can send two kinds of messages, quiz "submission" and "confirmation" notifications. Each message type is only available to users with the appropriate capability. Please note that the capability is checked at the system level context. Users who have this capability will have this message listed in their messaging preferences. You can omit the capability section if your message should be visible for all users. For example forum post notifications are available to all users.

<code php>
$messageproviders = array (
// Ordinary single forum posts
'posts' => array (
)
);
</code>

When displaying your message types in a user's messaging preferences it will use a string from your component's language file called "messageprovider:messagename". For example here are the relevant strings from the quiz's language file.
<code php>
$string['messageprovider:confirmation'] = 'Confirmation of your own quiz submissions';
$string['messageprovider:submission'] = 'Notification of quiz submissions';
</code>

Once your messages.php is complete you need to increase the version number of your component in its version.php. That will cause Moodle to check messages.php looking for new or changed message definitions. Log in as an admin and go to /admin/index.php (the Notifications page) to start the upgrade process.
===Setting defaults===
The default processor can be set using an element of the array
e.g.
<code php>
'mynotification' => [
'defaults' => [
'popup' => MESSAGE_PERMITTED + MESSAGE_DEFAULT_LOGGEDIN + MESSAGE_DEFAULT_LOGGEDOFF,
'email' => MESSAGE_PERMITTED
],
],
</code>
With that setting email will be permitted but disabled for each user by default. It can be turned on by each user through the preferences/notification preferences options (/message/notificationpreferences.php?userid=X)
The possible values are recorded in the lib.php file of messaging
<code php>
/**
* Define contants for messaging default settings population. For unambiguity of
* plugin developer intentions we use 4-bit value (LSB numbering):
* bit 0 - whether to send message when user is loggedin (MESSAGE_DEFAULT_LOGGEDIN)
* bit 1 - whether to send message when user is loggedoff (MESSAGE_DEFAULT_LOGGEDOFF)
* bit 2..3 - messaging permission (MESSAGE_DISALLOWED|MESSAGE_PERMITTED|MESSAGE_FORCED)
*
* MESSAGE_PERMITTED_MASK contains the mask we use to distinguish permission setting
*/
</code>
Note that if you change the values in message.php and then upgrade the plugin the values will not automatically be changed in the config_plugins table where they are stored.

===How to send a message===
{{Moodle_2.9}}
Here is example code showing you how to actually send a notification message. The example shows the construction of a object with specific properties, which is then passed to the message_send() function that uses the information to send a message.
<code php>
$message = new \core\message\message();
$message->component = 'mod_yourmodule'; // Your plugin's name
$message->name = 'mynotification'; // Your notification name from message.php
$message->userfrom = core_user::get_noreply_user(); // If the message is 'from' a specific user you can set them here
$message->userto = $user;
$message->subject = 'message subject 1';
$message->fullmessage = 'message body';
$message->fullmessageformat = FORMAT_MARKDOWN;
$message->fullmessagehtml = '<p>message body</p>';
$message->smallmessage = 'small message';
$message->notification = 1; // Because this is a notification generated from Moodle, not a user-to-user message
$message->contexturl = (new \moodle_url('/course/'))->out(false); // A relevant URL for the notification
$message->contexturlname = 'Course list'; // Link title explaining where users get to for the contexturl
$content = array('*' => array('header' => ' test ', 'footer' => ' test ')); // Extra content for specific processor
$message->set_additional_content('email', $content);

// You probably don't need attachments but if you do, here is how to add one
$usercontext = context_user::instance($user->id);
$file = new stdClass;
$file->contextid = $usercontext->id;
$file->component = 'user';
$file->filearea = 'private';
$file->itemid = 0;
$file->filepath = '/';
$file->filename = '1.txt';
$file->source = 'test';

$fs = get_file_storage();
$file = $fs->create_file_from_string($file, 'file1 content');
$message->attachment = $file;

// Actually send the message
$messageid = message_send($message);
</code>

Before 2.9 message data used to be a stdClass object as shown below (This formation of a message will no longer work as of Moodle 3.6. Only a message object will be accepted):-

<code php>
$message = new stdClass();
$message->component = 'mod_quiz'; //your component name
$message->name = 'submission'; //this is the message name from messages.php
$message->userfrom = $USER;
$message->userto = $touser;
$message->subject = $subject;
$message->fullmessage = $message;
$message->fullmessageformat = FORMAT_PLAIN;
$message->fullmessagehtml = '';
$message->smallmessage = '';
$message->notification = 1; //this is only set to 0 for personal messages between users
message_send($message);
</code>

===How to set-up the message popup===

Here is example code showing you how to set-up the Javascript popup link.
<code php>
require_once('message/lib.php');
$userid = 2;
$userto = $DB->get_record('user', array('id' => $userid));

message_messenger_requirejs();
$url = new moodle_url('message/index.php', array('id' => $userto->id));
$attributes = message_messenger_sendmessage_link_params($userto);
echo html_writer::link($url, 'Send a message', $attributes);
</code>

==Changes in Moodle 3.5==
{{Moodle_3.5}}

In Moodle 3.5, there were some moderately big changes. The only docs I have been able to find about them are in [https://github.com/moodle/moodle/blob/33a388eff737c049786ee42d7430db549568471c/message/upgrade.txt#L56 upgrade.txt] file. However, that is the details, here is an overview:

The main message_send() API to send a message has not changed, so if your code is just sending messages, you don't need to do anything.

Similarly, message_output plugins don't need to change, so no worries there.

If you are doing things with messages, then you need to understand how the internals have changed.

The database tables have changed. Messages from Moodle components to a user (e.g. mod_quiz), telling them that something has happened (e.g. an attempt was submitted) have always been 'Notifications'. In the past, this was just a column in the mdl_message table. Now, messages and notifications are stored in completely separate tables. Notifications are in mdl_notifications. The strucutre of this table is very similar to the old mdl_message table which is now not used at all. Messages are in mdl_messages, and related tables, that now exist to support group messaging. Those tables join together like this:

<code sql>
SELECT *

FROM mdl_messages m
JOIN mdl_message_conversations con ON con.id = m.conversationid
JOIN mdl_message_conversation_members mem ON mem.conversationid = con.id
LEFT JOIN mdl_message_user_actions act ON act.userid = mem.userid AND act.messageid = m.id

ORDER BY m.timecreated, m.id, mem.userid, act.id
</code>

==See also==
* [[Core APIs]]

[[Category:API]]
[[Category:Tutorial]]
[[Category:Plugins]]
[[Category:Messaging]]

Output renderers

2020-04-11T18:25:45Z

Plemaire: typographical error

{{Work in progress}}
{{Infobox Project
|name = Output renderers
|state = Implemented
|tracker = MDL-21235
|discussion = n/a
|assignee = [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] + [[User:David Mudrak|David Mudrak]] + feedback and ideas from other developers
}}
{{Moodle 2.0}}

== Goals ==
* stable API
* easy to use
* easy to customise via themes

== Renderers ==

Output renderer is a class with collection of methods that handle rendering of visual aspects of Moodle pages, emails, html export, etc. In Moodle 1.9, general output related functions were located in weblib.php and modules stored rendering code in lib.php, locallib.php, view.php, etc. Output renderer instances are obtained through moodle_page::get_renderer($component, $subtype = null, $target = null) method.

The general renderer class naming convention is:
{theme name}_{plugin type}_{plugin_name}_{subtype}_renderer_{target}

or (if using namespaces)

\{plugin type}_{plugin name}\output\{subtype}_renderer_{target} (standard plugin renderer)

\theme_{theme name}\output\{plugin type}_{plugin name}\{subtype}_renderer_{target} (plugin renderer overridden in a theme)

where theme name prefix, subtype infix and target suffix are optional. Examples of renderer class name are core_renderer, mytheme_core_renderer, mod_workshop_renderer, mod_forum_renderer_cli, \tool_templatelibrary\output\renderer etc.

; Renderer subtype : When get_renderer() is called, $subtype parameter can be provided to obtain a different renderer. Renderer subtypes are used mainly for core subsystems, but it is also possible to use them in modules.

; Renderer targets : In most cases, we are rendering page output for web browsers. Sometimes we need to generate different output for command line scripts, email messages, etc. When get_renderer() is called, $target parameter can be provided to obtain a different renderer. The list of targets will be part of the specification, individual plugins should not invent new rendering targets.

: note that both $subtype and $target works similarly - they just influence the name of the class to be returned by get_renderer(). But there is semantic difference and we will probably have the list of allowed targets limited (defaults to html).

== Overall picture ==

The following UML diagram describes the main classes involved in HTML output rendering and their relationships.

[[Image:uml_output_renderers.png|800px|left]] [[Media:uml_output_renderers.dia|(dia source)]]
<br clear="both" />

=== renderer_base ===

Abstract class every other renderer must extend. Renderer base implements basic methods and support for renderer dispatching.

=== core_renderer ===

Current core_renderer is available through the global $OUTPUT variable. This global should not be used in lower level APIs - only in the main scripts like view.php. When you want to start to print something, you will probably call
echo $OUTPUT->header();
in your view.php or similar script. To print a page footer and terminate your PHP script, you will call
echo $OUTPUT->footer();
die();

Beside these page header and footer related things, core_renderer knows how to display
# boxes and containers - basically <div> elements
# general widgets - headings, single buttons, selection forms, arrows in the breadcrumb navigation, language selection popup, user login info etc.
# error messages, notifications
# blocks

=== method render() and interface renderable ===

Various widgets (headings, buttons etc.) and other content blocks (submissions, forum posts etc.) are represented as classes. In most cases, they will look like a simple object with just some properties and a constructor to set the most common ones. Core renderer implements protected methods to render these widgets. These widget rendering methods are called render_something() where ''something'' is the name of the widget. Their first parameter must be an instance of ''something'' class that implements interface ''renderable''. These methods can be overridden by themes.

Public method to render a widget is called render(). It accepts the only parameter which must be an instance of a class implementing ''renderable'' interface. It uses the class name of the widget passed in as parameter to find the corresponding protected rendering method.

If the widget also implements the "templatable" interface, and there is no render_widget helper explicitly defined for this class, then the render method will look for a template name matching the class in the same component. If found, it will automatically render the template with the data exported using $widget->export_for_template(), no additional renderer code is required.

Implementation of renderer_base::render() (inherited by all renderers)
<code php>
class renderer_base {
// ...
public function render(renderable $widget) {
$classparts = explode('\\', get_class($widget));
// Strip namespaces.
$classname = array_pop($classparts);
// Remove _renderable suffixes
$classname = preg_replace('/_renderable$/', '', $classname);

$rendermethod = 'render_'.$classname;
if (method_exists($this, $rendermethod)) {
return $this->$rendermethod($widget);
}
if ($widget instanceof templatable) {
$component = array_shift($classparts);
if (!$component) {
$component = 'core';
}
$template = $component . '/' . $classname;
$context = $widget->export_for_template($this);
return $this->render_from_template($template, $context);
}
throw new coding_exception('Can not render widget, renderer method ('.$rendermethod.') not found.');
}
// ...
}
</code>

For some widgets, a helper method may be implemented to instantiate the widget and render it in the background. Such helper methods have the same name as the widget class and accepts parameters needed to create the widget instance. Themes should not override helper methods because their usage is optional.

'''Example:''' User avatar rendering involves following methods and classes:
<code php>
class core_renderer extends renderer_base {
// ...
protected function render_user_picture(user_picture $userpicture) {
// returns HTML code to be echoed for displaying the user avatar
}
public function user_picture(stdclass $userrecord, array $options=null) {
// helper method that constructs $user_image widget and calls $this->render()
$picture = new user_picture($userrecord, $options);
return $this->render($picture);
}
// ...
}

class user_picture implements renderable {
public $userrecord;
public $courseid = 0;
public $link = true;

public function __construct(stdclass $userrecord, array $options=null) {
// ...
}
}
</code>

There are two ways a developer can render the user picture. Either using a one-line style:
<code php>
$user = $DB->get_record('user', array(...));
echo $OUTPUT->user_picture($user, array('courseid' => $courseid, 'link' => true));
</code>

or an explicit style:
<code php>
$user = $DB->get_record('user', array(...));
$avatar = new user_picture($user);
$avatar->courseid = $courseid;
$avatar->link = true;
echo $OUTPUT->render($avatar);
</code>

The point is that the first style is usually one line only, it is also possible to have multiple helpers with different parameters. The second style allows more options without cluttering the simple API with tons of optional method parameters.

Plugins can also use renderable objects and define render_something() functions in plugin renderers.

=== core_renderer_cli ===

''_cli'' suffix indicates this is a core renderer for CLI rendering target (CLI scripts). For example headings are using '''=>''' instead if H2 html tag.

== Core subsystem renderers ==

== Plugin renderers ==

Plugin renderers are stored in renderer.php file in the root folder of the plugin or in /classes/. They all extend plugin_renderer_base method.

=== plugin_renderer_base ===

An important thing about this class is that it keeps a reference to an instance of (typically) core_renderer which is used as an underlying renderer. This reference is kept in protected $output member variable. So, there is no more $OUTPUT in plugin renderers. They all use $this->output->something() to render the output.

'''Example:''' Workshop module defines mod_workshop_renderer class in mod/workshop/renderer.php file. The renderer defines a method to display a student submission.
<code php>
// in renderer.php:
class workshop_submission implements renderable {

public function __construct(stdclass $submission, $anonymous = false, array $attachments = null) {
// here the widget is prepared and all necessary logic is performed
if ($anonymous) {
$this->authorname = get_string('anonymousauthor', 'workshop');
} else {
$this->authorname = fullname(...);
}
}
}

class mod_workshop_renderer extends plugin_renderer_base {

protected function render_workshop_submission(workshop_submission $submission) {
$out = $this->output->heading(format_string($submission->title), 2);
$out .= $this->output->container(format_string($submission->authorname), 'author');
$out .= $this->output->container(format_text($submission->content, FORMAT_HTML), 'content');
return $this->output->container($out, 'submission');
}
}

// in view.php
$output = $PAGE->get_renderer('mod_workshop');
$submissionrecord = get_record('workshop_submissions', array(...));
$submissionwidget = new workshop_submission($submissionrecord, false);
echo $output->header();
echo $output->render($submissionwidget);
echo $output->footer();
</code>

Note that $output->header() and $output->footer() are not defined in mod_workshop_renderer. Plugin renderers are able to forward calls to the underlying renderer automatically. So, in view.php, there could be echo $OUTPUT->header(); which would call the same method. We prefer the way above because of consistency - there is the only one $output instance used instead of two $OUTPUT and $wsoutput.

'''WARNING: get_renderer() should typically be the last output related call you make before displaying your page's header.''' get_renderer() forces the page layout to 'base' if it has not already been set and this will almost certainly cause your page to display incorrectly (e.g. no blocks).

Note that as of Moodle 2.9, the render method could be rewritten to use a template. See [[Templates]] for more information.

== Bootstrap renderer ==

Bootstrap renderer is used as a temporary $OUTPUT before the full initialisation of standard core renderer.

== Theme customisations ==

=== Theme renderers ===

Theme renderers are stored in renderers.php file in theme folder (or autoloaded from the classes folder). The actual overriding of renderers is the responsibility of renderer_factory classes which may be selected in theme config.php.

=== Creating a Renderable "widget" in your theme ===

To create a renderable "widget" that could be used in multiple places in your theme (e.g. on the front page, in an overriden renderer for mod_assign etc.)
Create a renderable and renderer in the following folder:
<code>
/theme/mytheme/output/mywidget/rendererable.php
theme/mytheme/output/mywidget/renderer.php
</code>
<code php>
$mywidgetrenderable = new \theme_mytheme\output\mywidget\renderable($params);
$mywidgetrenderer = $this->page->get_renderer('theme_mytheme','mywidget'); // Or $PAGE->get_renderer depending on context
$mywidget = $mywidgetrenderer->render($mywidgetrenderable);
</code>

there is a good example of this in moodle core -> /admin/tool/monitor

== Low level HTML output ==

Low level html markup is created via html_renderer class.

== See also ==
* [[Templates]]
* [[Theme changes]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=177535 Totally confused by output renderers...] forum discussion

[[Category:Themes]]

Creating a theme based on boost

2020-03-24T14:12:44Z

Plemaire: /* Why do we use pre and post SCSS? */ Removed useless article

{{Moodle 3.2}}
{{Template:Themes}}

This is a tutorial for how to create a new theme in any version of Moodle from 3.2 and later.

Moodle 3.2 introduced a new core theme named "Boost" which is a great starting point for themers wanting to build a modern Moodle theme utilising all the latest features available to themes in Moodle. If you aren't sure where to start, then START HERE! :-)

== Getting started ==
What is a theme? A theme in Moodle is just another type of plugin that can be developed. Themes are responsible for setting up the structure of each page and have the ability to customise the output of any page in Moodle.

This tutorial is based on a working theme named "theme_photo" you can download it or view the source code for it here: https://github.com/damyon/moodle-theme_photo

=== Choosing a name ===
Your new theme will need a name. Try and think of something short and memorable - and make sure it is not a name that has already been used by someone else. A quick search on the moodle.org/plugins can save you a lot of work renaming things later.

Lets call our new example theme "photo" as we will add some settings to allow "photos" in various places in Moodle.

=== Starting files ===
As a plugin, themes must start with the basic structure of a plugin in Moodle. See https://docs.moodle.org/dev/Tutorial#The_skeleton_of_your_plugin for an overview of the files common to all plugins in Moodle.

Following this guide we can start creating our theme. First we create the folder for the new theme under under "/theme/" folder in the Moodle root directory.

<code>
/theme/photo/
</code>

Now we need to add some standard plugin files to our theme. First is version.php

''/theme/photo/version.php''

<code php>

<?php
// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// This is the version of the plugin.
$plugin->version = '2016102100';

// This is the version of Moodle this plugin requires.
$plugin->requires = '2016070700';

// This is the component name of the plugin - it always starts with 'theme_'
// for themes and should be the same as the name of the folder.
$plugin->component = 'theme_photo';

// This is a list of plugins, this plugin depends on (and their versions).
$plugin->dependencies = [
'theme_boost' => '2016102100'
];

</code>

We also need a language file so that all our strings can be translated into different languages. The name of this file is the component name of our plugin and it sits in the lang/en/ folder for our plugin. We can include translations of our plugin, but we can also provide translations via the https://lang.moodle.org/ website once our plugin has been published to the plugins database at http://www.moodle.org/plugins/.

''/theme/photo/lang/en/theme_photo.php''

<code php>

<?php
// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// A description shown in the admin theme selector.
$string['choosereadme'] = 'Theme photo is a child theme of Boost. It adds the ability to upload background photos.';
// The name of our plugin.
$string['pluginname'] = 'Photo';
// We need to include a lang string for each block region.
$string['region-side-pre'] = 'Right';
</code>

=== Theme specific files ===
Theme plugins have a few more standard files they need to define.

Themes require a favicon file to show in the address bar. See [[http://docs.moodle.org/en/Favicon Favicon]].

''pix/favicon.ico''

(Image file not shown).

Themes also require an example screenshot to be displayed in the theme selector.

''pix/screenshot.jpg''

(Image file not shown).

Themes require a lib.php file. This file contains callbacks used by various API's in Moodle. Initially this file can be empty, but as we add features to our theme we will need to add some functions here.

''lib.php''
<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// We will add callbacks here as we add features to our theme.
</code>

Theme config goes in a config.php file. This is one of the most important files in our theme. Once we add this file we will be ready to test our theme for the first time.

''config.php''

<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// $THEME is defined before this page is included and we can define settings by adding properties to this global object.

// The first setting we need is the name of the theme. This should be the last part of the component name, and the same
// as the directory name for our theme.
$THEME->name = 'photo';

// This setting list the style sheets we want to include in our theme. Because we want to use SCSS instead of CSS - we won't
// list any style sheets. If we did we would list the name of a file in the /style/ folder for our theme without any css file
// extensions.
$THEME->sheets = [];

// This is a setting that can be used to provide some styling to the content in the TinyMCE text editor. This is no longer the
// default text editor and "Atto" does not need this setting so we won't provide anything. If we did it would work the same
// as the previous setting - listing a file in the /styles/ folder.
$THEME->editor_sheets = [];

// This is a critical setting. We want to inherit from theme_boost because it provides a great starting point for SCSS bootstrap4
// themes. We could add more than one parent here to inherit from multiple parents, and if we did they would be processed in
// order of importance (later themes overriding earlier ones). Things we will inherit from the parent theme include
// styles and mustache templates and some (not all) settings.
$THEME->parents = ['boost'];

// A dock is a way to take blocks out of the page and put them in a persistent floating area on the side of the page. Boost
// does not support a dock so we won't either - but look at bootstrapbase for an example of a theme with a dock.
$THEME->enable_dock = false;

// This is an old setting used to load specific CSS for some YUI JS. We don't need it in Boost based themes because Boost
// provides default styling for the YUI modules that we use. It is not recommended to use this setting anymore.
$THEME->yuicssmodules = array();

// Most themes will use this rendererfactory as this is the one that allows the theme to override any other renderer.
$THEME->rendererfactory = 'theme_overridden_renderer_factory';

// This is a list of blocks that are required to exist on all pages for this theme to function correctly. For example
// bootstrap base requires the settings and navigation blocks because otherwise there would be no way to navigate to all the
// pages in Moodle. Boost does not require these blocks because it provides other ways to navigate built into the theme.
$THEME->requiredblocks = '';

// This is a feature that tells the blocks library not to use the "Add a block" block. We don't want this in boost based themes because
// it forces a block region into the page when editing is enabled and it takes up too much room.
$THEME->addblockposition = BLOCK_ADDBLOCK_POSITION_FLATNAV;
</code>

=== Ready set go! ===
If you have been following along - now we are at the point where we can actually install and test our new theme. Try it now by visiting the admin notifications page to install the new plugin, and then choosing the new theme from the theme selector.

[[https://docs.moodle.org/en/Standard_themes#Theme_selector Theme selector]]

When you choose the new theme - you will find that it looks exactly the same as Boost. At this point with our minimal configuration - we are inheriting almost everything from our parent theme including styles and templates. You will notice though that we don't inherit the settings from our parent theme. If you choose a different preset in Boost - it is not applied in this child theme.

<div class="warningbox">
Note: make sure your config.php file contains $THEME->hidefromselector = false; (or at least set to false) or else, your theme wont show up in theme selector.
</div>

=== What if I want the settings too? ===

<div class="warningbox">
This section is included for completeness - but it is not recommended for themes to utilise settings from their parents. To find out how to duplicate the settings from the parent theme so they operate independently skip to [[#Duplicate the settings from Boost]].
</div>

If I want the settings from Boost to apply to my child theme as well I need to know a bit about how each of the settings in Boost is applied to make them work in my child theme.

'''Setting 1 - preset.'''

The "preset" file is the file that is used as the main file for scss compilation. In Boost this is controlled by the theme config value:

''theme_boost/config.php''
<code php>
$THEME->scss = function($theme) {
return theme_boost_get_main_scss_content($theme);
};
</code>
''theme_boost/lib.php''
<code php>
function theme_boost_get_main_scss_content($theme) {
global $CFG;

$scss = '';
$filename = !empty($theme->settings->preset) ? $theme->settings->preset : null;
$fs = get_file_storage();

$context = context_system::instance();
if ($filename == 'default.scss') {
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
} else if ($filename == 'plain.scss') {
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/plain.scss');
} else if ($filename && ($presetfile = $fs->get_file($context->id, 'theme_boost', 'preset', 0, '/', $filename))) {
$scss .= $presetfile->get_content();
} else {
// Safety fallback - maybe new installs etc.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
}

return $scss;
}
</code>

What this function is doing is checking for a theme setting "preset" and either fetching the file from Moodles internal file storage, or from the /preset/ folder. The function then returns the contents of this file.

It does not automatically work for our child theme because we have no setting named "preset" in our child theme and this code is not searching the theme parents for the setting. If we wanted it to apply we could do this in our child theme:

''config.php''
<code php>
// This setting defines the main scss file for our theme to be compiled. We could set it to a static file in the scss folder or to a function which returns the SCSS based on theme settings.
$THEME->scss = function($theme) {

// We need to load the config for our parent theme because that is where the preset setting is defined.
$parentconfig = theme_config::load('boost');
// Call a function from our parent themes lib.php file to fetch the content of the themes main SCSS file based on it's own config, not ours.
return theme_boost_get_main_scss_content($parentconfig);
};
</code>

'''Settings 2+3 brandcolor + scsspre'''

The way these settings work is they generate a chunk of SCSS to be prepended to the main scss file. In boost they work like this:

''theme_boost/config.php''
<code php>
$THEME->prescsscallback = 'theme_boost_get_pre_scss';
</code>
''theme_boost/lib.php''
<code php>
function theme_boost_get_pre_scss($theme) {
global $CFG;

$scss = '';
$configurable = [
// Config key => [variableName, ...].
'brandcolor' => ['brand-primary'],
];

// Prepend variables first.
foreach ($configurable as $configkey => $targets) {
$value = isset($theme->settings->{$configkey}) ? $theme->settings->{$configkey} : null;
if (empty($value)) {
continue;
}
array_map(function($target) use (&$scss, $value) {
$scss .= '$' . $target . ': ' . $value . ";\n";
}, (array) $targets);
}

// Prepend pre-scss.
if (!empty($theme->settings->scsspre)) {
$scss .= $theme->settings->scsspre;
}

return $scss;
}
</code>

What this code is doing is:
* looping over a list of theme settings that map to a SCSS variable and building some SCSS to initialise that variable from the setting. In Boost there is only one * brandprimary - but if we wanted to expose more bootstrap variables as theme settings we could use this function as a template in our child theme and add more settings to the $configurable array.
* Adding all of the raw SCSS from the scsspre theme setting
* Returning the whole thing as a string to be added before the main scss file.

If we want this code to work in our child theme, using the settings from Boost we could do this:

''config.php''
<code php>
// This is a function that returns some SCSS as a string to prepend to the main SCSS file.
$THEME->prescsscallback = 'theme_photo_get_pre_scss';
</code>

''lib.php''
<code php>
// Function to return the SCSS to prepend to our main SCSS for this theme.
// Note the function name starts with the component name because this is a global function and we don't want namespace clashes.
function theme_photo_get_pre_scss($theme) {
// Load the settings from the parent.
$theme = theme_config::load('boost');
// Call the parent themes get_pre_scss function.
return theme_boost_get_pre_scss($theme);
}
</code>

'''Setting 4 scss (post)'''

The final setting from Boost is a raw text field which adds SCSS to the end of the main SCSS file. This is a useful place to add style rules as they will override previously defined styles with the same specificity. It is applied in Boost by the following lines:

''theme_boost/config.php''
<code php>
$THEME->extrascsscallback = 'theme_boost_get_extra_scss';
</code>
''theme_boost/lib.php''
<code php>
function theme_boost_get_extra_scss($theme) {
return !empty($theme->settings->scss) ? $theme->settings->scss : '';
}
</code>

This is just returning the value of the setting as a string.

To make this setting apply in our child theme too - we use similar code to the previous sections.

''config.php''
<code php>
// This is a function that returns some SCSS as a string to prepend to the main SCSS file.
$THEME->extrascsscallback = 'theme_photo_get_extra_scss';
</code>

''lib.php''
<code php>
// Function to return the SCSS to append to our main SCSS for this theme.
// Note the function name starts with the component name because this is a global function and we don't want namespace clashes.
function theme_photo_get_extra_scss($theme) {
// Load the settings from the parent.
$theme = theme_config::load('boost');
// Call the parent themes get_extra_scss function.
return theme_boost_get_extra_scss($theme);
}
</code>

=== Duplicate the settings from Boost ===

This is the recommended way to extend boost as your child theme will not be affected by changes to the Boost settings, and both themes can be in use with different settings applied.

All that needs to happen is to create theme settings in the child theme that match each of the settings in the parent theme. You will need to add matching language strings for each of these settings in the language file.

This example shows how to do it - We are re-using the nice looking theme_boost_admin_settingspage_tabs class from boost and creating duplicate versions of each of the settings.

''settings.php''

<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// This is used for performance, we don't need to know about these settings on every page in Moodle, only when
// we are looking at the admin settings pages.
if ($ADMIN->fulltree) {

// Boost provides a nice setting page which splits settings onto separate tabs. We want to use it here.
$settings = new theme_boost_admin_settingspage_tabs('themesettingphoto', get_string('configtitle', 'theme_photo'));

// Each page is a tab - the first is the "General" tab.
$page = new admin_settingpage('theme_photo_general', get_string('generalsettings', 'theme_photo'));

// Replicate the preset setting from boost.
$name = 'theme_photo/preset';
$title = get_string('preset', 'theme_photo');
$description = get_string('preset_desc', 'theme_photo');
$default = 'default.scss';

// We list files in our own file area to add to the drop down. We will provide our own function to
// load all the presets from the correct paths.
$context = context_system::instance();
$fs = get_file_storage();
$files = $fs->get_area_files($context->id, 'theme_photo', 'preset', 0, 'itemid, filepath, filename', false);

$choices = [];
foreach ($files as $file) {
$choices[$file->get_filename()] = $file->get_filename();
}
// These are the built in presets from Boost.
$choices['default.scss'] = 'default.scss';
$choices['plain.scss'] = 'plain.scss';

$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

// Preset files setting.
$name = 'theme_photo/presetfiles';
$title = get_string('presetfiles','theme_photo');
$description = get_string('presetfiles_desc', 'theme_photo');

$setting = new admin_setting_configstoredfile($name, $title, $description, 'preset', 0,
array('maxfiles' => 20, 'accepted_types' => array('.scss')));
$page->add($setting);

// Variable $brand-color.
// We use an empty default value because the default colour should come from the preset.
$name = 'theme_photo/brandcolor';
$title = get_string('brandcolor', 'theme_photo');
$description = get_string('brandcolor_desc', 'theme_photo');
$setting = new admin_setting_configcolourpicker($name, $title, $description, '');
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

// Must add the page after definiting all the settings!
$settings->add($page);

// Advanced settings.
$page = new admin_settingpage('theme_photo_advanced', get_string('advancedsettings', 'theme_photo'));

// Raw SCSS to include before the content.
$setting = new admin_setting_configtextarea('theme_photo/scsspre',
get_string('rawscsspre', 'theme_photo'), get_string('rawscsspre_desc', 'theme_photo'), '', PARAM_RAW);
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

// Raw SCSS to include after the content.
$setting = new admin_setting_configtextarea('theme_photo/scss', get_string('rawscss', 'theme_photo'),
get_string('rawscss_desc', 'theme_photo'), '', PARAM_RAW);
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

$settings->add($page);
}
</code>

''lang/en/theme_photo.php''
<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();
// The name of the second tab in the theme settings.
$string['advancedsettings'] = 'Advanced settings';
// The brand colour setting.
$string['brandcolor'] = 'Brand colour';
// The brand colour setting description.
$string['brandcolor_desc'] = 'The accent colour.';
// A description shown in the admin theme selector.
$string['choosereadme'] = 'Theme photo is a child theme of Boost. It adds the ability to upload background photos.';
// Name of the settings pages.
$string['configtitle'] = 'Photo settings';
// Name of the first settings tab.
$string['generalsettings'] = 'General settings';
// The name of our plugin.
$string['pluginname'] = 'Photo';
// Preset files setting.
$string['presetfiles'] = 'Additional theme preset files';
// Preset files help text.
$string['presetfiles_desc'] = 'Preset files can be used to dramatically alter the appearance of the theme. See <a href=https://docs.moodle.org/dev/Boost_Presets>Boost presets</a> for information on creating and sharing your own preset files, and see the <a href=http://moodle.net/boost>Presets repository</a> for presets that others have shared.';
// Preset setting.
$string['preset'] = 'Theme preset';
// Preset help text.
$string['preset_desc'] = 'Pick a preset to broadly change the look of the theme.';
// Raw SCSS setting.
$string['rawscss'] = 'Raw SCSS';
// Raw SCSS setting help text.
$string['rawscss_desc'] = 'Use this field to provide SCSS or CSS code which will be injected at the end of the style sheet.';
// Raw initial SCSS setting.
$string['rawscsspre'] = 'Raw initial SCSS';
// Raw initial SCSS setting help text.
$string['rawscsspre_desc'] = 'In this field you can provide initialising SCSS code, it will be injected before everything else. Most of the time you will use this setting to define variables.';
// We need to include a lang string for each block region.
$string['region-side-pre'] = 'Right';
</code>

We aren't quite there yet as you will notice if you try and upload a preset file and then choose it. The "theme_boost_get_main_scss_content" function from Boost is expecting the preset files to be stored in a file area for theme_boost only. We need to add this function to our own theme and tweak it.

''config.php''
<code php>
// This is the function that returns the SCSS source for the main file in our theme. We override the boost version because
// we want to allow presets uploaded to our own theme file area to be selected in the preset list.
$THEME->scss = function($theme) {
return theme_photo_get_main_scss_content($theme);
};
</code>

''lib.php''
<code php>
function theme_photo_get_main_scss_content($theme) {
global $CFG;

$scss = '';
$filename = !empty($theme->settings->preset) ? $theme->settings->preset : null;
$fs = get_file_storage();

$context = context_system::instance();
if ($filename == 'default.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
} else if ($filename == 'plain.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/plain.scss');

} else if ($filename && ($presetfile = $fs->get_file($context->id, 'theme_photo', 'preset', 0, '/', $filename))) {
// This preset file was fetched from the file area for theme_photo and not theme_boost (see the line above).
$scss .= $presetfile->get_content();
} else {
// Safety fallback - maybe new installs etc.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
}

return $scss;
}
</code>

=== Stop and try it out ===
So now what is working and what isn't. Well - everything should be working and you should have a nice new theme extending boost with it's own settings pages. When Boost gets updates for bug fixes your new theme will inherit those fixes as it inherits all the SCSS and templates from theme boost. In addition your new theme will accept preset files and supports all the same features and settings as boost, ready to add more.

== Take it further ==
Now we have our very nice starting point we can start changing or adding features, customising templates and output or tweaking the SCSS.

=== Add some new settings ===

From this point in the tutorial we will start adding features to our theme to extend it and make it AWESOME!

Lets start with a new setting to set a background image on the login page. As you saw earlier, our theme defines it's list of settings in a file called settings.php. See [[Admin settings]] for more information about adding admin settings to any plugin. All of the different kinds of admin settings can be found in lib/adminlib.php. In our case we will want to add a setting which allows an admin to upload an image file. This is an "admin_setting_configstoredfile" and we add it to our theme by adding this code to the settings.php file (inside the "if ($ADMIN->fulltree) {" condition.

''settings.php''
<code php>
// Login page background setting.
// We use variables for readability.
$name = 'theme_photo/loginbackgroundimage';
$title = get_string('loginbackgroundimage', 'theme_photo');
$description = get_string('loginbackgroundimage_desc', 'theme_photo');
// This creates the new setting.
$setting = new admin_setting_configstoredfile($name, $title, $description, 'loginbackgroundimage');
// This means that theme caches will automatically be cleared when this setting is changed.
$setting->set_updatedcallback('theme_reset_all_caches');
// We always have to add the setting to a page for it to have any effect.
$page->add($setting);
</code>

We also need to add new lang strings to our language file.

"lang/en/theme_photo.php"
<code php>
// Background image for login page.
$string['loginbackgroundimage'] = 'Login page background image';
// Background image for login page.
$string['loginbackgroundimage_desc'] = 'An image that will be stretched to fill the background of the login page.';
</code>

Now we have a new setting that lets us upload a file - but it doesn't actually do anything yet. We need to update the theme to set this image background on the login page.

In order to change the SCSS for our theme we will add 2 additional SCSS files and include them before and after our main scss.

We already have a function in our lib.php file which fetches the main SCSS for our theme. This is a good point to include additional SCSS files. We can add 2 lines to the end of this function to achieve this.

''lib.php''
<code php>
function theme_photo_get_main_scss_content($theme) {
global $CFG;

$scss = '';
$filename = !empty($theme->settings->preset) ? $theme->settings->preset : null;
$fs = get_file_storage();

$context = context_system::instance();
if ($filename == 'default.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
} else if ($filename == 'plain.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/plain.scss');

} else if ($filename && ($presetfile = $fs->get_file($context->id, 'theme_photo', 'preset', 0, '/', $filename))) {
// This preset file was fetched from the file area for theme_photo and not theme_boost (see the line above).
$scss .= $presetfile->get_content();
} else {
// Safety fallback - maybe new installs etc.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
}

// Pre CSS - this is loaded AFTER any prescss from the setting but before the main scss.
$pre = file_get_contents($CFG->dirroot . '/theme/photo/scss/pre.scss');
// Post CSS - this is loaded AFTER the main scss but before the extra scss from the setting.
$post = file_get_contents($CFG->dirroot . '/theme/photo/scss/post.scss');

// Combine them together.
return $pre . "\n" . $scss . "\n" . $post;
}
</code>

''scss/pre.scss''
<code scss>
// Pre SCSS for the theme.
</code>

''scss/post.scss''
<code scss>
// Post SCSS for the theme.
</code>

==== Why do we use pre and post SCSS? ====
SCSS/SASS is a powerful language for creating CSS. It supports variables, functions, loops just like php. For lots of information and an introduction to SCSS read about [https://en.wikipedia.org/wiki/Sass_(stylesheet_language) Sass on wikipedia].

'''Pre SCSS'''

In Boost we use many variables when creating style rules.

When declaring a variable in SCSS - it is best practice to define it like this:
<code scss>
$mycoolcolour: #FF0 !default;
</code>

What this means is - if this variable is not defined already - set it to the hex value '#FF0';

So by setting this variable in some PRE scss we can override the default value of this variable everywhere it is used. Boost is built with the [https://v4-alpha.getbootstrap.com/ Bootstrap 4 (Alpha 4)] CSS Framework. This is a framework which uses SCSS to provide many extremely useful layouts and components which can be reused without adding specific CSS rules to style every page. Because bootstrap consistently uses variables we can customise many of these components easily by setting the value of the variables before we include the Bootstrap SCSS files.

Many variables are available in /theme/boost/scss/bootstrap/_variables.scss - as an example we can change the look of all buttons and input fields with this one variable:

<code scss>
$border-radius: 8px;
</code>

'''Post SCSS'''

Post SCSS is useful for defining full CSS rules. Because they are included last, they override any previous matching selector with the same [https://en.wikipedia.org/wiki/Cascading_Style_Sheets#Specificity Specificity].

=== Tips for customising Moodle with SCSS (or CSS) ===
Some handy things to know when you are new to theming is that Moodle adds some classes to every page that helps you target a specific page or set of pages with some style rules.

If you inspect a moodle page and look at the body tag you will see a long list of classes e.g.

<code html>
<body id="page-course-view-weeks" class="format-weeks path-course path-course-view safari dir-ltr lang-en yui-skin-sam yui3-skin-sam damyon-per-in-moodle-com--stable_master pagelayout-course course-11 context-497 category-1 drawer-open-left jsenabled">
</code>

You can see from this example that each page gets an id. This is a simplified representation of the current page in the navigation. In this example we are looking at the course page and this course is using the weeks format.

The classes on the body tag can also be used to target a page or set of pages.
* <code>format-weeks</code> The course format
* <code>path-course path-course-view</code> The parts of the bread-crumb leading up to the current page (The current page is what goes in the id)
* <code>safari</code> Some server side guessing of the browser type - it's not accurate so I would not rely on it
* <code>dir-ltr</code> The direction of the current language for the page ( dir-rtl for RTL languages )
* <code>lang-en</code> The current language of the page
* <code>yui*</code> Legacy yui classes - ignore these
* <code>damyon-per-in-moodle-com--stable_master</code> The current hostname for the site + the site name
* <code>pagelayout-course</code> The layout type for the current page
* <code>course-11</code> The id of the current course
* <code>context-497</code> The current context id
* <code>category-1</code> The category for the current course
* <code>drawer-open-left</code> Added / removed when the navigation drawer is opened / closed in Boost
* <code>jsenabled</code> True if the browser supports javascript

[https://docs.moodle.org/dev/Themes_overview#.3Cbody.3E_CSS_id_and_classes Read about Body id and classes].

In our example the page layout is the most useful here as we have a specific page layout for login pages. We can now craft a rule that applies a background image only to login pages using "body.pagelayout-login".

=== How do we refer to an image in SCSS ? ===
So now we can add a rule to the post.scss which will set the background image for the login page. First we need to know how to construct a url to the background images from our stylesheet.

In stylesheets in Moodle we can use a special pix tag to refer to images from our theme. The rule to attach the background image looks like this:
''scss/post.scss''
<code scss>
body.pagelayout-login {
background-image: url([[pix:theme_photo|loginbackgroundimage]]);
background-size: cover;
}
</code>

There are 2 important parts to this tag (the bit in square brackets). The first is "theme_photo". In this case we are passing a component name, the image serving code in theme_config::resolve_image_location() will then look for an image file in several locations. One of these is in "$CFG->dataroot/pix_plugins/$type/$plugin/$image". We can use this to make sure the image gets served correctly by copying the file saved in the setting to this location every time it is updated. (There is an alterative way we could do this by implementing pluginfile.php in our theme - which you can read about in the [[File API]] ).

If we had just passed the value "theme" the image serving code would have looked for the image in the "pix" folder of our theme.

So - we need this final change to copy the image file into our dataroot each time the setting is changed.

In the settings file we will update the callback to a new function which we will define in our lib.php.
''settings.php''
<code php>

// Login page background setting.
// We use variables for readability.
$name = 'theme_photo/loginbackgroundimage';
$title = get_string('loginbackgroundimage', 'theme_photo');
$description = get_string('loginbackgroundimage_desc', 'theme_photo');
// This creates the new setting.
$setting = new admin_setting_configstoredfile($name, $title, $description, 'loginbackgroundimage');
// This function will copy the image into the data_root location it can be served from.
$setting->set_updatedcallback('theme_photo_update_settings_images');
// We always have to add the setting to a page for it to have any effect.
$page->add($setting);
</code>

''lib.php''
<code php>
function theme_photo_update_settings_images($settingname) {
global $CFG;

// The setting name that was updated comes as a string like 's_theme_photo_loginbackgroundimage'.
// We split it on '_' characters.
$parts = explode('_', $settingname);
// And get the last one to get the setting name..
$settingname = end($parts);

// Admin settings are stored in system context.
$syscontext = context_system::instance();
// This is the component name the setting is stored in.
$component = 'theme_photo';

// This is the value of the admin setting which is the filename of the uploaded file.
$filename = get_config($component, $settingname);
// We extract the file extension because we want to preserve it.
$extension = substr($filename, strrpos($filename, '.') + 1);

// This is the path in the moodle internal file system.
$fullpath = "/{$syscontext->id}/{$component}/{$settingname}/0{$filename}";
// Get an instance of the moodle file storage.
$fs = get_file_storage();
// This is an efficient way to get a file if we know the exact path.
if ($file = $fs->get_file_by_hash(sha1($fullpath))) {
// We got the stored file - copy it to dataroot.
// This location matches the searched for location in theme_config::resolve_image_location.
$pathname = $CFG->dataroot . '/pix_plugins/theme/photo/' . $settingname . '.' . $extension;

// This pattern matches any previous files with maybe different file extensions.
$pathpattern = $CFG->dataroot . '/pix_plugins/theme/photo/' . $settingname . '.*';

// Make sure this dir exists.
@mkdir($CFG->dataroot . '/pix_plugins/theme/photo/', $CFG->directorypermissions, true);

// Delete any existing files for this setting.
foreach (glob($pathpattern) as $filename) {
@unlink($filename);
}

// Copy the current file to this location.
$file->copy_content_to($pathname);
}

// Reset theme caches.
theme_reset_all_caches();
}
</code>

I won't show it here - but it is now easy to add a new background image setting for every layout type. I can re-use this theme_photo_update_settings_images callback for each one - so all I have to do is add the setting to the settings.php file, add the SCSS rule to the scss/post.scss file and add the lang strings to the language file.

Thats it for this tutorial, but there are [[:Category:Themes| more Themes docs]] to browse.

[[Category:Themes]]

Debugging network requests in the Moodle App

2019-07-30T09:08:10Z

Plemaire: /* Debugging a web service (WS) error */ link error

{{Moodle Mobile}}== Introduction ==

This guide will help you find and report problems with the Moodle Mobile app on your site.

It is especially useful for the following problems:
* Unable to log in on your site
* When you receive one of the following error messages in the app:
** Can not find data record in database table external_functions
** Invalid response value detected
** Cannot get course contents

== Requirements ==
* Moodle 3.1 onwards (your site needs at least this version)
* Moodle Desktop app 3.6.1 onwards or Google Chrome/Chromium browser
[[{{ns:file}}:moodlemobile_enabledebug.png|thumb|300px]]

== Enabling debugging on your Moodle site ==

# Go to Debugging in the Site administration
# For "Debug messages" select 'DEVELOPER'
# Tick "Display debug messages"
# Click the 'Save changes' button.

Note: Remember to disable debugging again once you have finished debugging your problem.

== Enabling debugging on the mobile app ==

# Go to the More tab
# Go to Settings > General
# Enable "Display debug messages"

Note: Remember to disable debugging again once you have finished debugging your problem.

== First try ==

At this point, you may not need fo go further on this guide.

Log-out and log-in again into your site and try to reproduce the error, hopefully, with Moodle and app debugging enabled you will see an explanatory message of what is happening.

If you are unable to find a solution, contact a [https://moodle.com/partners/ Moodle Partner] or post in the [https://moodle.org/mod/forum/view.php?id=7798 Moodle for mobile forum] on moodle.org for non-guaranteed community support.

== Setting up the debugging tool ==

=== Moodle Desktop ===

The recommended way to debug the problem is using the Moodle Desktop app. Please notice that the app version should be 3.6.1 or higher. The desktop app lets you debug some features, such as Single Sign-On, that require a built app to work, rather than a hosted or local ionic build running in a web browser.

You can download the desktop app [https://download.moodle.org/desktop/ from here].

Download the desktop app, install it and open it. Once it's open, you can open the "Developer tools" with the following shortcut:

* In MacOS: Cmd + Option + I
* In Windows or Linux: Ctrl + Shift + I

Once the Developer Tools are open, follow these steps:

# Dock the new panels on the right side (in the new panel top-right options choose “Dock to the right” icon)
# Click the Network tab (at the top-center)
# Enable the filter (filter shape icon) so it changes to colour red
# In the new text field displayed when enabling the filter write <code>.php</code>

Now you are ready to debug all the web services requests sent to your Moodle site by the mobile app.

=== Chrome or Chromium ===

[[{{ns:file}}:moodlemobile_chrome_inspect_network.png|thumb|300px]]

Another option is to use Google Chrome or Google Chromium to debug this. If you already have the Moodle Desktop app you can skip this section.

Debugging the mobile app is not so easy, so we have provided an online web version of the app that can be easily debugged using the Chrome browser.

# Open your Chrome browser and go to https://mobileapp.moodledemo.net/
# Open your browser options (icon at the top-right of your browser window), then go to More tools -> Developer tools
# Dock the new panels on the right side (in the new panel top-right options choose “Dock to the right” icon)
# Click the Network tab (at the top-center)
# Enable the filter (filter shape icon) so it changes to colour red
# In the new text field displayed when enabling the filter write <code>.php</code>

Now you are ready to debug all the web services requests sent to your Moodle site by the mobile app.

== Debugging a web service (WS) error ==

[[{{ns:file}}:moodlemobile_chrome_debug_ws_error.png|thumb|300px]]

# Connect to your site and browse to the functionality displaying an error
# In the right panel you will see a list of requests made by the app to your Moodle site (token.php server.php server.php etc..)
# Click on each one of them (starting with the last one in the list) but skip those that don’t start with token.php or server.php
# In the new sub-window open select the “Response” tab and check if you see an error
# Copy the error then go to the [[:en:Moodle Mobile FAQ|Moodle Mobile FAQ]] in the user docs to check if there is a known solution for it
# If you are unable to find a solution, contact a [https://moodle.com/partners/ Moodle Partner] or post in the [https://moodle.org/mod/forum/view.php?id=7798 Moodle for mobile forum] on moodle.org for non-guaranteed community support.

== See also ==

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

Making changes show up during development

2019-04-04T09:56:12Z

Plemaire: /* Capabilities */

Sometime, when you are trying to do Moodle development, you edit the code, and nothing seems to change as a result. This is because, to improve performance, Moodle now has all sorts of caching built in. When this is happening, this page will try to give you the quickest way to make your changes show up in all situation.

== General advice ==

# In your development site, change most of the admin settings like 'Cache language strings', 'Cache JavaScript' to be suitable for development. Note that doing this will slow down your development site a bit.
# If in doubt, visit <nowiki>http://your.domain/moodle</nowiki>'''/admin''' to check that the Moodle install is up-to-date.
# And then <nowiki>http://your.domain/moodle</nowiki>'''/admin/purgecaches.php''' and click the 'Purge all caches' button. This will slow things down for the next few requests, until the caches have re-populated. Note there is also a CLI tool to purge caches.
# Depending on what you changed in your plugin, then in addition to the above, you may need to remember to increase the version number in the plugin's version.php, or the changes will not show up.
# You may have forgotten to run grunt.
# If you have just added a new Behat or PHPunit test, you may need to re-run admin/tool/.../cli/init.php

The above steps are a brute force approach. They will probably work, but are probably not the fastest way. Below, we list for all the various type of change you can make, the most efficient way to make the change show up.

== PHP ==

After changing the PHP files (*.php), you should just need to press reload (F5) in your browser.

=== Adding or removing an auto-loaded class ===

If you get class-not-found errors, you need to visit <nowiki>http://your.domain/moodle</nowiki>'''/admin'''.

== JavaScript ==

After editing the [[Javascript Modules]] source files (amd/src/*.js), if you have Administration -> Appearance -> AJAX and Javascript -> Cache Javascript turned off, then you should just need to reload (F5) in your browser.

If JS caching is on, you need to re-run grunt. (Do you also need to purge a cache??? I don't think so.)

== CSS ==

After changing the CSS styles (*.css) ...

== SCSS ==

After changing SCSS (*.scss) files ...

== LESS ==

After changing LESS (*.less) files ...

== Language strings ==

After changing language pack strings (lang/en/type_plugin.php):

* The best option is to turn off Admin -> Language -> Language settings -> Cache all language strings when doing development. Then you only need to press F5 to refresh to see your changes.
* Otherwise you need to Purge all caches (or just the Language strings cache) before reloading.

== Capabilities ==

After changing capabilities (db/access.php) you need to

# Bump the plugin version number.
# Go to admin -> Notifications.

Then check that the capabilitie shows up on Site administration > Users > Permissions > Define roles for any role.

== Scheduled tasks ==

After changing scheduled tasks (db/tasks.php) you need to

# Bump the plugin version number.
# Go to admin -> Notifications.

Then check that the task shows up on Admin -> Server -> Scheduled tasks.

== Web services ==

After changing web services (db/services.php) ...

== Database structure ==

After changing the database scheme (db/install.xml, db/upgrade.php) ...

== PHPunit ==

== Behat ==

After you add a new *.feature file, you need to re-run

$ php admin/tool/behat/cli/init.php

== Mobile support for plugins ==

If you are doing the kind of development described in [[Mobile support for plugins]], using a pre-built version of the app like https://mobileapp.moodledemo.net/.

Note, these steps were originally written by people mostly on question type plugins. Hopefully they are generally applicable, but if they don't make sense in your case, that might be why. Please edit to improve them.

=== General note ===

If there are lots of red error messages appearing in the JavaScript console (but not the very common error 'ERROR Error: Uncaught (in promise): null...' that repeats every minute and fills the console logs!) it is often necessary to clear site data and restart.

# In browser developer tools, go to Application -> Clear storage.
# Close the browser, and re-launch.

===Adding mobile support to a plugin for the first time===

# Bump the plugin version number.
# Go to admin -> Notifications.
# F5 in the app to restart.

=== HTML template ===

After changing an existing template (mobile/*.html), just pull down in the app to refresh.

=== Client-side JavaScript ===

After changing an existing client-side JavaScript (mobile/*.js), press F5 in the browser developer tools to restart the app.

=== Server-side classes/output/mobile.php ===

???

=== Mobile CSS ===

# Bump version number in db/mobile.php
# Purge caches (specifically the tool_mobile/plugininfo MUC cache)
# Press F5 to restart the app.

Blocks

2019-03-13T11:52:49Z

Plemaire: /* lang/en/block_simplehtml.php */

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

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

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

{{Moodle 2.0}}

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

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

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

== Basic Concepts ==

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

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

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

== Ready, Set, Go! ==

To define a "block" in Moodle, in the most basic case we need to provide just four PHP files. Remember, in this example we are creating a block called 'simplehtml', replace 'simplehtml' with the name of your custom block. The four files should be located in blocks/simplehtml and are:

=== block_simplehtml.php ===

This file will hold the class definition for the block, and is used both to manage it as a plugin and to render it onscreen.

We start by creating the main object file, 'block_simplehtml.php'. We then begin coding the block:

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

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

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

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

=== db/access.php ===

This file will hold the new capabilities created by the block.

Moodle 2.4 onwards introduced the capabilities addinstance and myaddinstance for core blocks. They were introduced so that it was possible to control the use of individual blocks. These capabilities should also be added to your custom block, so in this case to the file blocks/simplehtml/db/access.php. If your block is not going to be used in the 'My Moodle page' (ie, your applicable_formats function (discussed later) has 'my' set to false.) then the myaddinstance capability does not need to be given to any user, but it must still be defined here otherwise you will get errors on certain pages. The following is the capabilities array and how it should look for any new blocks.

<code php>
<?php
$capabilities = array(

'block/simplehtml:myaddinstance' => array(
'captype' => 'write',
'contextlevel' => CONTEXT_SYSTEM,
'archetypes' => array(
'user' => CAP_ALLOW
),

'clonepermissionsfrom' => 'moodle/my:manageblocks'
),

'block/simplehtml:addinstance' => array(
'riskbitmask' => RISK_SPAM | RISK_XSS,

'captype' => 'write',
'contextlevel' => CONTEXT_BLOCK,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),

'clonepermissionsfrom' => 'moodle/site:manageblocks'
),
);
</code>

=== lang/en/block_simplehtml.php ===

This is the English language file for your block. If you are not an English speaker, you can replace 'en' with your appropriate language code (but even then you will need english folder !). All language files for blocks go under the /lang subfolder of the block's installation folder.

Moodle 2.0 and above require a name for our plugin to show in the upgrading page. We set this value, along with the capabilities we created and any other language strings we wish to use within the block, in a language package as previously mentioned (the same file where we put our string for the plugin title).

The capabilities added above need descriptions for pages that allow setting of capabilities. These should also be added to the language file.

<code php>
<?php
$string['pluginname'] = 'Simple HTML block';
$string['simplehtml'] = 'Simple HTML';
$string['simplehtml:addinstance'] = 'Add a new simple HTML block';
$string['simplehtml:myaddinstance'] = 'Add a new simple HTML block to the My Moodle page';
</code>

=== version.php ===

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

Prior to Moodle 2.0, version details for blocks were stored as class fields; as of Moodle 2.0 these are stored in a file called version.php, stored under ''/blocks/simplehtml/'''version.php'''''. The version file is very simple indeed, containing only a few field definitions, depending on your needs. Here is an example:
<code php>
<?php
$plugin->component = 'block_simplehtml'; // Recommended since 2.0.2 (MDL-26035). Required since 3.0 (MDL-48494)
$plugin->version = 2011062800; // YYYYMMDDHH (year, month, day, 24-hr time)
$plugin->requires = 2010112400; // YYYYMMDDHH (This is the release version for Moodle 2.0)
</code>

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

The exact Moodle version of a release can be found in [[Releases]].

{{Top}}

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

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

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

return $this->content;
}

</code>

'''Add your block to the front page!'''
Don't forget (especially if you're a new Moodle user) to add your block to the front page. Turn Editing On, and add your block to the page.

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

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

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

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

== Configure That Out ==

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

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

<code php>
<?php

class block_simplehtml_edit_form extends block_edit_form {

protected function specific_definition($mform) {

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

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

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

'''NOTE:''' You might want extend language file for your block (lang/en/block_simplehtml.php) and add a value for "blockstring" defined in a code above.

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

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

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

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

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

{{Top}}

== The Specialists ==

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

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

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

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

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

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

<code php>
public function specialization() {
if (isset($this->config)) {
if (empty($this->config->title)) {
$this->title = get_string('defaulttitle', 'block_simplehtml');
} else {
$this->title = $this->config->title;
}

if (empty($this->config->text)) {
$this->config->text = get_string('defaulttext', 'block_simplehtml');
}
}
}
</code>

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

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

{{Top}}

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

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

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

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

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

{{Top}}

== We Are Legion ==

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

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

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

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

{{Top}}

== The Effects of Globalization ==

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

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

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

Place the following in your settings.php file:

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

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

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

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

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

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

=== Enabling Global Configuration ===
{{Moodle 2.4}}Since version 2.4, the following line must be added to the /blocks/simplehtml/block_simplehtml.php file in order to enable global configuration:
<code>
function has_config() {return true;}
</code>
This line tells Moodle that the block has a settings.php file.

'''NOTE FOR UPGRADERS'''

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

{{Top}}

=== Accessing Global Config Data ===

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

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

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

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

{{Top}}

=== Rolling It All Together ===

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

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

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

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

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

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

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

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

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

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

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

{{Top}}

== Eye Candy ==

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

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

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

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

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

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

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

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

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

{{Top}}

== Authorized Personnel Only ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{Top}}

== Background Processing ==

If you want to do some background processing in your block - use the [[Task API]] to create a background task that can be scheduled to run at regular intervals and can be displayed and configured by an administrator (this is the same regardless of the plugin type).

{{Top}}

== Additional Content Types ==

=== Lists ===

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

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

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

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

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

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

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

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

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

// Add more list items here

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

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

=== Trees ===

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

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

{{Top}}

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

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

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

== See also ==
* [[Blocks Advanced]] A continuation of this tutorial.
* [http://dev.moodle.org/mod/resource/view.php?id=48 Unit 7 of the Introduction to Moodle Programming course] is a follow up to this course. (But you should follow the forum discussions of that course closely as there are still some bugs and inconsistencies.)
* Daniel Neis Araujo's [https://github.com/danielneis/moodle-block_newblock NEWBLOCK template].

== Appendices ==

The appendices have been moved to separate pages:

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

{{Top}}

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

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

[[Category:Plugins]]