MoodleDocs - User contributions [en]

Setting up xhprof on Moodle

2015-06-17T15:06:27Z

Conhorne: /* Configuring Moodle to use xhprof */ correcting spelling issues

The following instructions are for setting up xhprof for Moodle under a Ubuntu/Debian environment. The process should be similar for other linux enviroments, but will need some tweaking if you wish to do this under windows. Please update this document if you find any major problems.

==Installing xhprof with Linux==

===Debian/Ubuntu package===
apt-get install php5-xhprof
The current LTS Ubuntu package is version 0.9.4-1build1

===Build manually===
<code bash>
mkdir ~/src/
cd ~/src/
wget http://pecl.php.net/get/xhprof-0.9.2.tgz
tar xvf xhprof-0.9.2.tgz
cd xhprof-0.9.2/extension/
phpize
./configure
make
sudo make install
</code>

Note: The version downloaded via these instructions is not compatible with PHP 5.4 - instead you should download the latest version of the code from https://github.com/facebook/xhprof (before following the instructions from 'cd xhprof-0.9.2/extension/' onwards).

Note: It is available now, the 0.9.3 version from the pecl website. You can run wget http://pecl.php.net/get/xhprof-0.9.3.tgz, if you have PHP 5.4 version.

Add the following to the apache version of you php.ini file

<code ini>
[xhprof]
extension=xhprof.so
xhprof.output_dir="/var/tmp/xhprof"
</code>

Restart Apache
<code bash>
sudo service apache2 restart
</code>

Create a file in your web root that makes a call to phpinfo(); and then view the result in your browser to make sure that xhprof is enabled in PHP. Checking the output of '''php -m''' would also work if you are sure that the command line version of PHP uses the same php.ini file as your web server.

===Troubleshooting===
If you see a '''failed to shell execute cmd=" dot -Tpng''' error when you follow the '''View Full Callgraph''' link you may need to install graphviz ('''sudo apt-get install graphviz''').

Into Windows environment this error can be caused by a path hardcoded into "\lib\xhprof\xhprof_lib\utils\callgraph_utils.php", you must replace one parameter of the proc_open function which is a Linux path "/tmp" by a Windows one, like "c:/temp".

==Installing xhprof with Windows==

You will need to download PHP extensions compiled for your version of PHP. [http://dev.freshsite.pl/php-extensions/xhprof.html Here is one source...]

Extract the contained dll file to the ext directory of your server. With XAMPP this is in xampp\php\ext

Add a line to your php.ini file that matches dll filename you are using. This goes in the Dynamic Extensions section.

<code>
extension=xhprof_0.10.3_php54_vc9.dll
</code>

Stop and restart Apache through your server control interface. If it complains, you probably don't have the correct extension for your version of PHP, or the extension entry in your php.ini file doesn't match the dll file.

To test that the extension is installed, log in to Moodle as an administrator and navigate to Administration > Site administration > Server > PHP info. Search for information about the xhprof extension. It should be present and enabled.

==Configuring Moodle to use xhprof==
[[Image:profilingOption.png|thumb|left|The profiling option is displayed when the php xhprof extension is installed]]
[[Image:profilingOutput.png|thumb|right|Tabular profiling output produced by xhprof]]
[[Image:callgraph.png|thumb|right|An example call graph showing slow parts of the profiled run]]
Once the xhprof php extension is correctly installed you will find a new "Profiling" option available under Settings > Site administration > Development

When you load the profiling settings page you are confronted with several options. In order to get xhprof up and running with minimal fuss you merely need to check the "Enable profiling" box and set a path that you wish to be profiled. You can simply set this to a wildcard using the asterisk symbol ('''*''') while you are testing profiling. Afterwards you can come back and set this to a more restrictive setting once you know profiling is working. Note the paths need to be specified relative to your Moodle directory and not the web root.

After you have enabled profiling you should load some pages within the "Profile these" filter that you set in the step above. Once you have done these go to Settings > Site administration > Development > Profiling runs and you should see a list of the pages you visited. Clicking on one of these and then clicking on the "View profiling details" will take you to a profiling table full of helpful stats for tracking down slow pages and functions. You can get an even more interesting breakdown of this by then clicking on the "View Full Callgraph" link. This callgraph makes it easy to see where the slow parts of each particular run are and functions which individually may not take a long time to run but which are run thousands of times and thus resulting in a great deal of slowdown.
[[Image:profilingSettings.png|frame|center|Enabling profiling and setting it to run on all pages via a wildcard]]
[[Image:profilingRuns.png|frame|left|A profiling runs option can be seen after enabling profiling]]

==Using XHProf==

MDL-39443 shows the kind of thing that can be done using XHProf.

[http://tjhunt.blogspot.co.uk/2013/05/performance-testing-moodle.html This blog post] talks about the process.

Since Moodle 2.5.1 it's possible to export and import any profiling run. That enables some interesting uses like, comparisons along the time, between different systems and sharing or runs in other systems like the Tracker when optimization issues are being fixed.

Setting up xhprof on Moodle

2015-06-17T15:05:11Z

Conhorne: /* Configuring Moodle to use xhprof */

The following instructions are for setting up xhprof for Moodle under a Ubuntu/Debian environment. The process should be similar for other linux enviroments, but will need some tweaking if you wish to do this under windows. Please update this document if you find any major problems.

==Installing xhprof with Linux==

===Debian/Ubuntu package===
apt-get install php5-xhprof
The current LTS Ubuntu package is version 0.9.4-1build1

===Build manually===
<code bash>
mkdir ~/src/
cd ~/src/
wget http://pecl.php.net/get/xhprof-0.9.2.tgz
tar xvf xhprof-0.9.2.tgz
cd xhprof-0.9.2/extension/
phpize
./configure
make
sudo make install
</code>

Note: The version downloaded via these instructions is not compatible with PHP 5.4 - instead you should download the latest version of the code from https://github.com/facebook/xhprof (before following the instructions from 'cd xhprof-0.9.2/extension/' onwards).

Note: It is available now, the 0.9.3 version from the pecl website. You can run wget http://pecl.php.net/get/xhprof-0.9.3.tgz, if you have PHP 5.4 version.

Add the following to the apache version of you php.ini file

<code ini>
[xhprof]
extension=xhprof.so
xhprof.output_dir="/var/tmp/xhprof"
</code>

Restart Apache
<code bash>
sudo service apache2 restart
</code>

Create a file in your web root that makes a call to phpinfo(); and then view the result in your browser to make sure that xhprof is enabled in PHP. Checking the output of '''php -m''' would also work if you are sure that the command line version of PHP uses the same php.ini file as your web server.

===Troubleshooting===
If you see a '''failed to shell execute cmd=" dot -Tpng''' error when you follow the '''View Full Callgraph''' link you may need to install graphviz ('''sudo apt-get install graphviz''').

Into Windows environment this error can be caused by a path hardcoded into "\lib\xhprof\xhprof_lib\utils\callgraph_utils.php", you must replace one parameter of the proc_open function which is a Linux path "/tmp" by a Windows one, like "c:/temp".

==Installing xhprof with Windows==

You will need to download PHP extensions compiled for your version of PHP. [http://dev.freshsite.pl/php-extensions/xhprof.html Here is one source...]

Extract the contained dll file to the ext directory of your server. With XAMPP this is in xampp\php\ext

Add a line to your php.ini file that matches dll filename you are using. This goes in the Dynamic Extensions section.

<code>
extension=xhprof_0.10.3_php54_vc9.dll
</code>

Stop and restart Apache through your server control interface. If it complains, you probably don't have the correct extension for your version of PHP, or the extension entry in your php.ini file doesn't match the dll file.

To test that the extension is installed, log in to Moodle as an administrator and navigate to Administration > Site administration > Server > PHP info. Search for information about the xhprof extension. It should be present and enabled.

==Configuring Moodle to use xhprof==
[[Image:profilingOption.png|thumb|left|The profiling option is displayed when the php xhprof extension is installed]]
[[Image:profilingOutput.png|thumb|right|Tabular profiling output produced by xhprof]]
[[Image:callgraph.png|thumb|right|An example call graph showing slow parts of the profiled run]]
Once the xhprof php extension is correctly installed you will find a new "Profiling" option available under Settings > Site administration > Development

When you load the profiling settings page you are confronted with several options. In order to get xhprof up and running with minimal fuss you merely need to check the "Enable profiling" box and set a path that you wish to be profiled. You can simply set this to a wildcard using the asterisk symbol ('''*''') while you are testing profiling. Afterwards you can come back and set this to a more restrictive setting once you know profiling is working. Note the paths need to be specified relative to your Moodle directory and not the web root.

After you have enabled profiling you should load some pages within the "Profile these" filter that you set in the step above. Once you have done these go to Settings > Site administration > Development > Profiling runs and you should see a list of the pages you visited. Clicking on one of these and then clicking on the "View profiling details" will take you to a profiling table full of helpful stats for tracking down slow pages and functions. You can get an even more ineresting breakdown of this by then clicking on the "View Full Callgraph" link. This callgraph makes it easy to see where the slow parts of each particular run are and functions which individually may not take a long time to run but which are run thousands of times and thus resulting in a great deal of slowdown.
[[Image:profilingSettings.png|frame|center|Enabling profiling and setting it to run on all pages via a wildcard]]
[[Image:profilingRuns.png|frame|left|A profiling runs option can be seen after enabling profiling]]

==Using XHProf==

MDL-39443 shows the kind of thing that can be done using XHProf.

[http://tjhunt.blogspot.co.uk/2013/05/performance-testing-moodle.html This blog post] talks about the process.

Since Moodle 2.5.1 it's possible to export and import any profiling run. That enables some interesting uses like, comparisons along the time, between different systems and sharing or runs in other systems like the Tracker when optimization issues are being fixed.

PHPUnit

2014-05-22T18:34:57Z

Conhorne: /* fixing wrong word */

{{Moodle 2.3}}

=What is PHPUnit=
PHPUnit by Sebastian Bergmann is an advanced unit testing framework for PHP. It is installed as Composer dependency and is not part of Moodle installation. To run PHPUnit tests, you have to manually install it on your development computer or test server.

Read the excellent guide at
* [http://phpunit.de/manual/current/en/index.html PHPUnit Manual]

=Installation of PHPUnit via Composer=

The installation procedure depends on your operating system.
* Install Composer dependency manager

cd /your/moodle/dirroot
curl -s https://getcomposer.org/installer | php

On Windows go to https://getcomposer.org/download/ and download the Composer-Setup.exe file

* Execute Composer installer

cd /your/moodle/dirroot
php composer.phar install --dev

(If that gives you connection problems try...)

php composer.phar install --dev --prefer-source

Troubleshooting:
* On Windows if you are behind a proxy you will need to setup an environment variable called HTTP_PROXY with a value detailing your HTTP Proxy address and port before composer will correctly download files.
* You may be prompted for github credentials when installing composer dependencies.
** This is used to generate an personal access token to avoid being rate limited by github.
** If you have Two Factor Authentication enabled on your github account, or do not wish to supply your own credentials you will need to generate a token manually:
*** Visit https://github.com/settings/applications and request personal access token
*** Copy this token and add it to your [https://gist.github.com/andrewnicols/c5377ed25a9df1006ce1 ~/.composer/config.json]
** ( See [https://github.com/composer/composer/issues/2280 composer issue #2280] for further details of this bug.)

Detailed instructions:
* [http://getcomposer.org/doc/00-intro.md Composer documentation]

Detailed instructions:
* [[PHPUnit installation in Windows]]
* [[PHPUnit installation in OS X]]

== Uninstalling previous PEAR based version ==

Before using composer, this page used to suggest to install phpunit via PEAR. If you did so, you may wish to uninstall that package now. This should work:

$ pear uninstall phpunit/DbUnit
$ pear uninstall phpunit/PHPUnit

=Initialisation of test environment=

Our PHPUnit integration requires a dedicated database and dataroot. First, add a new dataroot directory and prefix into your config.php, you can find examples in config-dist.php (scroll down to 'Section 9').

$CFG->phpunit_prefix = 'phpu_';
$CFG->phpunit_dataroot = '/home/example/phpu_moodledata';

If your system does not have a direct connection to the Internet, you also need to specify your proxy in config.php - even though you normally specify it by using the admin settings user interface. (If you do not use a proxy, you can skip this step.) Check the settings on the relevant admin settings page, or from the mdl_config table in your database, if you are unsure of the correct values.

// Normal proxy settings
$CFG->proxyhost = 'wwwcache.example.org';
$CFG->proxyport = 80;
$CFG->proxytype = 'HTTP';
$CFG->proxybypass = 'localhost, 127.0.0.1, .example.org';
// Omit the next lines if your proxy doesn't need a username/password:
$CFG->proxyuser = 'systemusername';
$CFG->proxypassword = 'systempassword';

Then you need to initialise the test environment using following command.

cd /home/example/moodle
php admin/tool/phpunit/cli/init.php

This command has to be repeated after any upgrade, plugin (un)installation or if you have added tests to a plugin you are developing:

'''NOTE:''' make sure that your php cli executable (or the one you want to use) is correctly on your path as the individual init scripts will call it repeatedly.

=Test execution=

To execute all test suites from main configuration file execute the <code>vendor/bin/phpunit</code> script from your <code>$CFG->dirroot</code> directory.

cd /home/example/moodle
vendor/bin/phpunit

The rest of examples uses <code>phpunit</code>, please substitute it with <code>vendor/bin/phpunit</code> or create a shortcut in your dirroot.

In IDEs, you may need to specify the path to the PHPUnit configuration file. Use the absolute path to <code>phpunit.xml</code> from your <code>$CFG->dirroot</code>.

There is an alternative script for running of tests via web interface: <code>admin/tool/phpunit/webrunner.php</code>. Use this as the last resort only when you cannot use the command-line interface on your test server. It will most probably break due to permissions problems if you try to execute it both from command-line and from webrunner. This feature is not officially supported.

===How to run only some tests===

==== Running a single test quickly ====

The fastest way to run a single test is:

vendor/bin/phpunit my_test_class_name my/tests/filename.php

This is faster than other methods because it avoids the need to search for the test file, but you should be careful because it may be possible to run tests this way which are not included in the normal run. If you use this method, do at least one full test run (or --group run, as below) to ensure the test can be found.

==== Using the @group annotation ====

If you add annotations like

<code php>
/**
* Unit tests for {@link stack_cas_keyval}.
* @group qtype_stack
*/
class stack_cas_keyval_exception_test extends basic_testcase {
</code>

to all the classes in your plugin, then you can run just the tests for your plugin by doing

phpunit --group qtype_stack

Therefore, it is suggested that you annotate all your tests with the Frankenstyle name of your plugin.

==== Using multiple phpunit.xml files ====

It's easy to create alternative phpunit.xml files defining which tests must be run together. For reference, take a look to the default /phpunit.xml available in your base directory once the testing environment has been initialised. After creating the custom file you will be able to run those tests with

vendor/bin/phpunit -c path/to/your/alternative/phpunit/file.xml

Also, for commodity, you can use this command:

php admin/tool/phpunit/cli/util.php --buildcomponentconfigs

It will, automatically, create one valid phpunit.xml file within each component (plugin or subsystem) and other important directories, so later you will be able to execute tests like

vendor/bin/phpunit -c mod/forum[/phpunit.xml] // Note that it's not needed to specify the name of the file (if it is 'phpunit.xml').
vendor/bin/phpunit -c question
vendor/bin/phpunit -c question/type/calculated
vendor/bin/phpunit -c backup
vendor/bin/phpunit -c lib/dml
...

or, also

cd directory/with/phpunit.xml
phpunit

=External test resources=
{{Moodle 2.6}}
By default Moodle phpunit tests contact http://download.moodle.org server when testing curl related functionality. Optionally you may checkout a local copy of the test scripts and access it instead:

# clone https://github.com/moodlehq/moodle-exttests to web directory
# add to your config.php or modify phpunit.xml file <code php>define('TEST_EXTERNAL_FILES_HTTP_URL', 'http://localhost/moodle-exttests');</code>

=Writing new tests=
* read [http://www.phpunit.de/manual/current/en/ official PHPUnit online documentation]
* see [[Writing PHPUnit tests]]

=Conversion of existing SimpleTests=
* see [[SimpleTest conversion]]

=PHPUnit support in IDEs=

* [http://www.phpsrc.org/projects/pti-phpunit/wiki/ Eclipse PHP Tool Integration]
* [http://blog.jetbrains.com/webide/2009/12/phpunit-support/ PHPStorm IDE]
* [http://netbeans.org/kb/docs/php/phpunit.html Netbeans]

=Common Unit Test Problems=
[[Common unit test problems]]

=Performance=

A typical run of full PHPUnit tests for Moodle 2.7 takes 10-20 minutes depending on the machine. If tests run slowly for you:

* Ensure you are using a database and filesystem running on the same machine that is running the tests (not on a remote server).
* Apply developer-only performance settings to your database: [[Postgres Tuning For Developers]]

[[Category:Unit testing]]

Coding

2014-05-22T17:21:31Z

Conhorne: /* Added clean theme info */

This page is the top-level page describing Moodle's coding guidelines. It's the place to start if you want to know how to write code for Moodle.

==Moodle architecture==

Moodle tries to run on the widest possible range of platforms, for the widest possible number of people, while remaining easy to install, use, upgrade and integrate with other systems.

For more about this, see [[Moodle architecture]].

==Plugins==

Moodle has a general philosophy of modularity. There are nearly 30 different standard types of plugins and even more sub-plugin types, however all of these plugin types work the same way. Blocks and activities are the only small exceptions.

See [[Plugins|Moodle plugins]] and [[Subplugins|Moodle sub-plugins]] for more information.

==Coding style==

Consistent coding style is important in any development project, and particularly so when many developers are involved. A standard style helps to ensure that the code is easier to read and understand, which helps overall quality.

Writing your code in this way is an important step to having your code accepted by the Moodle community.

Our [[Coding_style|Moodle coding style]] document explains this standard.

==Security==

Security is about protecting the interests and data of all our users. Moodle may not be banking software, but it is still protecting a lot of sensitive and important data such as private discussions and grades from outside eyes (or student hackers!) as well as protecting our users from spammers and other internet predators.

It's also a script running on people's servers, so Moodle needs to be a responsible Internet citizen and not introduce vulnerabilities that could allow crackers to gain unlawful access to the server it runs on.

Any single script (in Moodle core or a third party module) can introduce a vulnerability to thousands of sites, so it's important that all developers strictly follow our [[Security|Moodle security guidelines]].

==XHTML and CSS==

It's important that Moodle produces strict, well-formed [http://en.wikipedia.org/wiki/HTML5 HTML 5] code (preferably backwards compatible with [[XHTML|XHTML 1.1]] if possible), compliant with all common accessibility guidelines (such as [http://www.w3.org/TR/WCAG20/ W3C WAG 2.0], [http://www.w3.org/TR/wai-aria-practices/ ARIA]).

CSS should be used for layout. Moodle comes with several themes installed. Beginning with version 2.7, only the 'Clean' theme comes in the base Moodle code. The 'standard' theme, which should be a plain theme suitable to act as a building block for other themes. That should contain the minimal styling to make Moodle look OK and be functional. Then Moodle comes with several other default themes that look good and demonstrate various techniques for building themes.

This helps consistency across browsers in a nicely-degrading way (especially those using non-visual or mobile browsers), as well as improving life for theme designers.

==JavaScript==

In general, everything in Moodle should work with JavaScript turned off in your browser. This is important for accessibility, and in line with the principles of unobtrusive JavaScript and progressive enhancement.

Features that are not available without JavaScript must be compliant with all accessibility standards.

See the [[JavaScript guidelines|Moodle JavaScript guidelines]] for more information.

==Internationalisation==

Moodle works in over 84 languages because we pay great attention to keeping the language strings and locale information separate from the code, in language packs.

The default language for all code, comments and documentation, however, is English (AU).

Full details: [[Internationalisation|Moodle Internationalisation]]

==Accessibility==

Moodle should work well for the widest possible range of people.

See [[Accessibility|Moodle Accessibility]] for more information.

==Usability==

See [[Interface_guidelines| Interface Guidelines]] (under construction)

==Performance==

The load any Moodle site can cope with will, of course, depend on the server and network hardware that it is running on. However there are some features (intended especially for developers) that are discouraged on production sites for performance reasons.

The most important property is scalability, so a small increase in the number of users, courses, activities in a course, and so on, only causes a correspondingly small increase in server load.

For more information and advice, see [[Performance and scalability|Performance and scalability]].

==Database==

Moodle has a powerful database abstraction layer that we wrote ourselves, called [[XMLDB_Documentation|XMLDB]]. This lets the same Moodle code work on MySQL/MariaDB, PostgreSQL, MS SQL Server and Oracle. There are know issues when using Oracle, it is not fully supported and is not recommended for production sites.

We have tools and API for [[DDL functions|defining and modifying tables]] as well as [[Data manipulation API|methods for getting data in and out]] of the database.

Overview: [[Database|Moodle Database]] guidelines

==Events==

Moodle allows inter-module communication via '''events'''. Modules can '''trigger''' specific events and other modules can choose to '''handle/observe''' those events.

See:
* [[Events_API|Events API]] - Moodle 2.0 - 2.5
* [[Event_2|New Events API]] - Moodle 2.6 and later

==Unit testing==

[http://en.wikipedia.org/wiki/Unit_testing Unit testing] is not simply a technique but a philosophy of software development.

The idea is to create automatable tests for each bit of functionality that you are developing (at the same time you are developing it). This not only helps everyone later test that the software works, but helps the development itself, because it forces you to work in a modular way with very clearly defined structures and goals.

Moodle uses a framework called [https://github.com/sebastianbergmann/phpunit/ PHPUnit] that makes writing unit tests fairly simple.

See [[PHPUnit]] for more information.

==Acceptance testing==

PHPUnit covers mostly the internal implementation of functions and classes, the user interaction testing can be automated using the [http://behat.org Behat framework].

See [[Acceptance testing]] for more information.

== Other standards ==

Please note that Moodle coding style and design is pretty unique, it is not compatible with [http://pear.php.net/manual/en/standards.php PEAR coding standards] or any other common PHP standards.

Moodle architecture

2014-05-22T17:06:35Z

Conhorne: /* corrected an incorrect working */

The aim of this document is to quickly give an overview of how the Moodle works at a technical level. Hopefully this will be helpful to Administrators and Developers. However, to actually do Moodle development you will have to study the code in much more detail than is provided here. See the [[Developer_documentation|developer documentation]].

==What is Moodle?==

Moodle is a Learning Management System, Course Management System, or Virtual Learning Environment, depending on which term you prefer. Its goal is to give teachers and students the tools they need to teach and learn. Moodle comes from a background of [[:en:Pedagogy|Social Constructionist pedagogy]], however, it can be used to support any style of teaching and learning.

There are other types of software systems that are important for educational institutions, for example ePortfolios, Student Information Systems and Content repositories. Generally, Moodle does not try to re-invent these areas of functionality. Instead, tries to be the best LMS possible, and then interoperate gracefully with other systems that provide the other areas of functionality. It is, however, perfectly possible to use Moodle as a stand-alone system, without integrating it with anything else.

Moodle is a web application written in PHP. Moodle is open source. Copyright is owned by individual contributors, not assigned to a single entity, although the company Moodle Pty Ltd in Perth Australia, owned by Moodle's founder Martin Dougiamas, manages the project.

==Overview of a Moodle installation==

A Moodle installation comprises the Moodle code executing in a PHP-capable web server; a database managed by MySQL, PostgreSQL, Microsoft SQL Server, MariaDB, or Oracle; and a file store for uploaded and generated files (the moodledata folder).

All three parts can run on a single server; or they can be separated with many load-balanced web-servers, a database cluster, and a file-server; or anywhere between those extremes.

Moodle is designed to be simple to install on any server that meets these basic requirements. Moodle self-installs once the code has been copied to the web server and a blank database created (see [[:en:Installing Moodle]]). Similarly, Moodle can always self-upgrade from one version to the next (see [[:en:Upgrading]]).

==Moodle as a modular system==

Like many successful open source systems, Moodle is structured as an application core, surrounded by numerous plugins to provide specific functionality. Moodle is designed to be highly extensible and customizable without modifying the core libraries, as doing so would create problems when upgrading Moodle to a newer version. So when customizing or extending your own Moodle install, always do so through the plugin architecture.

Plugins in Moodle are of specific types. That is, an authentication plugin and an activity module will communicate with Moodle core using different APIs, tailored to the type of functionality the plugin provides. Functionality common to all plugins (installation, upgrade, permissions, configuration, ...) are, however, handled consistently across all plugin types.

The standard Moodle distribution includes Moodle core and a number of plugins of each type, so that a new Moodle installation can immediately be used to start teaching and learning. After installation a Moodle site can be adapted for a particular purpose by changing the default configuration option, and by installing add-ons or removing standard plugins. Most add-ons that have been shared publicly are listed in the [http://moodle.org/plugins/index.php Moodle Plugins Directory].

Physically, a Moodle plugin is just a folder of PHP scripts (and CSS, JavaScript, etc. if necessary). Moodle core communicates with the plugin by looking for particular entry points, often defined in the file <tt>lib.php</tt> within the plugin.

==An overview of Moodle core==

Moodle core provides all the infrastructure necessary to build a Learning Management System. It implements the key concepts that all the different plugins will need to work with. These include:

'''Courses and activities:'''
A Moodle course is a sequence of activities and resources grouped into sections. Courses themselves are organized into a hierarchical set of categories within a Moodle site.

'''Users:'''
In moodle, users are anyone who uses the moodle system. In order to participate in course users need to be enrolled into course with a given role, such as:

*Students
*Teachers

'''Course enrolment''':

*Enrolment gives user the possibility to participate in course as a student or teacher.

'''User functionality in moodle:'''

*User roles in moodle: Roles assigned to users give them a set of capabilities in given context. For example: Teacher, Student and Forum moderator are examples of roles.
*User's capabilities in moodle: A capability is a description of some particular Moodle feature. Capabilities are associated with roles. For example, mod/forum:replypost is a capability.
*Context: A context is a "space" in the Moodle, such as courses, activity modules, blocks etc.
*Permissions: A permission is some value that is assigned for a capability for a particular role. For example, allow or prevent.

'''Added facilities provided by moodle: Added facilities provided by moodle:'''

*Creation and editing of user profiles: In moodle, the moment an user creates his account, a profile is created for that user. The user needs to fill in his initial details for completing his profile. The user generally always have the permission to edit his own profile anytime on moodle.
*Groups and cohorts: Cohorts, or site-wide groups, enable all members of a cohort to be enrolled in a course in one action, either manually or synchronised automatically.
*Enrolments and access control: Users are generally enrolled into some courses and according to their permission settings and the groups to which they belong, they have limited access on moodle.

'''A bit more about moodle:'''

*Activity and course completion: The activity completion system allows activities such as Quizzes, SCORM modules, etc. to be marked complete when specified conditions are met.
*Navigation, settings and configuration: The Navigation block provide easy access to view various sections of the Moodle site and includes:
**My home - a personalised home page displaying links to the courses a user is associated with and activity information (such as unread forum posts and upcoming assignments)
**Site pages - links to site pages and resources from the front page of Moodle
**My profile - quick links allowing a user to view their profile, forums posts, blogs and messages as well as manage their private files
**My courses - lists (by course shortname) and links to courses the user is associated with. Click the course's shortname to view the front page of the course or use the arrows to navigate quickly to a specific section, resource or activity.

'''JavaScript library:'''
*Moodle has adopted the Yahoo User Interface library. There is also a nice system for loading the additional JavaScript files required by each page.

'''Upgrading moodle:'''
Moodle can be upgraded in four simple steps:

#Make sure that your server can run the latest Moodle version
#You should always be prepared to "roll back" if there's an issue with your data or some custom code you've added. So before committing, create a test install and always make backups.
#At this stage you can replace the Moodle code on your server with the version you downloaded and check for the plugins.
#Perform the upgrade by triggering the upgrade from the admin page.

(More information about upgrading can be found here : https://docs.moodle.org/27/en/Upgrade_overview)

'''Logs and statistics in moodle:'''
*Statistics in moodle: The statistics graphs and tables show how many hits there have been on various parts of your site during various time frames. They do not show how many distinct users there have been. They are processed daily at a time you specify. You must enable statistics before you will see anything.
*Log in moodle: Logs in Moodle are activity reports. Logs are available at site level and course level.

==The most important plugin types==

===Activities and resources===

Activities and resources are the most basic individual components that make up a course and are the main tools for teaching and learning. Some examples of resources are: pages, links and IMS content packages. Examples of activities include: forums, wikis, quizzes, and assignments.

Activities are by far the largest type of plugin in terms of amount of code. A forum or wiki system could be a software project in its own right. Both activities and resources are installed in the <tt>mod</tt> folder.

===Blocks===

Blocks are small bits of interface functionality that can be added to (normally the sides of) pages. Many blocks provide additional views of data stored and modified elsewhere. Blocks live in the <tt>blocks</tt> folder.

===Themes===

The overall visual style of a Moodle site, a particular course, or all courses in a category, can be changed by selecting a different theme at these different levels. Themes are the standard way of making aesthetic changes to your Moodle application, decoupling presentation from content and functionality.

Themes live in the <tt>theme</tt> folder, and published themes are listed in the [http://moodle.org/mod/data/view.php?id=6552 Themes database].

===Language packs===

Moodle is internationalised. That is, you can get language packs for many different languages. Language packs are normally downloaded and installed via the Moodle administration screens, but they can also be downloaded manually from [http://download.moodle.org/langpack/ Moodle.org: language packs].

Administrators can also manually change any of the standard user interface strings if the terms used in the installed language pack are not appropriate.

===Course formats===

control how the structure of the course, a sequence of activities grouped into sections, is presented to the users. Course formats live in the <tt>course/format</tt> folder.

===Authentication plugins===

control how users log in. Moodle can manage usernames and passwords itself, or use those stored in LDAP or another database. Alternatively, Moodle can use a number of single-sign-on schemes. Authentication plugins live in the <tt>auth</tt> folder.

===Enrolment plugins===

control which users are enrolled in which courses. Again this can be by synchronising with another system, perhaps a student information system, or it can be tracked internally by Moodle. Enrolment plugins live in the <tt>enrol</tt> folder. (Moodle was created by an Australian, so enrol is the correct spelling ;-).)

===Repository plugins===

Ways for users to get content (files) into Moodle, either by uploading from their hard drive, or by getting the file from another location on the Internet, perhaps Drop Box, Google Docs, or Flickr. Repository plugins live in the <tt>repository</tt> folder.

===Others===

There are [[Developer_documentation#Make_a_new_plugin|many more types of plugins]] (more than 30 at the last count). These include text filters, question types, gradebook reports, admin reports, course reports, plagiarism detection services and web service protocols.

For a definitive, up-to-date list, look at the value returned by the <tt>get_plugin_types()</tt> function, which is defined in <tt>lib/moodlelib.php</tt>.

==How Moodle code is organised==

Moodle mostly follows a [http://martinfowler.com/eaaCatalog/transactionScript.html transaction script] approach. That is, suppose you are looking at a Forum. The URL will be <tt>.../mod/forum/view.php?id=1234</tt>. and <tt>mod/forum/view.php</tt> the PHP script that generates that page. One could argue that transaction script is not an appropriate pattern for an application as complex as Moodle. However, it is a very natural architecture for a PHP application, and Moodle is an aggregate of many different plugins, rather than a single complex application.

Behind that basic transaction script approach, a lot of the core functionality has been refactored out into libraries (mostly in the <tt>lib</tt> folder). This provides elements of a [http://martinfowler.com/eaaCatalog/domainModel.html domain model]. The Moodle project started before PHP could handle object-oriented code, however, so don't expect an object-oriented domain model except in some of the more recent parts of the Moodle code.

There are two layers used to separate presentation from the business logic. The outer layer is the theme (see above) which controls the more visual aspects of the Moodle interface. Then there are renderer classes which generate the HTML to be output from the data supplied by the transaction scripts and the domain model. Unfortunately, neither PHP, nor the Moodle architecture, enforces a clear separation of the UI layer. It is possible for sloppy developers to make a mess, and this has happened in the past. The code in the standard Moodle distribution is gradually being cleaned up.

==The Moodle database==

The Moodle database comprises many tables (more than 250) because the whole database is an aggregate of the core tables and the tables belonging to each plugin. Fortunately, this large structure is understandable, because the tables for one particular plugin typically only link to each other and a few core tables. See [[Database_schema_introduction|Database schema introduction]] for more information.

The Moodle database structure is defined in <tt>install.xml</tt> files inside the <tt>db</tt> folder in each plugin. For example <tt>mod/forum/db/install.xml</tt> contains the database definition for the forum module. <tt>lib/db/install.xml</tt> defines the tables used by Moodle core. The <tt>install.xml</tt> files contain comments that should explain the purpose of each table and column. These comments can be turned into human-readable documentation by going to Site administration -> Development -> XMLDB editor in your Moodle installation, and clicking on the [Doc] link.

==See also==

* [[:en:Administrator documentation]]
* [[Developer_documentation|Developer documentation]]
* [[Database_schema_introduction|Database schema introduction]]
* [http://moodle.org/mod/data/view.php?id=6009 Modules and plugins] and [http://moodle.org/mod/data/view.php?id=6552 themes] databases
* [http://moodle.org/mod/forum/discuss.php?d=64465 Forum thread with a vigorous argument about whether an architecture document is a good idea, which eventually lead to this page being rewritten]
* [http://www.aosabook.org/en/moodle.html The chapter of The Architecture of Open Source Applications about Moodle]

[[Category:Coding guidelines]]

Moodle architecture

2014-05-22T17:03:13Z

Conhorne: /* Correcting spelling */

The aim of this document is to quickly give an overview of how the Moodle works at a technical level. Hopefully this will be helpful to Administrators and Developers. However, to actually do Moodle development you will have to study the code in much more detail than is provided here. See the [[Developer_documentation|developer documentation]].

==What is Moodle?==

Moodle is a Learning Management System, Course Management System, or Virtual Learning Environment, depending on which term you prefer. Its goal is to give teachers and students the tools they need to teach and learn. Moodle comes from a background of [[:en:Pedagogy|Social Constructionist pedagogy]], however, it can be used to support any style of teaching and learning.

There are other types of software systems that are important for educational institutions, for example ePortfolios, Student Information Systems and Content repositories. Generally, Moodle does not try to re-invent these areas of functionality. Instead, tries to be the best LMS possible, and then interoperate gracefully with other systems that provide the other areas of functionality. It is, however, perfectly possible to use Moodle as a stand-alone system, without integrating it with anything else.

Moodle is a web application written in PHP. Moodle is open source. Copyright is owned by individual contributors, not assigned to a single entity, although the company Moodle Pty Ltd in Perth Australia, owned by Moodle's founder Martin Dougiamas, manages the project.

==Overview of a Moodle installation==

A Moodle installation comprises the Moodle code executing in a PHP-capable web server; a database managed by MySQL, PostgreSQL, Microsoft SQL Server, MariaDB, or Oracle; and a file store for uploaded and generated files (the moodledata folder).

All three parts can run on a single server; or they can be separated with many load-balanced web-servers, a database cluster, and a file-server; or anywhere between those extremes.

Moodle is designed to be simple to install on any server that meets these basic requirements. Moodle self-installs once the code has been copied to the web server and a blank database created (see [[:en:Installing Moodle]]). Similarly, Moodle can always self-upgrade from one version to the next (see [[:en:Upgrading]]).

==Moodle as a modular system==

Like many successful open source systems, Moodle is structured as an application core, surrounded by numerous plugins to provide specific functionality. Moodle is designed to be highly extensible and customizable without modifying the core libraries, as doing so would create problems when upgrading Moodle to a newer version. So when customizing or extending your own Moodle install, always do so through the plugin architecture.

Plugins in Moodle are of specific types. That is, an authentication plugin and an activity module will communicate with Moodle core using different APIs, tailored to the type of functionality the plugin provides. Functionality common to all plugins (installation, upgrade, permissions, configuration, ...) are, however, handled consistently across all plugin types.

The standard Moodle distribution includes Moodle core and a number of plugins of each type, so that a new Moodle installation can immediately be used to start teaching and learning. After installation a Moodle site can be adapted for a particular purpose by changing the default configuration option, and by installing add-ons or removing standard plugins. Most add-ons that have been shared publicly are listed in the [http://moodle.org/plugins/index.php Moodle Plugins Directory].

Physically, a Moodle plugin is just a folder of PHP scripts (and CSS, JavaScript, etc. if necessary). Moodle core communicates with the plugin by looking for particular entry points, often defined in the file <tt>lib.php</tt> within the plugin.

==An overview of Moodle core==

Moodle core provides all the infrastructure necessary to build a Learning Management System. It implements the key concepts that all the different plugins will need to work with. These include:

'''Courses and activities:'''
A Moodle course is a sequence of activities and resources grouped into sections. Courses themselves are organized into a hierarchical set of categories within a Moodle site.

'''Users:'''
In moodle, users are anyone who uses the moodle system. In order to participate in course users need to be enrolled into course with a given role, such as:

*Students
*Teachers

'''Course enrolment''':

*Enrolment gives user the possibility to participate in course as a student or teacher.

'''User functionality in moodle:'''

*User roles in moodle: Roles assigned to users give them a set of capabilities in given context. For example: Teacher, Student and Forum moderator are examples of roles.
*User's capabilities in moodle: A capability is a description of some particular Moodle feature. Capabilities are associated with roles. For example, mod/forum:replypost is a capability.
*Context: A context is a "space" in the Moodle, such as courses, activity modules, blocks etc.
*Permissions: A permission is some value that is assigned for a capability for a particular role. For example, allow or prevent.

'''Added facilities provided by moodle: Added facilities provided by moodle:'''

*Creation and editing of user profiles: In moodle, the moment an user creates his account, a profile is created for that user. The user needs to fill in his initial details for completing his profile. The user generally always have the permission to edit his own profile anytime on moodle.
*Groups and cohorts: Cohorts, or site-wide groups, enable all members of a cohort to be enrolled in a course in one action, either manually or synchronised automatically.
*Enrolments and access control: Users are generally enrolled into some courses and according to their permission settings and the groups to which they belong, they have limited access on moodle.

'''A bit more about moodle:'''

*Activity and course completion: The activity completion system allows activities such as Quizzes, SCORM modules, etc. to be marked complete when specified conditions are met.
*Navigation, settings and configuration: The Navigation block provide easy access to view various sections of the Moodle site and includes:
**My home - a personalised home page displaying links to the courses a user is associated with and activity information (such as unread forum posts and upcoming assignments)
**Site pages - links to site pages and resources from the front page of Moodle
**My profile - quick links allowing a user to view their profile, forums posts, blogs and messages as well as manage their private files
**My courses - lists (by course shortname) and links to courses the user is associated with. Click the course's shortname to view the front page of the course or use the arrows to navigate quickly to a specific section, resource or activity.

'''JavaScript library:'''
*Moodle has adopted the Yahoo User Interface library. There is also a nice system for loading the additional JavaScript files required by each page.

'''Upgrading moodle:'''
Moodle can be upgraded in four simple steps:

#Make sure that your server can run the latest Moodle version
#You should always be prepared to "roll back" if there's an issue with your data or some custom code you've added. So before committing, create a test install and always make backups.
#At this stage you can replace the Moodle code on your server with the version you downloaded and check for the plugins.
#Perform the upgrade by triggering the upgrade from the admin page.

(More information about upgrading can be found here : https://docs.moodle.org/27/en/Upgrade_overview)

'''Logs and statistics in moodle:'''
*Statistics in moodle: The statistics graphs and tables show how many hits there have been on various parts of your site during various time frames. They do not show how many distinct users there have been. They are processed daily at a time you specify. You must enable statistics before you will see anything.
*Log in moodle: Logs in Moodle are activity reports. Logs are available at site level and course level.

==The most important plugin types==

===Activities and resources===

Activities and resources are the most basic individual components that make up a course and are the main tools for teaching and learning. Some examples of resources are: pages, links and IMS content packages. Examples of activities include: forums, wikis, quizzes, and assignments.

Activities are by far the largest type of plugin in terms of amount of code. A forum or wiki system could be a software project in its own right. Both activities and resources are installed in the <tt>mod</tt> folder.

===Blocks===

Blocks are small bits of interface functionality that can be added to (normally the sides of) pages. Many blocks provide additional views of data stored and modified elsewhere. Blocks live in the <tt>blocks</tt> folder.

===Themes===

The overall visual style of a Moodle site, a particular course, or all courses in a category, can be changed by selecting a different theme at these different levels. Themes are the standard way of making aesthetic changes to your Moodle application, decoupling presentation from content and functionality.

Themes live in the <tt>theme</tt> folder, and published themes are listed in the [http://moodle.org/mod/data/view.php?id=6552 Themes database].

===Language packs===

Moodle is internationalised. That is, you can get language packs for many different languages. Language packs are normally downloaded and installed via the Moodle administration screens, but they can also be downloaded manually from [http://download.moodle.org/langpack/ Moodle.org: language packs].

Administrators can also manually change any of the standard user interface strings if the terms used in the installed language pack are not appropriate.

===Course formats===

control how the structure of the course, a sequence of activities grouped into sections, is presented to the users. Course formats live in the <tt>course/format</tt> folder.

===Authentication plugins===

control how users log in. Moodle can manage usernames and passwords itself, or use those stored in LDAP or another database. Alternatively, Moodle can use a number of single-sign-on schemes. Authentication plugins live in the <tt>auth</tt> folder.

===Enrolment plugins===

control which users are enrolled in which courses. Again this can be by synchronising with another system, perhaps a student information system, or it can be tracked internally by Moodle. Enrolment plugins live in the <tt>enrol</tt> folder. (Moodle was created by an Australian, so enrol is the correct spelling ;-).)

===Repository plugins===

Ways for users to get content (files) into Moodle, either by uploading from their hard drive, or by getting the file from another location on the Internet, perhaps Drop Box, Google Docs, or Flickr. Repository plugins live in the <tt>repository</tt> folder.

===Others===

There are [[Developer_documentation#Make_a_new_plugin|many more types of plugins]] (more than 30 at the last count). These include text filters, question types, gradebook reports, admin reports, course reports, plagiarism detection services and web service protocols.

For a definitive, up-to-date list, look at the value returned by the <tt>get_plugin_types()</tt> function, which is defined in <tt>lib/moodlelib.php</tt>.

==How Moodle code is organised==

Moodle mostly follows a [http://martinfowler.com/eaaCatalog/transactionScript.html transaction script] approach. That is, suppose you are looking at a Forum. The URL will be <tt>.../mod/forum/view.php?id=1234</tt>. and <tt>mod/forum/view.php</tt> the PHP script that generates that page. One could argue that transaction script is not an appropriate pattern for an application as complex as Moodle. However, it is a very natural architecture for a PHP application, and Moodle is an aggregate of many different plugins, rather than a single complex application.

Behind that basic transaction script approach, a lot of the core functionality has be refactored out into libraries (mostly in the <tt>lib</tt> folder). This provides elements of a [http://martinfowler.com/eaaCatalog/domainModel.html domain model]. The Moodle project started before PHP could handle object-oriented code, however, so don't expect an object-oriented domain model except in some of the more recent parts of the Moodle code.

There are two layers used to separate presentation from the business logic. The outer layer is the theme (see above) which controls the more visual aspects of the Moodle interface. Then there are renderer classes which generate the HTML to be output from the data supplied by the transaction scripts and the domain model. Unfortunately, neither PHP, nor the Moodle architecture, enforces a clear separation of the UI layer. It is possible for sloppy developers to make a mess, and this has happened in the past. The code in the standard Moodle distribution is gradually being cleaned up.

==The Moodle database==

The Moodle database comprises many tables (more than 250) because the whole database is an aggregate of the core tables and the tables belonging to each plugin. Fortunately, this large structure is understandable, because the tables for one particular plugin typically only link to each other and a few core tables. See [[Database_schema_introduction|Database schema introduction]] for more information.

The Moodle database structure is defined in <tt>install.xml</tt> files inside the <tt>db</tt> folder in each plugin. For example <tt>mod/forum/db/install.xml</tt> contains the database definition for the forum module. <tt>lib/db/install.xml</tt> defines the tables used by Moodle core. The <tt>install.xml</tt> files contain comments that should explain the purpose of each table and column. These comments can be turned into human-readable documentation by going to Site administration -> Development -> XMLDB editor in your Moodle installation, and clicking on the [Doc] link.

==See also==

* [[:en:Administrator documentation]]
* [[Developer_documentation|Developer documentation]]
* [[Database_schema_introduction|Database schema introduction]]
* [http://moodle.org/mod/data/view.php?id=6009 Modules and plugins] and [http://moodle.org/mod/data/view.php?id=6552 themes] databases
* [http://moodle.org/mod/forum/discuss.php?d=64465 Forum thread with a vigorous argument about whether an architecture document is a good idea, which eventually lead to this page being rewritten]
* [http://www.aosabook.org/en/moodle.html The chapter of The Architecture of Open Source Applications about Moodle]

[[Category:Coding guidelines]]

Moodle architecture

2014-05-22T16:36:14Z

Conhorne: /* Added MariaDB */

The aim of this document is to quickly give an overview of how the Moodle works at a technical level. Hopefully this will be helpful to Administrators and Developers. However, to actually do Moodle development you will have to study the code in much more detail than is provided here. See the [[Developer_documentation|developer documentation]].

==What is Moodle?==

Moodle is a Learning Management System, Course Management System, or Virtual Learning Environment, depending on which term you prefer. Its goal is to give teachers and students the tools they need to teach and learn. Moodle comes from a background of [[:en:Pedagogy|Social Constructionist pedagogy]], however, it can be used to support any style of teaching and learning.

There are other types of software systems that are important for educational institutions, for example ePortfolios, Student Information Systems and Content repositories. Generally, Moodle does not try to re-invent these areas of functionality. Instead, tries to be the best LMS possible, and then interoperate gracefully with other systems that provide the other areas of functionality. It is, however, perfectly possible to use Moodle as a stand-alone system, without integrating it with anything else.

Moodle is a web application written in PHP. Moodle is open source. Copyright is owned by individual contributors, not assigned to a single entity, although the company Moodle Pty Ltd in Perth Australia, owned by Moodle's founder Martin Dougiamas, manages the project.

==Overview of a Moodle installation==

A Moodle installation comprises the Moodle code executing in a PHP-capable web server; a database managed by MySQL, PostgreSQL, Microsoft SQL Server, MariaDB, or Oracle; and a file store for uploaded and generated files (the moodledata folder).

All three parts can run on a single server; or they can be separated with many load-balanced web-servers, a database cluster, and a file-server; or anywhere between those extremes.

Moodle is designed to be simple to install on any server that meets these basic requirements. Moodle self-installs once the code has been copied to the web server and a blank database created (see [[:en:Installing Moodle]]). Similarly, Moodle can always self-upgrade from one version to the next (see [[:en:Upgrading]]).

==Moodle as a modular system==

Like many successful open source systems, Moodle is structured as an application core, surrounded by numerous plugins to provide specific functionality. Moodle is designed to be highly extensible and customizable without modifying the core libraries, as doing so would create problems when upgrading Moodle to a newer version. So when customizing or extending your own Moodle install, always do so through the plugin architecture.

Plugins in Moodle are of specific types. That is, an authentication plugin and an activity module will communicate with Moodle core using different APIs, tailored to the type of functionality the plugin provides. Functionality common to all plugins (installation, upgrade, permissions, configuration, ...) are, however, handled consistently across all plugin types.

The standard Moodle distribution includes Moodle core and a number of plugins of each type, so that a new Moodle installation can immediately be used to start teaching and learning. After installation a Moodle site can be adapted for a particular purpose by changing the default configuration option, and by installing add-ons or removing standard plugins. Most add-ons that have been shared publicly are listed in the [http://moodle.org/plugins/index.php Moodle Plugins Directory].

Physically, a Moodle plugin is just a folder of PHP scripts (and CSS, JavaScript, etc. if necessary). Moodle core communicates with the plugin by looking for particular entry points, often defined in the file <tt>lib.php</tt> within the plugin.

==An overview of Moodle core==

Moodle core provides all the infrastructure necessary to build a Learning Management System. It implements the key concepts that all the different plugins will need to work with. These include:

'''Courses and activities:'''
A Moodle course is a sequence of activities and resources grouped into sections. Courses themselves are organized into a hierarchical set of categories within a Moodle site.

'''Users:'''
In moodle, users are anyone who uses the moodle system. In order to participate in course users need to be enrolled into course with a given role, such as:

*Students
*Teachers

'''Course enrolment''':

*Enrolment gives user the possibility to participate in course as a student or teacher.

'''User functionality in moodle:'''

*User roles in moodle: Roles assigned to users give them a set of capabilities in given context. For example: Teacher, Student and Forum moderator are examples of roles.
*User's capabilities in moodle: A capability is a description of some particular Moodle feature. Capabilities are associated with roles. For example, mod/forum:replypost is a capability.
*Context: A context is a "space" in the Moodle, such as courses, activity modules, blocks etc.
*Permissions: A permission is some value that is assigned for a capability for a particular role. For example, allow or prevent.

'''Added facilities provided by moodle: Added facilities provided by moodle:'''

*Creation and editing of user profiles: In moodle, the moment an user creates his account, a profile is created for that user. The user needs to fill in his initial details for completing his profile. The user generally always have the permission to edit his own profile anytime on moodle.
*Groups and cohorts: Cohorts, or site-wide groups, enable all members of a cohort to be enrolled in a course in one action, either manually or synchronised automatically.
*Enrolments and access control: Users are generally enrolled into some courses and according to their permission settings and the groups to which they belong, they have limited access on moodle.

'''A bit more about moodle:'''

*Activity and course completion: The activity completion system allows activities such as Quizzes, SCORM modules, etc. to be marked complete when specified conditions are met.
*Navigation, settings and configuration: The Navigation block provide easy access to view various sections of the Moodle site and includes:
**My home - a personalised home page displaying links to the courses a user is associated with and activity information (such as unread forum posts and upcoming assignments)
**Site pages - links to site pages and resources from the front page of Moodle
**My profile - quick links allowing a user to view their profile, forums posts, blogs and messages as well as manage their private files
**My courses - lists (by course shortname) and links to courses the user is associated with. Click the course's shortname to view the front page of the course or use the arrows to navigate quickly to a specific section, resource or activity.

'''JavaScript library:'''
*Moodle has adopted the Yahoo User Interface library. There is also a nice system for loading the additional JavaScript files required by each page.

'''Upgradation of moodle:'''
Moodle can be upgraded in four simple steps:

#Make sure that your server can run the lates Moodle version
#You should always be prepared to "roll back" if there's an issue with your data or some custom code you've added. So before comitting, create a test install and always make backups.
#At this stage you can replace the Moodle code on your server with the version you downloaded and check for the plugins.
#Perform the upgrade by triggering the upgrade from the admin page.

(More information about upgradation can be found here : https://docs.moodle.org/26/en/Upgrade_overview)

'''Logs and statistics in moodle:'''
*Statistics in moodle: The statistics graphs and tables show how many hits there have been on various parts of your site during various time frames. They do not show how many distinct users there have been. They are processed daily at a time you specify. You must enable statistics before you will see anything.
*Log in moodle: Logs in Moodle are activity reports. Logs are available at site level and course level.

==The most important plugin types==

===Activities and resources===

Activities and resources are the most basic individual components that make up a course and are the main tools for teaching and learning. Some examples of resources are: pages, links and IMS content packages. Examples of activities include: forums, wikis, quizzes, and assignments.

Activities are by far the largest type of plugin in terms of amount of code. A forum or wiki system could be a software project in its own right. Both activities and resources are installed in the <tt>mod</tt> folder.

===Blocks===

Blocks are small bits of interface functionality that can be added to (normally the sides of) pages. Many blocks provide additional views of data stored and modified elsewhere. Blocks live in the <tt>blocks</tt> folder.

===Themes===

The overall visual style of a Moodle site, a particular course, or all courses in a category, can be changed by selecting a different theme at these different levels. Themes are the standard way of making aesthetic changes to your Moodle application, decoupling presentation from content and functionality.

Themes live in the <tt>theme</tt> folder, and published themes are listed in the [http://moodle.org/mod/data/view.php?id=6552 Themes database].

===Language packs===

Moodle is internationalised. That is, you can get language packs for many different languages. Language packs are normally downloaded and installed via the Moodle administration screens, but they can also be downloaded manually from [http://download.moodle.org/langpack/ Moodle.org: language packs].

Administrators can also manually change any of the standard user interface strings if the terms used in the installed language pack are not appropriate.

===Course formats===

control how the structure of the course, a sequence of activities grouped into sections, is presented to the users. Course formats live in the <tt>course/format</tt> folder.

===Authentication plugins===

control how users log in. Moodle can manage usernames and passwords itself, or use those stored in LDAP or another database. Alternatively, Moodle can use a number of single-sign-on schemes. Authentication plugins live in the <tt>auth</tt> folder.

===Enrolment plugins===

control which users are enrolled in which courses. Again this can be by synchronising with another system, perhaps a student information system, or it can be tracked internally by Moodle. Enrolment plugins live in the <tt>enrol</tt> folder. (Moodle was created by an Australian, so enrol is the correct spelling ;-).)

===Repository plugins===

Ways for users to get content (files) into Moodle, either by uploading from their hard drive, or by getting the file from another location on the Internet, perhaps Drop Box, Google Docs, or Flickr. Repository plugins live in the <tt>repository</tt> folder.

===Others===

There are [[Developer_documentation#Make_a_new_plugin|many more types of plugins]] (more than 30 at the last count). These include text filters, question types, gradebook reports, admin reports, course reports, plagiarism detection services and web service protocols.

For a definitive, up-to-date list, look at the value returned by the <tt>get_plugin_types()</tt> function, which is defined in <tt>lib/moodlelib.php</tt>.

==How Moodle code is organised==

Moodle mostly follows a [http://martinfowler.com/eaaCatalog/transactionScript.html transaction script] approach. That is, suppose you are looking at a Forum. The URL will be <tt>.../mod/forum/view.php?id=1234</tt>. and <tt>mod/forum/view.php</tt> the PHP script that generates that page. One could argue that transaction script is not an appropriate pattern for an application as complex as Moodle. However, it is a very natural architecture for a PHP application, and Moodle is an aggregate of many different plugins, rather than a single complex application.

Behind that basic transaction script approach, a lot of the core functionality has be refactored out into libraries (mostly in the <tt>lib</tt> folder). This provides elements of a [http://martinfowler.com/eaaCatalog/domainModel.html domain model]. The Moodle project started before PHP could handle object-oriented code, however, so don't expect an object-oriented domain model except in some of the more recent parts of the Moodle code.

There are two layers used to separate presentation from the business logic. The outer layer is the theme (see above) which controls the more visual aspects of the Moodle interface. Then there are renderer classes which generate the HTML to be output from the data supplied by the transaction scripts and the domain model. Unfortunately, neither PHP, nor the Moodle architecture, enforces a clear separation of the UI layer. It is possible for sloppy developers to make a mess, and this has happened in the past. The code in the standard Moodle distribution is gradually being cleaned up.

==The Moodle database==

The Moodle database comprises many tables (more than 250) because the whole database is an aggregate of the core tables and the tables belonging to each plugin. Fortunately, this large structure is understandable, because the tables for one particular plugin typically only link to each other and a few core tables. See [[Database_schema_introduction|Database schema introduction]] for more information.

The Moodle database structure is defined in <tt>install.xml</tt> files inside the <tt>db</tt> folder in each plugin. For example <tt>mod/forum/db/install.xml</tt> contains the database definition for the forum module. <tt>lib/db/install.xml</tt> defines the tables used by Moodle core. The <tt>install.xml</tt> files contain comments that should explain the purpose of each table and column. These comments can be turned into human-readable documentation by going to Site administration -> Development -> XMLDB editor in your Moodle installation, and clicking on the [Doc] link.

==See also==

* [[:en:Administrator documentation]]
* [[Developer_documentation|Developer documentation]]
* [[Database_schema_introduction|Database schema introduction]]
* [http://moodle.org/mod/data/view.php?id=6009 Modules and plugins] and [http://moodle.org/mod/data/view.php?id=6552 themes] databases
* [http://moodle.org/mod/forum/discuss.php?d=64465 Forum thread with a vigorous argument about whether an architecture document is a good idea, which eventually lead to this page being rewritten]
* [http://www.aosabook.org/en/moodle.html The chapter of The Architecture of Open Source Applications about Moodle]

[[Category:Coding guidelines]]

Admin reports

2013-08-13T17:26:10Z

Conhorne: /* What to do in index.php */

{{Moodle 2.1}}
This document applies to Moodle versions before 2.2. See [[Reports]] for the new unified reports in Moodle 2.2 and later.

==Overview==

An admin report is a folder of code under admin/report. For example, you might make a folder in there called '''myreport'''.

In there, the only code you are required to have is an index.php file. This will normally display a simple HTML form for controlling the report, and, the code for displaying the report. You will probably also want a language file, which would be called lang/en_utf8/report_myreport.php following the example above.

In addition, you can add any other PHP code you like, and then link people to it from index.php.

So, the minimal code layout is:

admin/
...
report/
backups/
capability/
...
myreport/
lang/
en_utf8/
report_myreport.php
index.php
...
...

==What to do in index.php==

The simplest way to work this out is by example. You should look at some of the reports that ship with Moodle. [http://cvs.moodle.org/moodle/admin/report/capability/index.php?view=markup admin/report/capability] (warning: capability report does not exist in v2.4+), is a good one to start with. Let us go through that example to see what is there (I will put into italics the bits that are more advanced - the things that the capability report does, but which a simple report will not need to do.):
# Require some libraries. Admin reports will always need config.php and adminlib.php.
# Check the user is logged in and has appropriate permissions. ''(Normally admin reports are controlled by the 'moodle/site:viewreports' capability, the capability report is a special case.)''
# Get the parameters from the URL that control the report, and clean them up a bit.
# ''Include some JavaScript code that enhances the report for people with JavaScript turned on in their browser.''
# Log this request.
# Print the page header. Since this is an administration page, we need to do this using the admin_externalpage... functions. You probably just need to copy these two lines exactly, then replace 'capability' with your report name.
# Display a form to control the report.
# If the URL contains all the parameters needed to generate the report, do so, and display the results. ''(You don't need to understand the details of what the capability report is doing, because your report will do something different. However, the general structure will probably be the same: get some data out of the database, then display it.)''
# Print the footer, using the admin_externalpage... function.
# ''Define some functions, if that is the best way to structure the code of your report. You could, of course, create a separate lib.php file inside your report folder.''

==How your report gets included in the admin tree==

By default, your report will be included in the admin tree under the 'Reports' section, and it will only appear to people with the 'moodle/site:viewreports' capability. If the report is in the ''myreport'' folder, then the report name will be get_string("myreport", "report_''myreport''"). The report name, needed for the call to admin_externalpage_setup, will be "report''myreport''".

If you want more control over how your report appears, for example, if you want it to appear somewhere other than under Reports, or if you want it to be controlled by another capability, then you can create a settings.php file. For example, for the capability report, there is a settings.php file that contains:

<code php>
<?php // $Id$
$ADMIN->add('''"roles"''', new admin_externalpage('reportcapability',
get_string('capability', 'report_capability'),
"$CFG->wwwroot/$CFG->admin/report/capability/index.php",
"moodle/role:manage"
));
?>
</code>

(The two non-standard bits there have been put into bold.)

==Strings you must define in you lang/en_utf8/report_''myreport''.php==

You just need to define

<code php>
$string["myreport"] = 'What my report is called';
</code>

to make the report show up properly in the admin tree, but if your report does anything interesting, you will almost certainly need more.

== Creating a new report in admin block ==

I am using Moodle 1.9. I have created a new reporting module in my local moodle server. I tried following the examples on this page but was not able to get the new report folder to show in my menu, the admin_externalpage functions where failing. To accomplish the same thing, I completed these steps:

'''1 -''' Created a new folder under admin\report, called AU_ProfessionalDevelopment

'''2 -''' Copied index.php and settings.php from the admin\report\question folder into the AU_ProfessionalDevelopment folder.

'''3 -''' edited setting.php, updating the string '''question''' with folder name '''AU_ProfessionalDevelopment'''.

'''4 -''' edited index.php, stripping out most of the code, leaving the following:

<code php>
require_once('../../../config.php');
require_once($CFG->libdir.'/adminlib.php');
admin_externalpage_setup('reportAU_ProfessionalDevelopment');
admin_externalpage_print_header();
admin_externalpage_print_footer();
</code>

'''5''' Reloaded the moodle page (i am logged in as the admin - and can see the Admin. Block). I can see '''AU_ProfessionalDevelopment''' in the admin\report block. Clicking on it loads my page with the admin header and footer.

==See also==

* [http://moodle.org/mod/data/view.php?d=13&rid=913 System images report] this is another very simple report, in contrib. Might be a good one to look at.

[[Category:Plugins]]

Using images in a theme

2011-12-16T17:20:04Z

Conhorne: /* Using your images within you layout files */

{{Template:Themes}}{{Moodle 2.0}}
==A little background==
Moodle 2.0 has introduced a new improved method of making use of images within its pages enabling theme designers to take full control over what images are being used and when possible ensures images are passed through Moodle's new performance caching system to obtain the best possible performance.

$CFG->themewww and custom pix in Moodle 1.9 and lower are gone from Moodle 2.0 and have been replaced by this new system.

==Before we start==

# Make sure you have a theme and images to work with, one that you have a backup of just in case.
# Take note of your theme's main layout file e.g. ''standard.php''.
# Take note of your theme's main CSS file e.g. ''core.css''.
# Turn on '''Theme designer mode'''.

==Image locations within Moodle==

There are three main areas in which images are located - core, plugin and theme.

Core images are used throughout Moodle and are stored in ''moodle/pix''.

The pix directory contains the following subdirectories:

:''a'' - Icons that are not widely used
:''c'' - Calendar-related icons
:''f'' - File icons for different file types
:''g'' - Default user icons and thumbnails
:''i'' - General icons
:''m'' - Currency symbols
:''s'' - Smileys
:''t'' - General icons
:''u'' - User icons and thumbnails
:''y'' - YUI icons

Plugin images are used by plugins and are stored within the plugin's directory e.g. ''mod/forum/*'' or ''blocks/navigation/*''

Theme images are used in themes and are stored in the ''pix'' subdirectory of a theme.

==Adding new images to your theme==

To add new images to your theme, such as a background image or a log, you should start by creating a pix directory within your themes directory.

Lets assume you have two images, gradient.png and logo.jpg. Copy both files to your themes pix directory.

The plan is to use gradient.png as the background image for your theme (in CSS) and use logo.jpg in the header (in your theme's layout file).

===Using images within CSS===

Moodle parses all CSS files. When theme designer mode is off, Moodle combines them into a handful of large CSS files that get cached and served. At the same time Moodle also looks at the CSS and replaces special syntax rules.

<div style='padding:10px;background-color:#f7f7f7;border:1px dashed #123456'><nowiki>[[pix:theme|</nowiki><span style='color:#336699;font-weight:bold;'><nowiki>path/to/image/</nowiki></span><span style='color:#33993A;font-weight:bold;'>imagename</span><nowiki>]]</nowiki></div>

The above pattern is looked for by Moodle and gets replaced with the correct image URL when found.
You should note the following things about this patter when using you own images within CSS:

# The bits in black don't change
# The bit in blue is the path to your image within the pix directory. It shouldn't start with a / but should end with one.
# The bit in green is the filename ('''no need to include the file extension''')

To use background.png as the background for our pages, add the following line of CSS to the themes core.css.
<code css>
body {background-image:url([[pix:theme|gradient]]);}
</code>

Before we look at how to use your own images within your themes layout files we should first look at how this changes if the image is in a sub directory.

Lets assume gradient.png is located here: '''pix/myimages/gradients/gradient.png'''

The CSS would need to be as follows:
<code css>
body {background-image:url([[pix:theme|myimages/gradients/gradient]]);}
</code>

If you want to refer to an image belonging to a plugin, you can do it like this:

<code css>
body {background-image:url([[pix:quiz|icon]]);}
body {background-image:url([[pix:qtype_ddmarker|grid]]);}
</code>

That refers to mod/quiz/pix/icon.png/gif and question/type/ddmarker/pix/grid.png/gif respectively (or whatever icons you have put in your theme to override these).

===Using your images within your layout files===

To use logo.jpg within the header of the layout file, open the layout file e.g. standard.php and find the correct spot to put your logo.

<code php>
....
<div id="page-header" class="clearfix">

<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
echo $OUTPUT->lang_menu();
echo $PAGE->headingmenu;
?></div>
</div>
....
</code>

To achieve this I simply need to add the following line of code:
<code php>
<img src="<?php echo $OUTPUT->pix_url('logo', 'theme'); ?>" alt="" />
</code>
As before, the image's file extension is not needed as Moodle finds it automatically.

Combined the solution is very simple:
<code php>
....
<div id="page-header" class="clearfix">
<img src="<?php echo $OUTPUT->pix_url('logo', 'theme'); ?>" alt="" />
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
echo $OUTPUT->lang_menu();
echo $PAGE->headingmenu;
?></div>
</div>
....
</code>

The only other thing to consider is how this example would look if logo.jpg was located in a subfolder e.g. '''pix/myimages/logos/logo.jpg'''.

The code for this would be:
<code php>
<img src="<?php echo $OUTPUT->pix_url('myimages/logos/logo', 'theme'); ?>" alt="" />
</code>

==Overriding images in your theme==

Overriding images within your theme can be an important part of creating and/or modifying themes.

As mentioned, there are three main areas for images within Moodle, core, plugins, and themes. Obviously we won't be overriding theme images as we are in a theme and have full control over that already which just leaves core and plugin images that you may want to override.

Within your theme create the following two directories:
; /pix_core/ : This is where your images to override core images will need to be.
; /pix_plugins/ : This is where images to override plugins will need to be.

Next, copy the images that you wish to override into either the pix_core or pix_plugins directory. You need to replicate the directory structure that the images are located in.

The following two examples illustrate how this works for both core and plugin images.

===Overriding core images===
For this example I am going to override the following two images:
# '''moodle/pix/help.gif''' This image is used for all help image icons and is shown throughout Moodle.
# '''moodle/pix/i/info.gif''' This image is used in several places, most notably the front page if the combo list is being displayed.

So first up help.gif. This is the most basic example of overriding an image. Because the image is directly within Moodle's pix directory we can simply place our new help image into our themes pix_core directory. There's nothing more to it!

The second example if not really any more difficult. Because the image is located within the subdirectory '''i''' we must create a sub directory within our pix_core directory into which we will copy our new help image. That is, the image ends up at '''/pix_core/i/info.png''' inside your theme folder. And again done!

You should also note that, as with any other image in Moodle, the extension doesn't matter. If you want to replace help.gif with a help.png you can just put the png into the correct directory. As long as the filename is the same Moodle will find it.

===Overriding plugin images===
This is a little bit more difficult than overriding core images, but not too much so. For this example, let's say I want to override the following two plugin images:
# '''moodle/mod/forum/icon.gif''' This is the icon that is used everywhere for the forum.
# '''moodle/blocks/customblock/activate.png''' This is an icon in a custom block I have installed.

First up, the forum icon. Just as with core images, we need to put the image in the correct directory structure. In this case it is going to be within our theme's pix_plugins directory.

Here we need to create the directory structure between '''/mod/''' and the image, so we need the following structure '''/pix_plugins/mod/forum/''' and into the final forum directory we put our replacement image.

The second example is done in exactly the same way, but with the blocks path. We simply need to put our replacement image in '''/pix_plugins/blocks/customblock/''' and it will automatically be overridden.

==Example: Silkicons theme==
As an example of how this all looks when done I have attached a screen shot of a theme I quickly created using the Silk icon set created by Mark James available at [http://famfamfam.com/lab/icons/silk/ http://famfamfam.com/lab/icons/silk/].

[[Image:Silkicon.theme.screenshot.jpg]]

I have also uploaded the this file to this forum discussion if you would like to check it out for yourself.
[http://moodle.org/mod/forum/discuss.php?d=151581 http://moodle.org/mod/forum/discuss.php?d=151581]

==More information==

[[Themes 2.0]]

[[Themes 2.0 creating your first theme]]

[[Plugins]]

[http://moodle.org/mod/forum/discuss.php?d=151581 http://moodle.org/mod/forum/discuss.php?d=151581]

Talk:Using images in a theme

2011-12-16T17:19:06Z

Conhorne: /* standard.php ?? */ new section

Just had a quick browse through this, I have not tested this but are there file extensions missing in the examples?

e.g. -
<code css>
body {background-image:url([[pix:theme|gradient]]);}
</code>

shouldn't this read -
<code css>
body {background-image:url([[pix:theme|gradient.png]]);}
</code>

--Matthew Cannings

No. It is intentional.

It is not really important for theme images. After all, if you are making a theme, you probably do know what type your images are. However, suppose in your theme you want to override one of the standard icons, for example i/edit. Well, even though the standard images is i/edit.gif, you might want to replace it with i/edit.png in your theme, and you can, and Moodle will find the image as long as it is one of the supported formats. We use the same basic system for all images (theme, core and plugin) so that is why you must not specify the extension when you link to the image, and you can use any format you like.--[[User:Tim Hunt|Tim Hunt]] 18:50, 10 June 2010 (UTC)

These documents are essentially for developers, but is there going to be a plainer version for us who do not speak the necessary jargon? I have been trying to figure out how to explain this in the [[Front Page FAQ]] to provide people looking at Moodle 2.0 with a hope of including their own logos onto their selected themes. Seriously, I do not have either the time or the patience to learn PHP to the point where I might be able to explain it in a non-technical manner. From what I am able to decipher, it might be easier than earlier versions, but I cannot be sure. --[[User:Colin Fraser|Colin Fraser]] 09:02, 2 October 2010 (UTC)

== couple small errors ==

In the text below, the second "pattern" has no "n", and I believe "background.png" should be "gradient.png".

----

The above pattern is looked for by Moodle and gets replaced with the correct image URL when found. You should note the following things about this '''patter''' when using you own images within CSS:

1. The bits in black don't change
2. The bit in blue is the path to your image within the pix directory. It shouldn't start with a / but should end with one.
3. The bit in green is the filename (no need to include the file extension)

To use '''background.png''' as the background for our pages, add the following line of CSS to the themes core.css.

body {background-image:url([[pix:theme|gradient]]);}

-------

: If you spot something that is clearly a typo, please just fix it directly. Thanks. Also, I don't think that it matters, for this example, whether the code uses background or gradient.--[[User:Tim Hunt|Tim Hunt]] 14:19, 8 October 2010 (UTC)

== standard.php ?? ==

The instructions say "open the layout file e.g. standard.php". I don't see any file called standard.php in version 2.2. So what file am I looking for?