Moodle Developers Quick Reference

This is work-in-progress!

Welcome Moodle Developers. So you don't get scared by many APIs and entities Moodle has here is a quick reference for you.

User

Term user in Moodle may mean not only to registered user but also to guest user. On sites that enable automatic "log in as guest" the function isloggedin() will always return true. Global variable $USER contains information about current user. Useful functions: isloggedin(), isguestuser(), session_is_loggedinas(), require_login()

Site administrator

Site administrators are the users whose ids are specified in configuration $CFG->siteadmins. Note this is NOT only the user with id 2. Admin users are often treated differently when checking capabilities or enrollments. Useful functions: is_siteadmin()

Course

The entity to organise the site content. Majority of content inside the course is visible only to users who have capabilities to access it and are enrolled in this course. At the same time the list of courses (name+summary) is visible to all users (except hidden courses). Note that site may also have content that is not inside any course and does not require enrollment (i.e. content provided by local plugins).

Course category

Allows to organise courses in a tree and inherit capabilities, themes, blocks.

Frontpage

Frontpage in Moodle is a course with id SITEID. Also this is the only course that does not have a parent category. The actual "Home" page may be redirected to /my/ or user preferences. The word "frontpage" in Moodle refers to the page at /index.php

Frontpage course assumes that everybody is automatically enrolled in it.

Context

Artificial but very important entity in Moodle that allows to treat different spaces similarly. Depending on property contextlevel in may refer to: system, user, course category, course, module or block. Each context is uniquely identified either by id or by combination of contextlevel+instanceid. Each context have parent context(s). System is top-most parent context for anything. Course is the parent context for it's modules, etc.

Block

Types of blocks are defined by installed plugins. Block instances are created by admins/managers. Each block instance has context id associated with it but 'parent' context is not really applicable in this case because the same instance may be displayed on completely different pages with different contexts.

Roles

Role is a set of capabilities that can be assigned on certain context level(s). There are default roles created when Moodle is installed but developers should never rely in the code on the roles ids or names. Roles are mostly used as UI for admins to assign capabilities except for special cases, such as participants lists or course contacts.

Role archetypes (authenticated user, student, editingteacher, etc.) are used by plugins to set the default capabilities set on install/upgrade.

Capabilities

Capability is the permission granted to the user to perform particular action in particular context. Capabilities are inherited from the parent context i.e. in a module from course, in course from course categori(es), unless user have a role in child context that prohibits particular capability from parent context.

Developer usually does not need to know which roles the user has but it always need to check if user has the proper capability. Useful functions has_capability(), has_all_capabilities(), has_any_capability(), require_capability(). Some other functions such as admin_externalpage_setup() may also check capabilities.

Plugins can define the capabilities they need in <plugindir>/db/access.php. Each capability must have corresponding string in language file.

Enrollments

Please note that from DB or development point of view enrollments are not connected with roles and capabilities. User may have capabilities inside the course but not be enrolled and vice versa. Enrollment is the separate entity connecting user to the course. Function require_login() will check that user is enrolled in the course (note: everybody is enrolled in frontpage course, in many checks including require_login() admins are considered to be "enrolled"). This function must be called on any page inside the course.

Page

Global variable $PAGE is created automatically for each moodle page. Before starting output it must be initialised with current context, url, title, etc. Function require_login() will take care of setting the course or module context. After that the current course, module or context can be accessed as $PAGE->course, $PAGE->cm, $PAGE->context respectfully.

Also $PAGE takes care of navigation bar and locating the current page in Navigation and Administration blocks.

Output renderers

Renderers are reponsible for output of html in Moodle. All output (at least in the current development) must be performed calling the renderer methods and not echo-ing the html. Global variable $OUTPUT contains an instance of core_renderer (or core_renderer_ajax or core_renderer_cli depending on how the script was called), it displays the page in the layout of the current theme. Each plugin can define it's own renderer in file <plugindir>/renderer.php and get an instance of it by calling $renderer = get_renderer('<component>');

Themes are able to overwrite particular renderers.

Settings and preferences

All settings defined in config.php or set by admin in Administration block can be accessed by calling $CFG->settingname or get_config(). Almost all plugin types can define their own settings in <plugindir>/settings.php, they will appear in Administration block. Repositories and filters plugins define their settings different from other plugin types (for historical reasons).

Language strings

All text strings that Moodle outputs must be output using get_string() or new lang_string(). It is acceptable to have hardcoded English strings for developer warnings or coding exceptions. Plugins must have English definitions of strings, other languages are managed by AMOS. All plugins must have file <plugindir>/lang/en/<fullpluginname>.php containing at least pluginname. There are some other strings that are picked up automatically, for example, descriptions of capabilities or caches. Strings can have arguments, for example "Found {$a} courses". Avoid concatenation of strings because different languages may have completely different words sequence.

Filters

Filters are plugins that can add small modifications to the text while it is being displayed, for example, convert links to youtube into embedded videos, insert emoticons, automatic links, etc. All text entered by user (descriptions, summaries) must be displayed using function format_text() and all strings (course name, module name, etc.) - using function format_string(). It is important to specify context in the funcitons arguments so the filters are applied properly.

Stored files

Files API is one of the most complicated APIs in Moodle. Each file stored in Moodle is uniquely idendified by 6 attributes: contextid, component, filearea, itemid, filepath, filename. Component may be either core component such as 'course' or 'user' or plugin name. If plugin needs to store files uploaded by user it needs to define fileareas it uses and callback checking user access to particular file. Before editing the form that contains elements 'editor' or 'filemanager' the files are copied to the user draft area using file_prepare_standard_editor() or file_prepare_standard_filemanager(). After form is submitted files are copied back from draft area using file_postupdate_standard_editor() or file_postupdate_standard_filemanager().

Script /pluginfile.php given those 6 arguments will call the component callback for displaying the file. To display text with the embedded files converted to the proper URLs use file_rewrite_pluginfile_urls(). To display single stored file: file_encode_url()

Database operations

Moodle can work with different databases. All SQL queries must be written so they can be executed on any database engine. Global variable $DB will return you an instance of appropriate moodle_database child class. Except for functions for retrieving and updating records it has number of useful functions for parts of SQL query that can be different in different DB, such as get_in_or_equal(), sql_concat(), etc. Tables in database may have a user defined prefix. In functions where table name is not a separate argument (such as get_recordset_sql() or execute()) use {} around table name and prefix will be added automatically.

CSS

Moodle core does not have CSS files outside of themes. But each plugin can put it's own directives in <plugindir>/styles.css. Note that all css files are merged together in one big file that is included on every page so please use prefixes in your CSS directives so they are applied only to the files generated by your plugin. Note that <body> tag already has plenty of different classes and id representing the file path. You can also use $PAGE->add_body_class()

Javascript

Moodle uses YUI as Javascript framework. YUI allows to load modules as they are needed. You can load necessary JS files and execute init functions by calling $PAGE->requires->yui_module(), $PAGE->requires->js_init_code(), etc. Also you can pass language strings to the JS using $PAGE->requires->string_for_js() and inside script they will be available via M.str or M.util.get_string()