Installing add-ons: Difference between revisions

Revision as of 16:17, 2 May 2013

An add-on is an optional plugin for adding additional features and functionality to Moodle, such as new activities, new quiz question types, new reports, integrations with other systems and many more.

What is meant by the words 'plugin' and 'add-on'?

Moodle = core code + plugins

Plugins may be either standard plugins (included in the Moodle download package) or add-ons.

Before you do anything else...

VERY IMPORTANT Warning: Please be aware that some add-ons have not been reviewed, and the quality and/or suitability for your Moodle site has not been checked. Please be careful. It may not do what you expect, it may have serious security issues or it may even not work at all.

Do you really need the add-on? More functionality means more things to support, more things to (potentially) go wrong and more things to worry about at upgrade time.
Is the add-on supported and maintained? If something goes wrong can you get support? Will bugs be fixed?
If the add-on does not work in a future version of Moodle, what will you do about it?
Beware of patches! If an add-on modifies or replaces core files then be very careful. It can only be guaranteed to work with the exact build (version) of Moodle it was created for and is highly unlikely to survive a Moodle upgrade.

Installing an add-on

New feature
in Moodle 2.6! In Moodle 2.5 onwards, add-ons may be from within Moodle, either directly from the Moodle plugins directory or by uploading a ZIP file.

To install an add-on directly from the Moodle plugins directory:

Login as an admin and go to Administration > Site administration > Plugins > Install add-ons.
Click the button 'Install add-ons from Moodle plugins directory'.
Choose a plugin with an Install button (i.e. suitable for 2.5), click the Install button then click Continue.
Check that you obtain a 'Validation passed!' message, then click the button 'Install add-on'.

To install an add-on by uploading a ZIP file:

Go to the Moodle plugins directory, select Moodle 2.5 as version, then choose an add-on with a Download button and download the ZIP file.
Login to your Moodle site as an admin and go to Administration > Site administration > Plugins > Install add-ons.
Upload the ZIP file, select the appropriate plugin type, tick the acknowledgement checkbox, then click the button 'Install add-on from the ZIP file'.
Check that you obtain a 'Validation passed!' message, then click the button 'Install add-on'.

For both methods, after clicking the button 'Install add-on', you will then be automatically redirected to Settings > Site administration > Notifications where you will see a message saying that the add-on is installed.

Note: The add-on may contain language files. They'll be found by your Moodle automatically. These language strings can be customized using the standard Settings > Site administration > Language editing interface.

Uninstalling an add-on

To uninstall an add-on

Go to Settings > Site Administration > Plugins > Plugins overview and click the Uninstall link opposite the add-on you wish to remove
Use a file manager to remove/delete the actual plugin directory as instructed, otherwise Moodle will reinstall it next time you access the site administration

Note: Certain plugin types offer the removal from the disk as well, though not yet all.

Plugins overview

Plugins overview highlighting available update with install button

The Plugins overview page in Settings > Site Administration > Plugins > Plugins overview lists all installed plugins, together with the version number, availability (enabled or disabled) and settings link (if applicable).

A 'Check for available updates' button enables admins to quickly check for any updates available to standard plugins or add-ons installed on the site (from the plugins directory). Any updates available are highlighted, with further information and a download link in the notes column opposite the plugin.

Plugin updating from within Moodle

In Moodle 2.4 onwards, an administrator can enable updates deployment in Administration > Site Administration > Server > Update notifications. Then when updates are available, 'Install this update' buttons are shown on the Plugins overview page. See Automatic updates deployment for more details.

Preventing installing add-ons from within Moodle

If required, installing and updating from within Moodle can be prevented by copying the following lines of code from config-dist.php and pasting them in config.php.

// Use the following flag to completely disable the On-click add-on installation
// feature and hide it from the server administration UI.
//
//      $CFG->disableonclickaddoninstall = true;

@@ Line 1: / Line 1: @@
 {{Installing Moodle}}
-There are optional plugins or add-ons available that can extend Moodle in all sorts of ways - new activities, new quiz question types, new reports, integrations with other systems and many more. This page gives some important advice you should consider before adding them and general advice on how to install them.
+An add-on is an optional plugin for adding additional features and functionality to Moodle, such as new activities, new quiz question types, new reports, integrations with other systems and many more.
 ==What is meant by the words 'plugin' and 'add-on'?==
@@ Line 10: / Line 10: @@
 == Before you do anything else... ==
-'''VERY IMPORTANT''' Warning: Please be aware that some add-ons have not been reviewed, and the quality and/or suitability for your Moodle site has not been checked. Please be careful when considering using one. It may not do what you expect, it may have serious security issues or it may even not work at all.
+'''VERY IMPORTANT''' Warning: Please be aware that some add-ons have not been reviewed, and the quality and/or suitability for your Moodle site has not been checked. Please be careful. It may not do what you expect, it may have serious security issues or it may even not work at all.
 * Do you '''really''' need the add-on? More functionality means more things to support, more things to (potentially) go wrong and more things to worry about at upgrade time.
@@ Line 17: / Line 17: @@
 * Beware of ''patches''! If an add-on modifies or replaces core files then be very careful. It can only be guaranteed to work with the exact build (version) of Moodle it was created for and is highly unlikely to survive a Moodle upgrade.
-=== Moodle requirements ===
+==Installing an add-on==
-* You must have access to your Moodle code files to upload or install the add-on. There is no way to install add-ons through the web interface.
+{{New features}}In Moodle 2.5 onwards, add-ons may be from within Moodle, either directly from the Moodle plugins directory or by uploading a ZIP file.
-* Your add-on may impose additional requirements on the server. In particular, add-ons to access other systems or services may need specific PHP plugins (e.g. LDAP or other database drivers). Check the documentation.
-''You should always look for a 'readme' file or other documentation supplied with the add-on and read that carefully.''
+To install an add-on directly from the Moodle plugins directory:
-==Downloads==
+# Login as an admin and go to ''Administration > Site administration > Plugins > Install add-ons''.
+# Click the button 'Install add-ons from Moodle plugins directory'.
+# Choose a plugin with an Install button (i.e. suitable for 2.5), click the Install button then click Continue.
+# Check that you obtain a 'Validation passed!' message, then click the button 'Install add-on'.
-Add-ons may be downloaded from the [http://moodle.org/plugins/ Moodle plugins directory].
+To install an add-on by uploading a ZIP file:
-Note: Make sure you select the correct version. Most add-ons for Moodle 2.0+ will work in all 2.x versions of Moodle. Question Types changed in Moodle 2.1 and require specific plugins for Moodle 2.1+. Plugins (and themes) for Moodle 1.9 and earlier will NOT work. There is no point trying!
+# Go to the [https://moodle.org/plugins Moodle plugins directory], select Moodle 2.5 as version, then choose an add-on with a Download button and download the ZIP file.
+# Login to your Moodle site as an admin and go to ''Administration > Site administration > Plugins > Install add-ons''.
+# Upload the ZIP file, select the appropriate plugin type, tick the acknowledgement checkbox, then click the button 'Install add-on from the ZIP file'.
+# Check that you obtain a 'Validation passed!' message, then click the button 'Install add-on'.
-==Installation==
+For both methods, after clicking the button 'Install add-on', you will then be automatically redirected to ''Settings > Site administration > Notifications'' where you will see a message saying that the add-on is installed.
-First, establish the correct place in the moodle code 'tree' for the plugin. Some plugins need elements installed in multiple locations. To complicate matters not everybody packages up plugins in the same way. It's best to unzip/unpack the plugin in an empty directory first just to see what it looks like and to check for 'readme' files. Common locations are (there are others):
-* /path/to/moodle/mod/ - modules (i.e. activities and resources)
-* /path/to/moodle/blocks/ - blocks (in the sidebars)
-* /path/to/moodle/question/type/ - questiontypes
-* /path/to/moodle/course/format/ - course formats
-* /path/to/moodle/admin/report/ - admin reports
-* /path/to/moodle/theme/ - themes
-Then:
-# Download the zip file
-# Upload or copy it to your Moodle server
-# Unzip it in the right place for the plugin type (or follow add-on instructions).
-# In your Moodle site (as admin) go to ''Settings > Site administration > Notifications'' (you should, for most plugin types, get a message saying the add-on is installed)
-# Test the add-on
 Note: The add-on may contain language files.  They'll be found by your Moodle automatically. These language strings can be customized using the standard ''Settings > Site administration > Language'' editing interface.
-===If you have problems...===
+==Uninstalling an add-on==
-* Check the file permissions. The web server needs to be able to read the plugin files. If the the rest of Moodle works then try to make the plugin permissions and ownership match.
+To uninstall an add-on
-* Did you '''definitely''' unzip or install the add-on in the correct place?
+# Go to ''Settings > Site Administration > Plugins > Plugins overview'' and click the Uninstall link opposite the add-on you wish to remove
-* Because Moodle scans plugin folders for new plugins you cannot have any other files or folders there. Make sure you deleted the zip file and don't try to rename (for example) an old version of the plugin to some other name - it will break.
+# Use a file manager to remove/delete the actual plugin directory as instructed, otherwise Moodle will reinstall it next time you access the site administration
-* Make sure the directory name for the plugin is correct. All the names '''have''' to match. If you change the name then it won't work.
-* Turn on [[Debugging]] - any error messages?
-* Ask in the appropriate forum in [http://moodle.org/course/view.php?id=5 Using Moodle]. Make sure you describe your system (including versions of MySQL, PHP etc.), what you tried and what happened. Copy and paste error messages exactly. Provide the link to the version of the add-on you downloaded (some have very similar names).
-==Uninstalling a plugin==
+Note: Certain plugin types offer the removal from the disk as well, though not yet all.
-To uninstall a plugin
-# Go to ''Settings > Site Administration > Plugins > Plugins overview'' and click the Uninstall link opposite the plugin you wish to remove
-# Use a file manager to remove/delete the actual plugin directory as instructed, otherwise Moodle will reinstall it next time you access the site administration
 ==Plugins overview==
@@ Line 70: / Line 51: @@
 [[File:plugins overview.png|thumb|left|Plugins overview highlighting available update with install button]]The Plugins overview page in ''Settings > Site Administration > Plugins > Plugins overview'' lists all installed plugins, together with the version number, availability (enabled or disabled) and settings link (if applicable).
-''Note: The open or closed eye icon indicates whether a plugin is enabled or not. However, this icon is not clickable and you cannot change a plugin's availability from here.''
+A 'Check for available updates' button enables admins to quickly check for any updates available to standard plugins or add-ons installed on the site (from the [http://moodle.org/plugins plugins directory]). Any updates available are highlighted, with further information and a download link in the notes column opposite the plugin.
-A 'Check for available updates' button enables admins to quickly check for any updates available to core code and for any contributed plugins installed on the site (from the [http://moodle.org/plugins plugins directory]). Any updates available are highlighted, with further information and a download link in the notes column opposite the plugin.
 ===Plugin updating from within Moodle===
 In Moodle 2.4 onwards, an administrator can enable updates deployment in  ''Administration > Site Administration > Server > Update notifications''. Then when updates are available, 'Install this update' buttons are shown on the Plugins overview page. See [[Automatic updates deployment]] for more details.
+==Preventing installing add-ons from within Moodle==
+If required, installing and updating from within Moodle can be prevented by copying the following lines of code from config-dist.php and pasting them in config.php.
+ // Use the following flag to completely disable the On-click add-on installation
+ // feature and hide it from the server administration UI.
+ //
+ //      $CFG->disableonclickaddoninstall = true;
 ==See also==
@@ Line 83: / Line 71: @@
 *[[Add-on FAQ]]
 *Using Moodle [http://moodle.org/mod/forum/view.php?id=44 General add-ons forum]
-*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=131413 Moodle not installing a new Activity Module] forum discussion
 * [[Installing Moodle from Git repository#Installing a contributed extension from its Git repository|Installing a contributed extension from its Git repository]]
@@ Line 90: / Line 77: @@
 *[[:dev:Category:Plugins|Plugins developer documentation]]
 *[[:dev:Plugin validation]]
+*[[:dev:On-click add-on installation]]
 [[Category:Contributed code]]

Documentation