Moodle Developers Quick Reference: Difference between revisions
No edit summary |
No edit summary |
||
Line 12: | Line 12: | ||
=== Course === | === 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 === | === Course category === | ||
Allows to organise courses in a tree and inherit capabilities, themes, blocks. | |||
=== Frontpage === | === Frontpage === | ||
Line 21: | Line 25: | ||
Frontpage course assumes that everybody is automatically enrolled in it. | Frontpage course assumes that everybody is automatically enrolled in it. | ||
=== Module === | === Module (Activity, Resource) === | ||
=== Context === | === 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 | 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 === | === Block === | ||
Line 33: | Line 37: | ||
=== Roles === | === Roles === | ||
Role is a set of capabilities that can be assigned on certain context | 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. | '''Role archetypes''' (authenticated user, student, editingteacher, etc.) are used by plugins to set the default capabilities set on install/upgrade. | ||
Line 47: | Line 51: | ||
=== Enrollments === | === 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 | 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 === | === Page === |
Latest revision as of 02:43, 11 June 2013
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.
Module (Activity, Resource)
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()