Plugin files: Difference between revisions
David Mudrak (talk | contribs) m (Add info about the CHANGES file support) |
mNo edit summary |
||
(10 intermediate revisions by 4 users not shown) | |||
Line 1: | Line 1: | ||
{{Plugins development}} | {{Plugins development}} | ||
The following is a list of files that work the same in all [[Plugin types|plugin types]] (if they are present). | |||
=== version.php === | === version.php === | ||
Line 22: | Line 22: | ||
* [[Coding style#Functions and Methods]] | * [[Coding style#Functions and Methods]] | ||
=== db/install.xml === | === db/install.xml === | ||
Line 68: | Line 69: | ||
* [[Web services API]] | * [[Web services API]] | ||
* [[External functions API]] | * [[External functions API]] | ||
=== db/renamedclasses.php === | |||
Details of classes that have been renamed to fit in with autoloading. See [https://moodle.org/mod/forum/discuss.php?d=262403 forum discussion] for details | |||
=== classes/ === | === classes/ === | ||
Line 73: | Line 78: | ||
* [[Automatic class loading]] | * [[Automatic class loading]] | ||
* [[Coding style#Namespaces]] | * [[Coding style#Namespaces]] | ||
=== cli/ === | |||
It is a convention in the Moodle code that all [[CLI scripts]] are put into the <tt>cli/</tt> folder inside the plugin directory. Make sure all these files declare themselves as CLI scripts properly (the constant must be defined prior to loading the config.php): | |||
<code php> | |||
define('CLI_SCRIPT', true); | |||
require(__DIR__.'/../../../config.php'); | |||
require_once($CFG->libdir.'/clilib.php'); | |||
</code> | |||
=== settings.php === | === settings.php === | ||
Line 100: | Line 115: | ||
* [[jQuery pre2.9]] | * [[jQuery pre2.9]] | ||
=== styles.css === | |||
The plugin's CSS are stored here. | |||
* [[Plugin contribution checklist#CSS styles]] | |||
* [[CSS Coding Style]] | |||
=== pix/icon.svg === | === pix/icon.svg === | ||
Line 134: | Line 156: | ||
Locations defined in this file are excluded from the coding style prechecks that are executed during the [[Plugin validation]]. | Locations defined in this file are excluded from the coding style prechecks that are executed during the [[Plugin validation]]. | ||
More information about 3rd party libraries can be found at: https://docs.moodle.org/dev/Third_Party_Libraries | |||
=== readme_moodle.txt === | |||
The file should contain detailed instructions on how to import 3rd party libraries into Moodle. This should list: | |||
* Download URLs | |||
* Build instructions | |||
More information about 3rd party libraries can be found at: https://docs.moodle.org/dev/Third_Party_Libraries | |||
=== environment.xml === | |||
Plugin can declare its additional environment requirements via this file - such as compulsory presence of some otherwise optional PHP extension. See [[Environment checking#Configuration file overview]] for details of the syntax. | |||
<code xml> | |||
<?xml version="1.0" encoding="UTF-8" ?> | |||
<COMPATIBILITY_MATRIX> | |||
<PLUGIN name="plugintype_pluginname"> | |||
<PHP_EXTENSIONS> | |||
<PHP_EXTENSION name="soap" level="required"> | |||
</PHP_EXTENSION> | |||
</PHP_EXTENSIONS> | |||
</PLUGIN> | |||
</COMPATIBILITY_MATRIX> | |||
</code> | |||
=== README === | === README === | ||
Line 142: | Line 191: | ||
If the file <tt>CHANGES.md</tt> (or <tt>CHANGES.txt</tt>, <tt>CHANGES.html</tt> or just <tt>CHANGES</tt> alternatively) is found when uploading a new plugin version into the [[Plugins directory]], then the contents of this file is used to pre-fill the release notes field for the new version. | If the file <tt>CHANGES.md</tt> (or <tt>CHANGES.txt</tt>, <tt>CHANGES.html</tt> or just <tt>CHANGES</tt> alternatively) is found when uploading a new plugin version into the [[Plugins directory]], then the contents of this file is used to pre-fill the release notes field for the new version. | ||
== See also == | |||
* [[Moodle architecture]] - general overview of Moodle code architecture | |||
* [[Plugin types]] - list of all supported plugin types | |||
* [https://moodle.org/plugins/ Moodle plugins directory] - repository of contributed plugins for Moodle | |||
* [https://moodle.org/plugins/tool_pluginskel Moodle plugin skeleton generator] - allows to quickly generate code skeleton for a new plugin | |||
* [https://docs.moodle.org/dev/Plugin_contribution_checklist Checklist for plugin contributors] - read before submitting a plugin |
Revision as of 10:10, 10 July 2018
The following is a list of files that work the same in all plugin types (if they are present).
version.php
Meta-data about the plugin (like the version number, dependencies or the maturity level) are defined here.
- version.php page provides detailed description of the file contents
lang/en/plugintype_pluginname.php
English strings for the plugin are defined here. At least $string['pluginname'] must be present. There is an exception for the Activity modules, their expected file name is just pluginname.php (without the mod_ prefix).
- String API provides information about the string files
lib.php
The interface between the Moodle core and the plugin is defined here for the most plugin types. The expected contents of the file depends on the particular plugin type.
Moodle core often (but not always) loads all the lib.php files of the given plugin types. For the performance reasons, it is strongly recommended to keep this file as small as possible and have just required code implemented in it. All the plugin's internal logic should be implemented in the auto-loaded classes or in the locallib.php file.
db/install.xml
The plugin's database scheme (tables, fields, indexes and keys) are defined here. You should always use the in-built XMLDB editor to generate this file.
db/upgrade.php
Upgrade steps (such as database scheme changes and other things that must happen when the plugin is being upgraded) are defined here. The in-built XMLDB editor can be used to generate the code to change the database scheme.
db/access.php
Plugin capabilities are defined here.
db/install.php
Allows you to execute a PHP code right after the plugin's database scheme has been installed.
db/uninstall.php
Allows you to execute a PHP code before the plugin's database tables and data are dropped during the plugin uninstallation.
db/events.php
Event handlers (subscriptions) are defined here. It lists all the events that your plugin want to observe and be notified about.
db/messages.php
Allow to declare your plugin as the messaging provider.
db/services.php
External functions and web services provided by your plugin are described here.
db/renamedclasses.php
Details of classes that have been renamed to fit in with autoloading. See forum discussion for details
classes/
cli/
It is a convention in the Moodle code that all CLI scripts are put into the cli/ folder inside the plugin directory. Make sure all these files declare themselves as CLI scripts properly (the constant must be defined prior to loading the config.php):
define('CLI_SCRIPT', true);
require(__DIR__.'/../../../config.php');
require_once($CFG->libdir.'/clilib.php');
settings.php
Describes the administration configuration for your plugin.
The setting names are supposed to be plugintype_pluginname/settingname (note the slash) and not plugintype_pluginname_settingname or even just settingname. This makes them to be stored in the config_plugins table without polluting the global $CFG object.
amd/
Plugin's Javascript modules written using the Asynchronous Module Definition (AMD, supported since Moodle 2.9).
yui/
Plugin's YUI modules (recommended way to include Javascript in Moodle 2.8 and older).
jquery/
Plugin's jQuery modules (Moodle 2.8 and older)
styles.css
The plugin's CSS are stored here.
pix/icon.svg
The plugin's icon. Activity modules should provide 24 x 24 px colour icons. All other plugin files should be represented by 16 x 16 px monochrome icon. There should be a fallback pix/icon.png version of the icon for legacy browsers.
- Moodle icons provides icons design guidelines
thirdpartylibs.xml
The file should list all 3rd party libraries bundled with a plugin.
<?xml version="1.0"?>
<libraries>
<library>
<location>javascript/html5shiv.js</location>
<name>Html5Shiv</name>
<version>3.6.2</version>
<license>Apache</license>
<licenseversion>2.0</licenseversion>
</library>
<library>
<location>vendor/guzzle/guzzle/</location>
<name>guzzle</name>
<version>v3.9.3</version>
<license>MIT</license>
<licenseversion></licenseversion>
</library>
</libraries>
The location is a path to the library directory or file, relative to the plugin's root directory. Please note that license must be always compatible with the GNU GPLv3.
Locations defined in this file are excluded from the coding style prechecks that are executed during the Plugin validation.
More information about 3rd party libraries can be found at: https://docs.moodle.org/dev/Third_Party_Libraries
readme_moodle.txt
The file should contain detailed instructions on how to import 3rd party libraries into Moodle. This should list:
- Download URLs
- Build instructions
More information about 3rd party libraries can be found at: https://docs.moodle.org/dev/Third_Party_Libraries
environment.xml
Plugin can declare its additional environment requirements via this file - such as compulsory presence of some otherwise optional PHP extension. See Environment checking#Configuration file overview for details of the syntax.
<?xml version="1.0" encoding="UTF-8" ?>
<COMPATIBILITY_MATRIX>
<PLUGIN name="plugintype_pluginname">
<PHP_EXTENSIONS>
<PHP_EXTENSION name="soap" level="required">
</PHP_EXTENSION>
</PHP_EXTENSIONS>
</PLUGIN>
</COMPATIBILITY_MATRIX>
README
The file README.md or README.txt should contain useful information about the plugin. Ideally, it should act as an offline version of all the informations that are available at the plugin's page in the Plugins directory.
CHANGES
If the file CHANGES.md (or CHANGES.txt, CHANGES.html or just CHANGES alternatively) is found when uploading a new plugin version into the Plugins directory, then the contents of this file is used to pre-fill the release notes field for the new version.
See also
- Moodle architecture - general overview of Moodle code architecture
- Plugin types - list of all supported plugin types
- Moodle plugins directory - repository of contributed plugins for Moodle
- Moodle plugin skeleton generator - allows to quickly generate code skeleton for a new plugin
- Checklist for plugin contributors - read before submitting a plugin