Af4m is a set of guidelines to help us create
extensions to Moodle using JavaScript.
It is a framework created to allow us to use existing Moodle infrastructure, and staff's familiarity with Moodle as an advantage and a bedrock to enhance students' learning experience, instead of rebuilding everything from the ground up. The framework is built to allow all Moodle users with editing rights to create extensions to Moodle, effectively opening open-source contributions to Moodle from thousands more users that can write simple JavaScript scripts but cannot build or install Moodle plugins.
Let's go through the guidelines to create addons using the framework.
Addons should be globally available to all VLE users. This is common in web development, where all scripts are within a shared folder on the server. However, editors do not have access to folders on the Moodle server. They do however have access to Moodle courses. And guided by our fundamental rule to use Moodle existing infrastructure to our advantage when building af4m, we have adapted Moodle courses so that they are accessible to all VLE users without needing to be enrolled in them, effectively converting them to repositories.
We do this by simply changing the moodle/course:view permission and adding a phantom Folder resource where we will house all scripts and relevant files for our enhancements.
This is the beauty of addons. They work with surgical precision to enhance one area of interest. If more enhancements are needed for the same course, create one addon for every enhancement.
You can include addons either in sidebar text blocks, or in Text and media areas within a section. You can restrict where the addon will be loaded using relevant display settings for the text block or activity restrictions, but you should restrict further within the addon if needed.
We recommend that you distribute addons using existing Moodle core infrastructure and specifically backups. Another way of distributing addons would be to have clear documentation that contains the HTML snippet that users need to copy/paste in place, as well as how the component containing the snippet needs to be configured.
Alternatively, if you have the "Sharing cart" plugin installed on your Moodle installation, you could use its fine-tuned backup/restore functionality to allow editors to use your addons.
This is fundamental for us. Af4m was built to enhance existing Moodle functionality. Af4m can be used to create completely new functionality as well, so in this case you will have to provide a simple version that should work with your minimum browser requirements and enhance it further to meet the learning experience needed.
If for whatever reason the addon cannot work on the user's browser, graceful degradation should be implemented correctly so that Moodle shows the default/out of the box experience in this case, instead of a broken page.
If possible, use existing Moodle infrastructure that editors are familiar with, instead of rewriting new editing functionality. Enhance for learners but strive to keep as much of Moodle's default functionality in editing as possible to capitalise on academics' familiarity.
Addons can be tested, both using unit testing and integration testing via Behat/Selenium, fully integrating with automated Moodle testing.
To keep things clean and tidy, we recommend that you group addons in relevant repositories. We also recommend that you place all documentation for the addons within the same course as the addons themselves.
You should always write documentation both for developers and for editors/users.