MoodleDocs - User contributions [en]

Quiz reports

2018-03-23T13:46:40Z

Ddelrio1986: /* The attempts report classes */

{{Quiz developer docs}}

Quiz report sub-plugins can not only be used to display custom reports on the quiz data, but can also be used to plugin other functionality into the quiz module.

==Overview==

Theses sub-plugins have frankenstyle prefix <tt>quiz_</tt>, and live inside <tt>mod/quiz/report</tt>. (The prefix was a historical mistake. It would have been much better to use <tt>quizreport_</tt>, but it is too late to change now.)

A quiz report plugins just needs to implement one class
class quiz_''name''_report extends quiz_default_report {
public function display($cm, $course, $quiz) {
// Generate and display the report, or
// other functionality.
}
}

The base class is defined in <tt>mod/quiz/report/default.php</tt> and you just need to implement the <tt>display</tt> method. This gets called from <tt>mod/quiz/report.php</tt> after some basic set-up has been done.

==What files make up a quiz report==

mod/quiz/report/''name''/
report.php - Contains the implementation of the quiz_''name''_report class.
version.php - Normal Moodle plugin version.php file.
lang/en/quiz_''name''.php - Language strings for your plugin.
db/* - lets you define db tables, capabilities, etc.
simpletest/* - Unit tests.

* It is possible to make a working plugin with only the first three of these.
* The only lang strings you need to define are <tt>pluginname</tt>, <tt>report''name''</tt> and <tt>''name''report</tt>. (This should probably be simplified in the future.)

==When a user view the report==

The will go to a URL like <tt>http://.../mod/quiz/report.php?id=''cmid''&mode=''name''</tt>. There may also be additional parameters in the URL if your report contains several internal pages with links between them. The statistics and grading reports are good examples of this.

This leads to a call to the <tt>quiz_''name''_report::display($quiz, $cm, $course)</tt> method. You can put whatever code you like in there.

==The attempts report classes==

There are some useful helper classes in <tt>mod/quiz/report/attemptsreport.php</tt>. This is basically the common functionality that is used by both the <tt>overview</tt> and <tt>responses</tt> reports. If you want to make a similar report (with one row for each quiz attempt) you should probably build on these classes.

There are also useful helper functions in <tt>mod/quiz/report/reportlib.php</tt>.

==See also==

* Most quiz reports use [[lib/tablelib.php]].
* [http://git.moodle.org/gw?p=moodle.git;a=tree;f=mod/quiz/report;h=b748acaba34655e2efe659475dec3e301541dec1;hb=HEAD The standard quiz reports code in git].
* [http://moodle.org/plugins/browse.php?list=category&id=13 Contributed quiz reports].

[[Category:Quiz]]
[[Category:Plugins]]

Overriding a renderer

2017-11-16T21:22:22Z

Ddelrio1986:

{{Template:Themes}}
This document explains renderers and how to override a renderer within a theme in order to achieve a unique look. It assumes you have a grounding in PHP and have read [[Themes]].

==An overview of renderers==

A renderer is a class that handles all of the output for a component of Moodle. It should contain no logic other than what is required to generate the display, and should be compartmentalised into functional chunks, each of which should be responsible for producing a widget or control used within the component. This output will vary depending on what the component is, for example the forum will have a method for displaying a forum post, displaying a thread (which most likely calls the forum post method), and displaying a search form.

These renderers are used as much as possible in Moodle and code is constantly being converted. As Moodle progresses, more of the code should be utilising renderers.

As well as the component renderers there is a core renderer, which is responsible for producing the display for many general things within Moodle, for example tables, action icons, and block regions.

Why use these renderers? They help developers separate the logic and the display when writing code and for theme designers they allow a means by which to take total control of the HTML that Moodle produces.

How do you do that you ask? By overriding them!

==Getting started==

We will create a test theme that extends the standard theme and does nothing other than override renderers.

1. Open your Moodle installation's theme directory and within it create a new directory called '''''overridetest'''''.
Within the newly created overridetest directory create a config.php file and add the following PHP to it:
<code php>
<?php

$THEME->name = 'overridetest';
$THEME->parents = array('standard', 'base');
</code>
This tells Moodle that our theme is called overridetest and that it extends both the base and standard themes.

2. The next step is to tell the theme that we want to override renderers. This is simple - we just tell Moodle which render factory we want our theme to use.

A render factory is a class that Moodle will use to find renderers. It is required by Moodle because renderers can exist in several locations within Moodle. These factories are what allow us to override only the renderers we want to rather than having to override them all.

3. To the bottom of the config.php add the following line:
<code php>
$THEME->rendererfactory = 'theme_overridden_renderer_factory';
</code>
This line tells Moodle that for this theme we want to use the '''theme_overridden_renderer_factory''', a special class tells Moodle to look for renderers first within the theme and then in all of the other default locations.

== Templates ==

As of Moodle 2.9 it is preferable to use [[Templates]] rather than generating HTML from php with html_writer.

==All about html_writer (Moodle 2.8 and older) ==

The html_writer class is used quite a bit and so it's important to understand what it is actually doing.

While you could write all of your HTML manually within a renderer method, it is encouraged to use the html_writer where possible to keep all renderer code similar and easily readable.

The following examples will introduce you to the html_writer, what some of it's core methods are, and what they produce.

'''html_writer::start_tag'''

This is used to produce an opening tag and takes two arguments - the first the tag to open and the second is the attributes to give the tag. The attributes are an array of key value pairs where the key is the attribute and the value is the value. Things such as class, id, and type are attributes that can be specified in this way.

<code php>
<?php echo html_writer::start_tag('div', array('class'=>'blah')); ?>
<div class="blah">

<?php echo html_writer::start_tag('table', array('class'=>'generaltable', 'id'=>'mytable')); ?>
<table class="generaltable" id="mytable">
</code>

'''html_writer::end_tag'''

This method is used to simply produce a closing tag for a tag that has been opened by html_writer::start_tag.

It takes just one argument the tag to close.
<code php>
<?php echo html_writer::end_tag('div'); ?>
</div>
<?php echo html_writer::end_tag('table'); ?>
</table>
</code>

'''html_writer::tag'''

This method takes three arguments and is the combination of start_tag and end_tag plus the inclusion of content.
<code php>
<?php echo html_writer::tag('div', 'I am some content to go into the string', array('class'=>'blah')); ?>
<div class="blah">I am some content to go into the string</div>
</code>

'''html_writer::empty_tag'''
The final method empty_tag is used to create a self closing tag. This is useful in situations such as producing image tags, or input fields.
It takes two arguments - tag and attributes, the same as start_tag.
<code php>
<?php echo html_writer::empty_tag('img', array('src'=>'myimage.png', 'alt'=>'This is my image')); ?>
<img src="myimage.png" alt="This is my image" />

<?php echo html_writer::empty_tag('input', array('type'=>'text', 'name'=>'afield', 'value'=>'This is a field')); ?>
<input type="input" name="afield" value="This is a field" />
</code>

==Our first renderer==

A note about autoloading and namespaces. Moodle 2.8 introduced support for autoloading for renderers. The examples in this page will work on older versions of Moodle, but the autoloaded alternatives are listed in notes for each section.

1. Create a file '''renderers.php''' within the root of the theme's directory. (This could also be renamed "classes/core_renderer.php to use auto-loading).

The first renderer that we will override is the core renderer for Moodle.

2. Within your renderers.php add the following:
<code php>
<?php

class theme_overridetest_core_renderer extends core_renderer {

}
</code>

What we have added is the class definition for our first renderer. Note:

* The name of the renderer is VERY important it is made up of three sections joined by underscores:
: '''''theme''''' : This will always be the same when overriding renderers from the theme.
: '''''overridetest''''' : This is of course the name of our theme, and should be the name of the theme the renderer is being overridden from.
: '''''core_renderer''''' : This is the renderer that we are overriding.
* The renderer should always extend the renderer it is overriding. This ensures we don't need to override every method the renderer offers.

With our renderer class defined it's now time to override our first display method.

In this case you we will override the '''''heading()''''' method that the core renderer has. This method is used to display a simple header in the page consisting of an h* tag (h2, h3, etc) and the heading itself.

The existing code for the function is as follows:
<code php>
/**
* Outputs a heading
* @param string $text The text of the heading
* @param int $level The level of importance of the heading. Defaulting to 2
* @param string $classes A space-separated list of CSS classes
* @param string $id An optional ID
* @return string the HTML to output.
*/
public function heading($text, $level = 2, $classes = 'main', $id = null) {
$level = (integer) $level;
if ($level < 1 or $level > 6) {
throw new coding_exception('Heading level must be an integer between 1 and 6.');
}
return html_writer::tag('h' . $level, $text, array('id' => $id, 'class' => renderer_base::prepare_classes($classes)));
}
</code>
Pretty simple really, it takes four standard arguments, and outputs a h* tag.

There are several important things to take away from this very simple bit of code:
* The first three lines are to check that $level is an integer between 1 and 6, this is because that integer gets written to the tag.
* The final line creates a h* tag with the arguments and returns it as a string.
* The output is returned rather than being echoed to the page. '''ALL''' renderer methods must do this.
* The html_writer class is used to generate the output rather than creating the string within the function. This is highly recommended for all renderer methods.

3. Let's override this method within our themes renderer. Within our method we will aim to wrap the h* tag in a div with a class name we choose and then add an image right before the h* tag is printed.

The following code does exactly this:
<code php>
public function heading($text, $level = 2, $classes = 'main', $id = null) {
$content = html_writer::start_tag('div', array('class'=>'headingcontainer'));
$content .= html_writer::empty_tag('img', array('src'=>$this->pix_url('headingpic', 'theme'), 'alt'=>'', 'class'=>'headingimage'));
$content .= parent::heading($text, $level, $classes, $id);
$content .= html_writer::end_tag('div');
return $content;
}
</code>
Looking at the code line by line:

<code php>
$content = html_writer::start_tag('div', array('class'=>'headingcontainer'));
</code>
Here we are opening a div and giving it a class of ''headingcontainer'' using the html_writer.

<code php>
$content .= html_writer::empty_tag('img', array('src'=>$this->pix_url('headingpic', 'theme'), 'alt'=>'', 'class'=>'headingimage'));
</code>
Again we are using the html_writer to do the work, however this time we are producing an img tag. You'll also notice the use of the pix_url function. Because our renderer is extending the core_renderer we can make use of all of its functions, pix_url being a useful one in this case.

<code php>
$content .= parent::heading($text, $level, $classes, $id);
</code>
Of course the other thing we can do in this case is still use the core_renderers heading method to produce the h* tag as we are just adding content around it.

<code php>
$content .= html_writer::end_tag('div');
</code>
The final thing to do is close the div that we opened on line one. Again we can do this with the html_writer.

Before testing it there are a few more things we need to do:

1. Create an image called headingpic.png and put it into a directory called pix located within your theme directory - ''/theme/overridetest/pix/headingpic.png''

2. Create a CSS file called overridetest.css within a directory called style within your theme directory - ''/theme/overridetest/style/overridetest.css''

3. Add into overridetest.css the following two lines of css.
<code css>
.headingcontainer .headingimage {float:left;margin-right:1em;}
.headingcontainer h2,
.headingcontainer h3,
.headingcontainer h4,
.headingcontainer h5,
.headingcontainer h6 {text-align:left;}
</code>
4. Add the following line to the bottom of the config.php file
<code php>
$THEME->sheets = Array('overridetest');
</code>

With that done if you now view a page within your Moodle installation you should see the difference.

[[image:overriding_a_renderer_01.jpg]]

As you can see from the clipping above heading now have our image next to the text and are left aligned.

==Finding renderers to override==

Identifying renderers and locating the files where they are located is necessary in order to override them.

Renderers should always be located in a file ending with '''renderer.php'''.

The renderer.php file should always be located in the base directory of a component, e.g.

* /webservice/renderer.php
* /mod/forum/renderer.php
* /mod/workshop/allocation/manual/renderer.php

or in the <plugindir>/classes/ folder when used with autoloading.

The only exception to this is the core renderer which is located in ''/lib/outputrenderers.php''.

There is also a routine way to name renderers much like the process for naming a theme's overriding renderer.

It should always be made up of the following three components joined by underscores:
# '''component''' This is the component the renderer belongs too, e.g. block, mod, or core.
# '''name''' This is the name of what ever the component is, e.g. forum, workshop, or wiki.
# '''renderer''' They should always be completed by the word renderer.

The following are examples of renderers currently in use within Moodle:
<code php>
class core_webservice_renderer {}
class mod_forum_renderer {}
class workshopallocation_manual_renderer {}
</code>

Again the only exception to this is the core renderer which is just '''core_renderer'''.

==Overriding a component's renderer==

Overriding a component's renderer works almost exactly the same as overriding a core renderer.

As a matter of fact there are quite some renderers that also have 'core' in their name, which can be a bit confusing.

One pitfall is that, in order to extend such a renderer, it's class definition must be loaded first (unless you use autoloading).

Below is an example of how to override the calendar renderer.

1. Within your renderers.php as created above add the line that loads the calendar's core_calendar_renderer class definition

<code php>
<?php

class theme_overridetest_core_renderer extends core_renderer {

}

include_once($CFG->dirroot . "/calendar/renderer.php");

</code>

2. Add the theme_overridetest_core_calendar_renderer class definition that extends core_calendar_renderer

<code php>
<?php

class theme_overridetest_core_renderer extends core_renderer {

}

include_once($CFG->dirroot . "/calendar/renderer.php");

class theme_overridetest_core_calendar_renderer extends core_calendar_renderer {

// place your overridden methods (functions) here.

}
</code>

Note again:

* The name of the renderer is VERY important it is made up of three sections joined by underscores:
: ''theme'': This will always be the same when overriding renderers from the theme.
: ''overridetest'': This is of course the name of our theme, and should be the name of the theme the renderer is being overridden from.
: ''core_calendar_renderer'': This is the renderer that we are overriding.
* The renderer should always extend the renderer it is overriding. This ensures we don't need to override every method the renderer offers.

With the theme_overridetest_core_calendar_renderer class defined you can now override the methods that need overriding.

For example to stop the button to add an event from being rendered:

<code php>
<?php

class theme_overridetest_core_renderer extends core_renderer {

}

include_once($CFG->dirroot . "/calendar/renderer.php");

class theme_overridetest_core_calendar_renderer extends core_calendar_renderer {

/**
* Disabled creation of the button to add a new event (Was: Creates a button to add a new event)
*
* @param int $courseid
* @param int $day
* @param int $month
* @param int $year
* @return string
*/
protected function add_event_button($courseid, $day=null, $month=null, $year=null) {
return '';
}

}
</code>

The same principle applies for all other renderers.

== Namespaces ==

Renderers can also be used with code that uses namespaces. When creating or overriding new renderers with namespaces, be sure to use "output" as the second level namespace to comply with the rules for namespaces. Non-namespaced renderers can be overridden by a namespaced renderer and vice-versa - this leads to a complex search strategy when looking for overridden renderers.

For example: the renderer for the component "mod_assign" with subtype "custom" and target "cli" could exist in any of these classes (listed in priority order):

* theme_child\\output\\mod_assign\\custom_renderer_cli
* theme_child\\output\\mod_assign\\custom\\renderer_cli
* theme_child_mod_assign_custom_renderer_cli
* theme_parent\\output\\mod_assign\\custom_renderer_cli
* theme_parent\\output\\mod_assign\\custom\\renderer_cli
* theme_parent_mod_assign_custom_renderer_cli
* mod_assign\\output\\custom_renderer_cli
* mod_assign\\output\\custom\\renderer_cli
* mod_assign_custom_renderer_cli
* theme_child\\output\\mod_assign\\custom_renderer
* theme_child\\output\\mod_assign\\custom\\renderer
* theme_child_mod_assign_custom_renderer
* theme_parent\\output\\mod_assign\\custom_renderer
* theme_parent\\output\\mod_assign\\custom\\renderer
* theme_parent_mod_assign_custom_renderer
* mod_assign\\output\\custom_renderer
* mod_assign\\output\\custom\\renderer
* mod_assign_custom_renderer

For more examples of possible class names for renderers see lib/tests/outputfactories_test.php

==See also==

* [[Adding courses and categories to the custom menu]]
* [[Output renderers]]
* [[Automatic_class_loading]]
* [[Coding_style#Namespaces]]

Page API

2012-08-20T18:25:27Z

Ddelrio1986: /* Overview */

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==FAQs==

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

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

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

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

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

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

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

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

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

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

==See also==

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

[[Category:API]]

Access API

2012-08-20T18:18:05Z

Ddelrio1986:

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

==Overview==

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

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

==How to define new capabilities in plugins==

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

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

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

It is necessary to bump up plugin version number after any change in db/access.php.

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

==Useful functions and classes==

===Context fetching===

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

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

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

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

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

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

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

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

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

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

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

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

===Enrolment functions===

Since Moodle 2.2 there is a new concept of user enrolments, they are fully independent from the roles and capabilities, see [[Enrol API]] for more information.

Capabilities are very often used in combination with enrolment status.

====is_enrolled()====
Is user participating in the course? Returns true for students and teachers, false for administrators and other managers. User enrolments can be either active or suspended, suspended users can not enter the course (unless there is some kind of guest access allowed) and are usually hidden in the UI.

<code>
function is_enrolled(context $context, $user = null, $withcapability = '', $onlyactive = false)
</code>

Good example is choice module where we have one slot for each participant, people that are not enrolled are not allowed to vote <code>is_enrolled($context, $USER, 'mod/choice:choose')</code>. Another example is assignment where users need to be enrolled and have capability to submit assignemnts <code>is_enrolled($this->context, $USER, 'mod/assignment:submit')</code>.

====get_enrolled_users()====

Sometimes you need to know the list of users that can participate in some activity.

<code>
function get_enrolled_sql(context $context, $withcapability = '', $groupid = 0, $onlyactive = false)
function get_enrolled_users(context $context, $withcapability = '', $groupid = 0, $userfields = 'u.*', $orderby = '', $limitfrom = 0, $limitnum = 0)
function count_enrolled_users(context $context, $withcapability = '', $groupid = 0)
</code>

For example you want to know who is able to summit assignment right now:
<code>
$submissioncandidates = get_enrolled_users($modcontext, 'mod/assignment:submit', 0, true);
</code>

The assignment module needs to hold data for all users that are enrolled including the users with suspended enrolments and without any roles. Module developers may decide to purge all user data when user is fully unenrolled.

SQL select from get_enrolled_sql() is often used for performance reasons - you can use it in joins to get specific information for only enrolled users.

===Other related functions===

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

====require_login()====

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

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

====require_course_login()====

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

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

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

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

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

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

====get_users_by_capability()====

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

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

[[Category:API]]

Access API

2012-08-20T18:17:27Z

Ddelrio1986:

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

==Overview==

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

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

==How to define new capabilities in plugins==

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

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

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

It is necessary to bump up plugin version number after any change in db/access.php.

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

==Useful functions and classes==

===Context fetching===

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

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

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

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

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

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

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

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

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

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

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

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

===Enrolment functions===

Since Moodle 2.2 there is a new concept of user enrolments, they are fully independent from the roles and capabilities, see [[Enrol API]] for more information.

Capabilities are very often used in combination with enrolment status.

====is_enrolled()====
Is user participating in the course? Returns true for students and teachers, false for administrators and other managers. User enrolments can be either active or suspended, suspended users can not enter the course (unless there is some kind of guest access allowed) and are usually hidden in the UI.

<code>
function is_enrolled(context $context, $user = null, $withcapability = '', $onlyactive = false)
</code>

Good example is choice module where we have one slot for each participant, people that are not enrolled are not allowed to vote <code>is_enrolled($context, $USER, 'mod/choice:choose')</code>. Another example is assignment where users need to be enrolled and have capability to submit assignemnts <code>is_enrolled($this->context, $USER, 'mod/assignment:submit')</code>.

====get_enrolled_users()====

Sometimes you need to know the list of users that can participate in some activity.

<code>
function get_enrolled_sql(context $context, $withcapability = '', $groupid = 0, $onlyactive = false)
function get_enrolled_users(context $context, $withcapability = '', $groupid = 0, $userfields = 'u.*', $orderby = '', $limitfrom = 0, $limitnum = 0)
function count_enrolled_users(context $context, $withcapability = '', $groupid = 0)
</code>

For example you want to know who is able to summit assignment right now:
<code>
$submissioncandidates = get_enrolled_users($modcontext, 'mod/assignment:submit', 0, true);
</code>

The assignment module needs to hold data for all users that are enrolled including the users with suspended enrolments and without any roles. Module developers may decide to purge all user data when user is fully unenrolled.

SQL select from get_enrolled_sql() is often used for performance reasons - you can use it in joins to get specific information for only enrolled users.

===Other related functions===

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

====require_login()====

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

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

====require_course_login()====

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

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

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

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

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

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

====get_users_by_capability()====

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

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

[[Category:API]]

Web services (2.0 onwards)

2011-05-06T18:28:54Z

Ddelrio1986: /* Overview */

== Adding web-services to a plugin (Moodle 2.0) ==

=== Overview ===

Web services are built and provided by the 'externallib.php' file in the modules (or areas) directory. In this file is kept the external class that extends the 'external_api' class and provides definitions for the incoming message format, outgoing message format and the worker functions for each service.

Extract from courses externallib.php:
defined('MOODLE_INTERNAL') || die;

require_once("$CFG->libdir/externallib.php");

class moodle_course_external extends external_api {
}

Each web-service requires three methods:
1. A parameters function (appended with _parameters).
2. A return parameters function (appended with _returns).
3. And the worker function itself.

For example the 'get_courses' service has the following three methods:
//Provides a description of the parameters
public static function get_courses_parameters () {}

//Does the work of collecting the requested data, creating adding deleting records etc.
public static function get_courses ($options) {}

//Provides a description of the structure for the data returned by get_courses (the worker function).
public static function get_courses_returns () {}

== Making a web-service (get_course_activities ==

For this tutorial we are going to create a local plugin that extends the services available through the core course web-services. For information on how to setup a local plugin see []

This tutorial creates a get_course_activities web-service.

To create this new service we will need to create the static functions in the externallib.php file under /course and will need to add several database entries.

=== What should the call do? A little planning ===

With this web-service we want to be able to ask moodle what activities a course has. To do this we will need to provide the web-service call with the course id that we want the activities returned for.

1. First we need to create the parameters function. We could start with any of them however it will be easier to define the inputs and outputs before moving onto the worker.
//First draft
public static function get_course_activities_parameters () {
//The _parameters method only has one objective, to return a description of the input data structure.
return new external_function_parameters();
}

We aren't done with this method yet.

A quick explanation of external_function_parameters is in order. (At the moment this explanation is guess work). The external_function_parameters is a wrapper class for the external_single_structure class. You must return an external_function_parameters class in the _parameters function. If you don't Moodle will throw an 'Invalid parameters description' error.

2. Next add the expected input structure to the external_function_parameters object.

//Second draft
public static function get_course_activities_parameters () {
return new external_function_parameters (
array(
'courseid'=> new external_value(PARAM_INT, 'id of the course')
)
);
}

Here we have added a single external_single_structure implicitly through the external_function_parameters object. We don't need anything more spectacular as we only want to provide one piece of data, the course id.

To do this we add a named array with one key, value pair. The key is set to the name of the field: 'courseid' and the value is set to an external_value object with a PARAM_INT type.
'courseid'=> new external_value(PARAM_INT,'id of the course')

This completes the _parameters function for the web-service. Next we can move on and define what we want to see in return.

3. Creating the _returns function (get_course_activities_returns)

Differently to the _parameters function the _returns function doesn't require a specific object as its primary return value. Instead you can choose from any of the objects that inherit the external_description class.

As a result we should start by taking a look at the kind of data and therefore the kind of data structure that we are going to expect returned to use from the service. We expect that a single course will have many activities and we aren't asking for activities from more than one course. Each activity will have a set of fields that contain the activity information such as id and type.

This should give us a starting point roughly like this:
//
public static function get_course_activities_returns () {
return new external_multiple_structure (
new external_single_structure ( //This is used to represent a single activity.
array(
), 'activity') //The description of what this element represents.
)
}

We have a basic outline of the top level data structures that we want returned. This was fairly simple as the above structure is what you're likely to need anytime you want to return a list of objects or 'items'.

4. Adding a description of the activity fields to be returned.

Now we need to define what each activity item should look like. In reality when you develop a web-service you may switch between defining the return structure in the _returns function and writing the worker function (i.e what the author needed to do to write this tutorial). We are going to concentrate just on finishing this function so that the description of the fields is in one place and we can follow a single train of thought.

This is the basic data structure we are going to use. There are many more fields within related to each activity that we could add, but for the moment this will do.

array(
'id'=> new external_value(PARAM_INT,'The id of the activity'),
'name' => new external_value(PARAM_TEXT,'The name of the activity'),
'mod' => new external_value(PARAM_ALPHANUM,'The module that provides this activity.')
)

This is enough of a structure to return an interesting result. It's time to move on to the worker function itself.

5. The worker function.

This is where the data gathering is done. The previous two functions mean that we can leave Moodle to do the heavy lifting when it comes time to make and send requests. The worker function just needs to get the data we are after and return it in a php data structure that matches the template we've outlined in the _return function.

public static function get_course_activities ($courseid) {
global $CFG;
require_once($CFG->dirroot . "/course/lib.php");

$params = self::validate_parameters(self::get_course_activities_parameters(),
array('courseid' => $courseid)
);

//retrieve courses
if (!key_exists('courseid', $params)) { //Will probably need to chuck a narny.
throw new moodle_exception(get_string('nocourseid', 'webservice', $exceptionparam));
} else {
$activities_raw = get_array_of_activities($params['courseid']);

$activities = array();

foreach($activities_raw as $key => $activity_raw) {
$activity = array();
$activity["id"] = $activity_raw->id;
$activity["name"] = $activity_raw->name;
$activity["mod"] = $activity_raw->mod;

$activities[] = $activity;
}

return $activities;
}
}

This is everything we need to make the whole web service work, but perhaps we should break it down and look at it.

First some of the basics

global $CFG;
require_once($CFG->dirroot . "/course/lib.php");

Instead of re-inventing the wheel and working out how collect the data for ourselves we are essentially going to wrap the get_array_of_activities function provided by the course library. It takes care of making the right database calls and putting the information together. It will also mean that the information is returned consistently the same whether you are using the internal call or the external call (web service).

Next we will validate the incoming data. This is where the _parameters method comes in. To validate we call the validate_parameters function that is provided for free by extending the external_api class. We provide to it the _parameters function for the web service being created and the incoming data. In this case in a format to match the top level structure that we defined in _parameters function.

$params = self::validate_parameters(self::get_course_activities_parameters(),
array('courseid' => $courseid)
);

From this call we are provided with the $params data structure. This will provide a structure that matches the structure set up in the _parameters function.

//retrieve courses
if (!key_exists('courseid', $params)) { //Will probably need to chuck a narny.
throw new moodle_exception(get_string('nocourseid', 'webservice', $exceptionparam));
} else {
//Here we will place the work code that provides the activity data.
}

If we don't have a courseid value we will instead return with a moodle_exception. If everything is fine proceed to to collecting the activity information. Inside the if statement we add this:

$activities_raw = get_array_of_activities($params['courseid']);

$activities = array();

foreach($activities_raw as $key => $activity_raw) {
$activity = array();
$activity["id"] = $activity_raw->id;
$activity["name"] = $activity_raw->name;
$activity["mod"] = $activity_raw->mod;

$activities[] = $activity;
}

return $activities;

In essence this code calls the course function get_array_of_activities and then processes the result. The structure to be built is an array of named arrays. To do this we create the $activities array and then loop through the object we received back. For each entry we create another array (convenience of php) and add named entries to match the fields in the _returns function. In this case we add the 'id', 'name' and 'mod' fields.

Once done we then append the $activity array to the list of others we are collecting and final return them.

At this point the web-service is ready to go except for the database entry that will tell moodle that we have a new web service available and where to find it.

=== Adding the database entry ===

For now we will do this the hard (and not good) way.

Moodle web-services are described in the external_functions (mdl_external_functions) table.

The table has six fields that we need to fill in:
* name - This is the name of the service and the way it will be referred to by moodle. Consider it the public name
* classname - This is the name of the class that provides this method. In this case moodle_course_external
* methodname - The name of the method: In this case get_course_activities. Moodle will work out the _returns and _parameters
* classpath - The name of the file that the class (referred to in classname) can be found in. The path is relative to the moodle root. In this case: 'course/externallib.php'. externallib.php is the default for these services and all of the core services are found here so stick with it.
* component - all the core services belong to 'moodle'. This (I'm currently guessing) refers to the component that is providing the services. I.E. If you're not contributing to core avoid using 'moodle' here.
* capabilities - These are the capabilities users will require to successfully use this service.

(NB: I'm sure there has to be a better way than to add the db entries directly)

As a result we get the following query for this service:

insert into mdl_external_functions (name,classname,methodname,classpath,component,capabilities) values
('moodle_course_get_course_activities','moodle_course_external','get_course_activities',
'course/externallib.php','moodle','moodle/course:view,moodle/course:viewhiddencourses')

And from here we are done. You can now find and configure the new web-service through the admin area.

== Of course there is testing ==

It would appear that the web-service tests in Moodle aren't able to read and test new ones without code additions. In which case try this. Fill in the blanks and run this in a php environment.

<?php

error_reporting(E_ALL);
$s = new SoapClient("http://add-your-moodle-url/webservice/soap/server.php?wstoken=add-your-ws-token&wsdl=1");
var_dump($s->moodle_course_get_course_activities(--add a course id--));

?>

== Data Structure Descriptors ==

In order to keep a little of the technical stuff out of the tutorial and provide an overview of the data structures:

=== external_single_structure ===

This method translates to a named array or hash with a subset of elements that provide the requested data.

Because of this you can imagine this to be the equivalent of a named array, hash or object wrapper.

i.e. external_single_structure = hash

=== external_multiple_structure ===

external_multiple_structure = array

=== external_value ===

external_value object is used to specify a data field. It requires two values, a type constant (see below) and a description string.

==== Available type constants ====

* PARAM_INT : specifies an integer data type.
* PARAM_TEXT : (description required).
* PARAM_RAW : (description required).

XMLDB introduction

2007-04-30T14:48:15Z

Ddelrio1986: mispelling of the word module...it was modude

[[XMLDB Documentation|XMLDB Documentation]] > Introduction
----
__NOTOC__
One of the main upcoming features in Moodle 1.7 will be its ability to work with some more [[wikipedia:RDBMS|RDBMS]] ([[wikipedia:MSSQL|MSSQL]] and [[wikipedia:Oracle database|Oracle]]) while maintaining everything working properly with both [[MySQL]] and [[PostgreSQL]]. As Moodle core uses [http://adodb.sourceforge.net/ ADOdb] internally, this possibility has been present since the beginning and, with the current maturity of the project (5 years old baby!), this can be a good moment to sort all this out.

Initially, all our tests and preliminary work was to inspect how [http://adodb.sourceforge.net/ ADOdb] was doing its work, and how we could mix together all those 4 RDBMS, whose SQL dialects, although pretty similar, have some differences and idiosyncrasies that force us to do some important changes to our current database code (formerly '''datalib.php''') and how it's used by the rest of Moodle.

All the changes to be performed, which primary objective is to enable Moodle to work with more RDBMS must be be filled following the next non-functional requirements:

* '''Provide one layer (new) for DB creation/upgrade''' ([[wikipedia:Data_Definition_Language|DDL]]): With this, developers will create their structures in one neutral form, independent of the exact implementation to be used by each RDBMS.

* '''Provide one layer (existing) for DB handling''' ([[wikipedia:Data_Manipulation_Language|DML]]): With this, developers will request/store information also in one nuetral form, independent of the RDBMS being used.

* '''Easy migration path from previous versions''': The current installation/upgrade system will work until, at least, Moodle 2.0, allowing 3rd part developers to migrate along the time to the new system.

* '''Simple, usable and effective''': Until now, the way to upgrade Moodle has been really cool and it has worked pretty fine since the beginning, but it has forced developers to maintain at least two installation and two upgrade scripts for each module/plugin. The new alternative will have only one file to install and one file to upgrade (per module/plugin too), reducing the possibility of mistakes in an high degree.

* '''Conditional code usage must be minimised''': Database libraries must accept 99% of potential SQL sentences, building/transforming them as necessary to work properly under any RDBMS. The number of places using custom (per DB) code should be minimum.

* '''Well documented''': All the functions defined, both at DML and DDL level must be well documented, helping the developer to find and use the correct one in each situation.

== The Stack ==

The next stack shows how Moodle 1.7 code will interact with underlying RDBMS. It will help us to understand a bit more what we are trying to do and will explain some of the points related in the Roadmap (below in this page).

[[Image:MoodleDBStack.png|center]]

Moodle code will use two ''languages'' to perform its DB actions:

* '''XMLDB neutral description files''': To create, modify and delete database objects (DDL: create/alter/drop tables, fields, indexes, constraints...). It consists in a collection of validated, standard, XML files. They will be used to define all the DB objects. New for 1.7.
* '''Moodle SQL neutral statements''': To add, modify, delete and select database information (DML: insert/update/delete/select records). To modify for 1.7.

Please note the '''neutral''' keyword used in the expressions above. It means that both '''languages''' will be 100% the same, independently of the underlying RDBMS being used. And this must be particularly true for the XMLDB part. Point.

Obviously it's possible that in the SQL part we found some specialised queries (using complex joins, regular expressions...) that will force us to do some '''Exceptions'''. Well, they can exist (in fact, they exist), but we always must try to provide an alternate path to minimise them using neutral statements and standard libraries.

Each one of the '''languages''' above will use its own library to do the work:

* '''Moodle DDL Library''' ([[DDL functions|ddllib.php]]): Where all the functions needed to handle DB objects will exist. This library is new for 1.7 and will provide developers with an high level of abstraction. As input it will accept some well defined objects and actions and it will execute the proper commands for the RDBMS being used.
* '''Moodle DML Library''' ([[DML functions|dmllib.php]]): Where all the functions needed to handle DB contents will exist. This library is new for 1.7, although its contents are, basically, functions currently present in '''datalib.php''' (moved from there). All those DML functions will offer cross-db support for insert/update/delete/select statements using a common behaviour.

Also note that '''datalib.php''' continues present in the schema above. It will contain all the functions that haven't been moved to the new '''ddllib.php''' and '''dmllib.php''' libraries. Only some common functions will remain there, and this situation will disappear (it's considered a legacy library) in upcoming '''Moodle''' releases (after 1.7) by moving all those functions to their proper library (course/lib.php, user/lib.php....).

Both this libraries (plus the small '''Exceptions''' bar) will perform all their actions using the '''ADOdb Database Abstraction Library for PHP''' that will receive all the request from them, communicate with the DB ('''MySQL''', '''PostgreSQL''', '''Oracle''' or '''SQL*Server'''), retrieve results and forward them back to originator library.

== The process ==

This section points to the main areas of information about the '''process of design and implementation''' of the new XMLDB layer:

* [[XMLDB Roadmap|Roadmap]]: Where the whole process is defined. It has been splitted in small chuncks to be performed and tested easily. Also, such documents should be used to track what's done and what's pending following some easy nomenclature.

* [[XMLDB Problems|Problems]]: A comprensive list of issues that need to be determined/solved prior to incorporate them to the [[XMLDB Roadmap|roadmap]].

== The documentation ==

This section points to the '''main documentation index''' about the implemented XMLDB:

* [[XMLDB Documentation|Documentation]]: Where you'll find quick links to different parts of the XMLDB documentation.

==See also==

=== XMLDB related ===

* [[XMLDB preliminary links|XMLDB preliminary links]] - A collection of links about general info, searched and analysed at the initial stages of the project
* [[XMLDB preliminary notes|XMLDB preliminary notes]] - A collection of notes collected in the early stages of this project, pointing both to some changes required and some problems to solve.

=== Database related ===

* [[DDL functions|DDL functions]] - Documentation for all the Data Definition Language (DDL) functions available inside Moodle.
* [[DML functions|DML functions]] - Documentation for all the Data Manipulation Language (DML) functions available inside Moodle.

[[Category:XMLDB]]

[[zh:开发:XML数据库计划]]