Plugin with third party libraries: Difference between revisions
From MoodleDocs
Damyon Wiese (talk | contribs) No edit summary |
David Mudrak (talk | contribs) m (Add {{Plugins development}} template) |
||
| (7 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
{{Plugins development}} | |||
This page describes the correct way to include third party libraries with your plugin. | This page describes the correct way to include third party libraries with your plugin. | ||
| Line 7: | Line 9: | ||
The process for including a third party library is the same for core code as it is for a plugin - there are a number of steps to follow. | The process for including a third party library is the same for core code as it is for a plugin - there are a number of steps to follow. | ||
# Check the license | # Check the license to make sure the library uses a GPLv3 compatible license - see the [https://www.gnu.org/licenses/license-list.en.html list of compatible licenses]. If a library is not compatible with GPLv3 then it cannot be distributed together with the plugin in one ZIP package and hosted in the Moodle Plugins directory. | ||
# Check the library is not already shipped by core - we don't want multiple versions of the same library. | # Check the library is not already shipped by core - we don't want multiple versions of the same library. | ||
# Download the latest stable release of the code. | # Download the latest stable release of the code. | ||
# Perform any build steps required to get a distributable version of the library. This will vary depending on the library - but an example is running less to generate minified css files. | # Perform any build steps required to get a distributable version of the library. This will vary depending on the library - but an example is running less to generate minified css files. | ||
# Put that library into a sub folder in your plugin. It is best to NOT use version numbers in the foldername ("jquery" not "jquery-1.7.3"). | # Put that library into a sub folder in your plugin. It is best to NOT use version numbers in the foldername ("jquery" not "jquery-1.7.3"). | ||
# Create or update the "lib/thirdpartylibs.xml" file for your plugin. https://docs.moodle.org/dev/ | # Create or update the "lib/thirdpartylibs.xml" file for your plugin. https://docs.moodle.org/dev/Plugin_files#thirdpartylibs.xml describes this file. | ||
# Create a readme_moodle.txt file in the new third party library folder containing detailed instructions on how to complete steps 3-6 above. This should list download urls, build instructions etc. | # Create a readme_moodle.txt file in the new third party library folder containing detailed instructions on how to complete steps 3-6 above. This should list download urls, build instructions etc. https://docs.moodle.org/dev/Plugin_files#readme_moodle.txt | ||
# Note any creation, update or deletion of third party libraries in your plugins upgrade.txt | # Note any creation, update or deletion of third party libraries in your plugins upgrade.txt or CHANGES. https://docs.moodle.org/dev/Plugin_files#CHANGES | ||
# Run `grunt ignorefiles` to regenerate ignored files path | |||
== Exceptions: == | == Exceptions: == | ||
| Line 21: | Line 23: | ||
=== Javascript AMD modules === | === Javascript AMD modules === | ||
Javascript AMD modules cannot exist in a sub-folder - they must exist in a single .js file in the amd/src folder for your plugin. So - the process for AMD files is the same as above, except that the license and readme_moodle.txt file contents must be added as a javascript comment to the top of the libraries .js file. | Javascript AMD modules cannot exist in a sub-folder - they must exist in a single .js file in the amd/src folder for your plugin. So - the process for AMD files is the same as above, except that the license and readme_moodle.txt file contents must be added as a javascript comment to the top of the libraries .js file. | ||
== See also == | |||
* [[Grunt]] - Information for installing and using Grunt | |||
Revision as of 07:05, 17 June 2020
This page describes the correct way to include third party libraries with your plugin.
A third party library refers to any library where the latest version of the code is not maintained and hosted by Moodle. An example is "Mustache.php". Following this process means that all third party libraries are correctly listed in the page "Site administration -> Development -> Third party libraries", they can be tracked and kept up to date - and we will not introduce conflicting versions of the same library in different places.
Instructions
The process for including a third party library is the same for core code as it is for a plugin - there are a number of steps to follow.
- Check the license to make sure the library uses a GPLv3 compatible license - see the list of compatible licenses. If a library is not compatible with GPLv3 then it cannot be distributed together with the plugin in one ZIP package and hosted in the Moodle Plugins directory.
- Check the library is not already shipped by core - we don't want multiple versions of the same library.
- Download the latest stable release of the code.
- Perform any build steps required to get a distributable version of the library. This will vary depending on the library - but an example is running less to generate minified css files.
- Put that library into a sub folder in your plugin. It is best to NOT use version numbers in the foldername ("jquery" not "jquery-1.7.3").
- Create or update the "lib/thirdpartylibs.xml" file for your plugin. https://docs.moodle.org/dev/Plugin_files#thirdpartylibs.xml describes this file.
- Create a readme_moodle.txt file in the new third party library folder containing detailed instructions on how to complete steps 3-6 above. This should list download urls, build instructions etc. https://docs.moodle.org/dev/Plugin_files#readme_moodle.txt
- Note any creation, update or deletion of third party libraries in your plugins upgrade.txt or CHANGES. https://docs.moodle.org/dev/Plugin_files#CHANGES
- Run `grunt ignorefiles` to regenerate ignored files path
Exceptions:
Javascript AMD modules
Javascript AMD modules cannot exist in a sub-folder - they must exist in a single .js file in the amd/src folder for your plugin. So - the process for AMD files is the same as above, except that the license and readme_moodle.txt file contents must be added as a javascript comment to the top of the libraries .js file.
See also
- Grunt - Information for installing and using Grunt
