MoodleDocs - User contributions [en]

Page API

2016-05-09T20:37:54Z

Vaibspidy: /* Page layout */

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. 
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. 
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. 
It can be set in the following manner:

<code php>
$PAGE->set_url(new moodle_url('/path/to/your/file.php', array('key' => 'value', 'id' => 3)));
$PAGE->set_url('/path/to/your/file.php', array('key' => 'value', 'id' => 3));
$PAGE->set_url('/path/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 used by many 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.0 and 2.1
$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. 
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. 
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(). 
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 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. 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. 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'));
</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. 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. 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. 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. 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. This allows you to have several pages that all point to the same docs page rather than requiring a docs page for each. 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. 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. 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. 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. This is rarely needed but can be useful if you need to automatically refresh the likes of a chat page, or news feed. 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. On some pages this functionality is not desired and can be stopped by calling this method and using false as the first argument. 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. 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. 
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. 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. 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->navigation;</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

2016-05-09T19:29:35Z

Vaibspidy: /* Enrollment functions */

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

==Overview==

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

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

==How to define new capabilities in plugins==

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

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

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

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

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

==Useful functions and classes==

===Context fetching===

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

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

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

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

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

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

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

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

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

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

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

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

===Enrollment functions===

See [[Enrolment API]].

===Other related functions===

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

====require_login()====

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

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

====require_course_login()====

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

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

These functions were previously needed for limiting of access of special accounts. It is usually not necessary anymore, 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 enrollment 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_enrollments 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 enrollment plugin

====get_users_by_capability()====

This method returns list of users with given capability, it ignores enrollment 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

2016-05-09T19:05:19Z

Vaibspidy:

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

==Overview==

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

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

==How to define new capabilities in plugins==

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

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

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

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

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

==Useful functions and classes==

===Context fetching===

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

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

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

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

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

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

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

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

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

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

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

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

===Enrollment functions===

See [[Enrollment API]].

===Other related functions===

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

====require_login()====

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

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

====require_course_login()====

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

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

These functions were previously needed for limiting of access of special accounts. It is usually not necessary anymore, 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 enrollment 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_enrollments 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 enrollment plugin

====get_users_by_capability()====

This method returns list of users with given capability, it ignores enrollment 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]]

Git for developers

2016-04-11T08:53:30Z

Vaibspidy:

This document is for helping you get started on Moodle development with Git. For further details of Git, see [[:Category:Git]].

== General workflow ==

'''A reasonable knowledge of the Git basics is a good idea before you start to use it for development. If you are new to Git, you are encouraged to go to 'See also' for some more general reading.'''

[[image:git-pushpull-model.png|right|thumb|400px|Moodle development workflow with Git]]
Detailed explanation of the workflow can be found in the [[Process]] page. In short, the Moodle development with Git looks like this:

* You as the contributor commit changes into your personal repository at your computer
* You push the changes into your public repository and publish links to your changes in the Moodle Tracker
* You request a peer review of your code from another developer
* When peer reviewer is happy they submit issue for integration
* Moodle integrators pull the changes from your public repository and if they like them, they put them into Moodle integration repository
* The integrated change is tested and finally pushed into Moodle production repository
* You update your local repository with all changes from the production repository and the next cycle may start again

This workflow runs in roughly weekly cycles. The integration happens on Monday and Tuesday and the testing on Wednesday. On Thursday (or Friday if testing takes too long), the production repository moodle.git is usually updated with changes from the last development week.

Most Moodle developers have their public repositories hosted at [http://github.com/ Github]. Alternatively you may want to try [http://gitorious.org Gitorious] or the legendary [http://repo.or.cz repo.or.cz]. In the examples in this guide we assume you'll set up your public repository at Github.

When you first register on tracker you can not assign issues to yourself or send them for peer review. You will be added to the developers group after your first bug fix is integrated. Before that just comment on the issue with a link to your branch and component lead or another developer will send issue for peer review for you.

== Installing Git on your computer ==

Install Git on your computer. Most Linux distributions have Git available as a package to install. On Debian/Ubuntu, type ''''sudo apt-get install git'''' on the terminal. If you are on Mac, [http://code.google.com/p/git-osx-installer/ git-osx-installer] installs it in a few clicks.

Immediately after the installation, set your name and contact e-mail. The name and e-mail will become part of your commits and they can't be changed later once your commits are accepted into the Moodle code. Therefore we ask contributors to use their real names written in capital letters, eg "John Smith" and not "john smith" or even "john5677".

git config --global user.name "Your Name"
git config --global user.email yourmail@domain.tld

Unless you are the repository maintainer, it is wise to set your Git to not push changes in file permissions:

git config --global core.filemode false

Also, it's recommended to verify that the your git installation is not performing any transformation between LFs and CRLFs. All Moodle '''uses only LFs''' and you should '''fetch/edit and push''' it that way (may need to configure your editor/IDE too). Note that having any "magic" enabled is known to cause [[Common unit test problems#The_test_file_.22evolution.test.22_should_not_contain_section_named_.22.5Blots_of_content.5D.22|problems with unit tests]] execution. So we recommend you to set:

git config --global core.autocrlf false

== Setting-up the public repository ==

1. Go to [http://github.com/ Github] and create an account.

2. Go to the [http://github.com/moodle/moodle official Moodle Github repository] and click on the Fork button. You now have your own Github Moodle repository.

3. Now you need to set up your SSH public key, so you can push to your Github Moodle repository from your local Moodle repository. On Mac you can go on this [http://help.github.com/mac-key-setup/ Github help page]. If you are on another system, go to your Github administration page, to the section SSH Public Keys, and you should see a link to a help page. Done? Good! That was the most difficult part!

== Setting-up the local repository at your computer ==

Create a local clone repository of your Github repository. In a terminal:

git clone git://github.com/YOUR_GITHUB_USERNAME/moodle.git LOCALDIR

(or: git clone git@github.com:YOUR_GITHUB_USERNAME/moodle.git LOCALDIR)

This command does several jobs for you. It creates a new folder, initializes an empty Git repository in it, sets your Github repository as the remote repository called 'origin' and makes a local checkout of the branch 'master' from it. The important point to remember now is that your Github repository is aliased as 'origin' for your local clone.

Note that the format of the URL here is important. In the first example, the URL starts "git://github.com" and this will give read-only access to the repository at github.com. If you use this URL, the "git push origin" command that appears later in this document will not work. Therefore, if you want to be able to update the "origin" repository, you should use the URL that starts "git@github.com", i.e. the second of the two "git clone" commands given above. This will give you read and write access to the repository on github.com.

== Keeping your public repository up-to-date ==

[[image:git-sync-github.png|right|thumb|400px|Fetching changes from upstream and pushing them to github]]
Your fork at Github is not updated automatically. To keep it synced with the upstream Moodle repository, you have to fetch the recent changes from the official moodle.git and push them to your public repository. To avoid problems with this it is strongly recommended that you never modify the standard Moodle branches. ''Remember: never commit directly into master and MOODLE_xx_STABLE branches.'' In other words, always create topic branches to work on. In Gitspeak, the master branch and MOODLE_xx_STABLE branches should be always fast-forwardable.

To keep your public repository up-to-date, we will register remote repository git://git.moodle.org/moodle.git under 'upstream' alias. Then we create a script to be run regularly that fetches changes from the upstream repository and pushes them to your public repository. Note that this procedure will not affect your local working directory.

To register the upstream remote:

cd moodle
git remote add upstream git://git.moodle.org/moodle.git

The following commands can be used to keep the standard Moodle branches at your Github repository synced with the upstream repository. You may wish to store them in a script so that you can run it every week after the upstream repository is updated.

#!/bin/sh
git fetch upstream
for BRANCH in MOODLE_{19..27}_STABLE master; do
git push origin refs/remotes/upstream/$BRANCH:$BRANCH
done

=== How it works ===

The git-fetch command does not modify your current working dir (your checkout). It just downloads all recent changes from a remote repository and stores them into so called remote-tracking branches. The git-push command takes these remote-tracking branches from upstream and pushes them to Github under the same name. Understanding this fully requires a bit knowledge of Git internals - see gitrevisions(7) man page.

Note there is no need to switch the local branch during this. You can even execute this via cron at your machine. Just note that the upstream repository updates typically just once a week.

=== New branches ===

Occasionally, moodle.org will create a new branch that does not exist in your public (e.g. Github.com) repository. If you try to push this new branch, you will see an error such as the following:

error: unable to push to unqualified destination: MOODLE_99_STABLE
The destination refspec neither matches an existing ref on the remote
nor begins with refs/, and we are unable to guess a prefix based on the source ref.
error: failed to push some refs to 'git@github.com:YOUR_GITHUB_USERNAME/moodle.git'

In the above example, "MOODLE_99_STABLE", is the name of the new branch that does not exist in your public repository. To fix the error, you need to create the new branch on your public repository, using the following commands, replacing "MOODLE_99_STABLE" with the name of the new branch you wish to create:

git checkout MOODLE_99_STABLE
git push origin MOODLE_99_STABLE:MOODLE_99_STABLE

The above code will create a new copy of the "MOODLE_99_STABLE" branch in your local repository. If you do not need to keep a local copy of the new branch - and probably you do not need it, you then can remove it from your local repository as follows:

git checkout master
git branch -D MOODLE_99_STABLE

== Preparing a patch ==

As said earlier at this page, you never work on standard Moodle branches directly. Every time you are going to edit something, switch to a local branch. Fork the local branch off the standard branch you think it should be merged to. So if you are working on a patch for 1.9 or 2.0, fork the branch off MOODLE_19_STABLE or MOODLE_20_STABLE, respectively. Patches for the next [[Moodle versions|major version]] should be based on the master branch.

git checkout -b MDL-xxxxx-nasty-bug origin/master

Note that if you forget to specify the starting point, the branch is based on the currently checked-out branch. It may not be what you want. It is recommended to always specify the starting point.

To check the current branch, run

git branch

The current branch is highlighted.

Now go and fix the issue with your favorite IDE. Check the status of the files, view the change to be committed and finally commit the change:

vim filename.php
git status
git diff
git commit -a

Note that this is safe as the commit is recorded just locally, nothing is sent to any server yet (as it would in CVS). To see history of the commits, use

git log

Once your local branch contains the change (note that it may consists of several patches) and you are happy with it, publish the branch at your public repository:

git push MDL-xxxxx-nasty-bug

Because we did not specify explicit remote repository, the 'origin' is used. Because we did not specify the branch to push, the Git will use the current branch and push it to the remote repository under the same name (by default, this is a subject of your configuration. See push.default config variable).

Now as your branch is published, you can ask Moodle core developers to review it and eventually integrate it into the standard Moodle repository.

=== Changing commit message, reordering and squashing commits ===

It often happens that you made a mistake in your patch or in the commit message and helpful CiBot pointed it out for you. You can "rewrite the history" and change the existing commits.

Option 1. Reset all the changes in the branch and commit again.

git reset --mixed origin/master

Now all your changes are still present but all commits on top of "master" branch are gone. You can create a new commit

Option 2. Discover '''git rebase''' - this is a powerful tool to change the sequence of commit, change the commit messages, squash commits, etc. We will not cover it here, there are many articles in the Internet about it.

Whatever option you chose, you have "rewritten the history" and you can not simply push the changes to github again because they would need to overwrite the commits that were already pushed. If you try "git push MDL-xxxxx-nasty-bug" you will get an error message suggesting you to force push. To force push the changed commits use:

git push -f MDL-xxxxx-nasty-bug

=== Checking if a branch has already been merged ===

After some time contributing to Moodle you would have a lot of branches both in your local repository and in your public repository. To prune their list and delete those that were accepted by upstream, use the following

git fetch upstream (1)
git branch --merged upstream/master (2)
git branch --merged upstream/MOODLE_20_STABLE (3)

The command (1) fetches the changes from your upstream repository at git.moodle.org (remember that git-fetch does not modify your working dir so it is safe to run it whenever). Command (2) and (3) print all branches that are merged into the upstream master branch and MOODLE_20_STABLE branch, respectively. To delete these local branches, use

git branch -d MDL-xxxxx-accepted-branch

The similar approach can be used to check the branches published at your origin repository at github.com

git fetch origin (1)
git fetch upstream
git branch -r --merged upstream/master (2)
git branch -r --merged upstream/MOODLE_20_STABLE (3)

The command (1) makes sure that you have all your branches from github.com recorded as the remote tracking branch locally. Commands (2) and (3) work the same as in the previous example but they list remote tracking branches only ([http://www.kernel.org/pub/software/scm/git/docs/git-branch.html see -r param]). To delete a branch at github.com, use

git push origin :MDL-xxxx-branch-to-delete

This syntax may look weird to you. However it is pretty logical. The general syntax of the git-push command is

git push <repository> <source ref>:<target ref>

so deleting a remote branch can be understood as pushing an "empty (null) reference" to it.

== Peer-reviewing someone else's code ==

To review a branch that someone else pushed into their public repository, you do not need to register a new remote (unless you work with such repository frequently, of course). Let us imagine your friend Alice pushed a work-in-progress branch called 'wip-feature' into her Github repository and asked you to review it. You need to know the read-only address of the repository and the name of the branch.

git fetch git://github.com/alice/moodle.git wip-feature

This will download all required data and will keep the pointer to the tip of the wip-feature branch in a local symbolic reference FETCH_HEAD. To see what's there on that branch, use

git log -p FETCH_HEAD

To see how a particular file looks at Alice's branch

git show FETCH_HEAD:admin/blocks.php

To create a new local branch called 'alice-wip-feature' containing the work by Alice, use

git checkout -b alice-wip-feature FETCH_HEAD

To merge Alice's work into your current branch:

git merge FETCH_HEAD

To see what would be merged into the current branch without actually modifying anything:

git diff ...FETCH_HEAD

Once you are all set and reviewing code, this [[Peer_reviewing_checklist|checklist]] should prove to be useful.

== Rebasing a branch ==

Rebasing is a process when you cut off the branch from its current start point and transplant it to another point. Let us assume the following history exists:

A---B---C topic
/
D---E---F---G master

From this point, the result of the command:

git rebase master topic

would be:

A'--B'--C' topic
/
D---E---F---G master

and would end with 'topic' being your current branch.

You may be asked to rebase your branch submitted for the integration if the submitted branch was based on an outdated commit. The typical case is if you create a new branch as a fork off the upstream master branch on Tuesday. Then on Wednesday, the upstream master branch grows as all changes from the last integration cycle are merged to it. To make diff easy on Github for next weekly pull request review, you want to rebase your branch against the updated master.

git rebase master MDL-xxxxx-topic-branch

Note that rebasing effectively rewrites the history of the branch. '''Do not rebase the branch if there is a chance that somebody has already forked it and based their own branch on it.''' For this reason, many Git tutorials discourage from rebasing any branch that has been published. However in Moodle, all branches submitted for integration are potential subject of rebase (even though we try to not to do it often) and you should not base your own branches on them.

=== Conflicts during rebase ===

During the rebase procedure, conflicts may appear. git-status commands reports the conflicted files. Explore them carefully and fix them in your editor (like you would do with CVS). Then add the files with 'git add' command and continue.

vim conflicted.php
git add conflicted.php
git rebase --continue

== Applying changes from one branch to another ==

Most bugs are fixed at a stable branch (like MOODLE_20_STABLE) and the fix must be prepared for other branches, too (like MOODLE_21_STABLE and the main development branch - master). In Moodle, we do not merge stable branches into the master one. So usually the contributor prepares at least two branches - with the fix for the stable branch(es) and with the fix for the master branch.

If you have a patch prepared on a local branch (let us say MDL-xxxx-topic_20_STABLE), it is possible to re-apply it to another branch.

=== Cherry-picking a single commit ===

Let us have two local Git repositories ~/public_html/moodle21 containing local installation of Moodle 2.1 and ~/public_html/moodledev with the local installation of most recent development version of Moodle. They both use your public repository at github.com as the origin. You have a branch in moodle21 called MDL-xxxx-topic_21_STABLE that was forked off MOODLE_21_STABLE. It contains one commit. Now you want to re-apply this commit to a branch MDL-xxxx-topic in moodledev.

cd ~/public_html/moodledev
git checkout -b MDL-xxxx-topic origin/master (1)
git fetch ../moodle21 MDL-xxxx-topic_21_STABLE (2)
git cherry-pick FETCH_HEAD (3)

The command (1) creates new local branch forked off the CONTHERE The command (1) fetches all data needed to re-apply the topic branch and stores the pointer to the tip of that branch to FETCH_HEAD symbolic reference. The command (2) picks the tip of the branch (the top-most commit on it) and tries to apply it on the current branch.
There is also a variant of the cherry-pick command that supports multiple commits, shortly (see its man page for details): <code bash>$ git cherry-pick A^..B</code> if you want to include from A - see '''^''' - to B, A should be older than B. We will use another approach for cherry-picking multiple commits.

=== Applying a set of patches ===

If the branch MDL-xxxx-topic_21_STABLE from the previous example consists of several commits, it may be easier to use git-format-patch and git-am combo to re-apply the whole set of patches (aka patchset). Firstly you will export all commits from the topic branch to files.

cd ~/public_html/moodle21
mkdir .patches
git format-patch -o .patches MOODLE_21_STABLE..MDL-xxxx-topic_21_STABLE (1)

The command (1) takes all commits from the topic branch that are not in MOODLE_21_STABLE and exports them one by one to the output directory .patches. Look at the generated files. They contain the patch itself (in diff format) and additional information about the commit. You could eg send these files by email to a friend of yours for peer-review. We will use them in another repository.

cd ~/public_html/moodledev
git checkout -b MDL-xxxx-topic origin/master
git am -3 ../moodle21/.patches/* (1)

The command (1) applies all the files from the .patches directory. When a patch does not apply cleanly, the command tries fall back on 3-way merge (see the -3 parameter). If conflicts occur during the procedure, you can either deal with them and then use `git am --continue` or abort the whole procedure with `git am --abort`.

== See also ==

; Moodle forum discussions
* [http://moodle.org/mod/forum/discuss.php?d=168094 GIT help needed]
* [http://moodle.org/mod/forum/discuss.php?d=165236 Best way to manage CONTRIB code with GIT]
* [http://moodle.org/mod/forum/discuss.php?d=167063 Handy Git tip for tracking 3rd-party modules and plugins]
* [http://moodle.org/mod/forum/discuss.php?d=167730 Moodle Git repositories]
* [http://moodle.org/mod/forum/discuss.php?d=183409 Git help!! I don't understand rebase enough...]
* [http://moodle.org/mod/forum/discuss.php?d=217617 add MOODLE_24_STABLE to github.com repository]

; External resources
* [http://www.kernel.org/pub/software/scm/git/docs/everyday.html Everyday GIT With 20 Commands Or So]
* [http://gitref.org/ Git Reference]
* [http://progit.org/book/ Pro Git book]
* [http://vimeo.com/14629850 Getting git by Scott Chacon] - an recording of an excellent 1-hour presentation that introducing git, including a simple introduction to what is going on under the hood.
* [http://tjhunt.blogspot.co.uk/2012/03/fixing-bug-in-moodle-core-mechanics.html Tim Hunt's blog: Fixing a bug in Moodle core: the mechanics]

[[Category:Git]]

[[ja:開発者用Git]]