Settings transfer
Introduction
A long time ago, seven and a half years or so, when I was involved with and maintaining the Essential theme (moodle.org/plugins/theme_essential), the thought struck me that with all its settings and thus combinations thereof, that there should be a way of transferring their values from one site to another. This thought was partly influenced through having multiple development versions and needing to configure them in order to attempt the replication of an issue that somebody was having. I needed my version of Essential to look like theirs as much as possible. I also recall chatting to Justin Hunt (moodle.org/plugins/browse.php?list=contributor&id=14534) about the problem. And so I went ahead, looked at the problem and came up with a solution. That solution worked but was lacking one thing, files! The files had to be transferred manually between Moodle installations… until now!
Disclaimers
Names / logos can be trademarks of their respective owners. Please review their website for details. I am independent from the organisations mentioned and am in no way writing for or endorsed by them. The information presented in this article is written according to my own understanding, there could be inaccuracies, so please do undertake your own research. The featured image is my copyright, please don’t use without my permission.
A journey
From Essential, the settings code was ported to other themes, such as Foundation and Adaptable. Since being given Adaptable by Jeremy Hopkins (Jez H at the top of moodle.org/plugins/theme_adaptable/) to maintain and develop further after having already contributed to the theme, I’ve been pondering the files problem for some time. In that time I’ve been learning and developing the skills required, understanding the underlying setting file code along with how Moodle stores and manages its files. In essence getting all of the pieces of the puzzle in place so that they can fit together and work. Some of those pieces being: Seeing how the SVG pattern images that crop up in places such as the ‘Course overview’ block are encoded in base64 format (en.wikipedia.org/wiki/Base64), understanding how the text editor manages ‘draft files’ (moodledev.io/docs/4.4/apis/subsystems/form/usage/files#editors) and how ‘admin_setting_configstoredfile’ (github.com/moodle/moodle/blob/v4.4.3/lib/adminlib.php#L10591-L10760) works.
Its then only after you’ve realised that you have all of the elements understood that you can then work on a practical solution.
The solution
On the ‘Import / export settings’ page in the Moodle 4.1 to 4.4 versions (at the time of typing), there are two new buttons ‘Export properties with files as a JSON string’ and ‘Export properties with files as a JSON file’:
Whist retaining the existing ‘Export properties without files as a JSON string’. I could have just had the new ‘JSON file’ setting, but the files in a JSON string option was actually a stage in the development of the solution. To reach a point, make it work and then add file creation as the next step, and so I kept it to give you flexibility of use.
To help with each option, I’ve added a tooltip to each button to explain what it does.
Export properties with files as a JSON string
Clicking on this button produces the JSON string as before:
You can then select it all and copy it via the clipboard and over to another installation:
Saving the changes to process the JSON string and produce a report:
But instead of a list of files you need to manually transfer, there is a report of what has changed – here I’m just reimporting what I’ve exported on the same site.
Export properties with files as a JSON file
Clicking on this button produces the JSON file in a new setting ‘propertyfiles’:
This is the same as the core setting file manager but can store more than one file. In this case I’ve set it to eight. As with the core version, when deleting a file you have to save changes for that to take effect. The filename is generated down to the nearest second to avoid name conflicts. You can then download the file as shown as you can with other such file manager settings. Once you have, then head off to the target installation where you’ll find another new setting ‘fileputprops’:
Where you can upload / drag and drop the file, then click on ‘Save changes’ at the bottom as we did with the ‘JSON string’ method. The report is then again in the ‘putrops’ box.
Note that when you do reach eight stored setting files, then no more will be added even if the button is pressed until one or more are deleted.
Backward compatibility
Any existing ‘Export properties without files as a JSON string’ strings that you have will can still be imported. Indeed as this is such new functionality I have retained this as a fallback.
The real use to you
This functionality, I hope, will make it much easier for you to configure your test installation first. Tailoring it to exactly how you want, including the images on the slider. Then within moments have the same look on your production installation. You’ll be able to take ‘snapshots’ of how your Adaptable theme looks and retain them as a backup.
Compression?
One thing I haven’t done is compress the files, they are pure text. That was a decision I made given the complexities of the additional code and the need to possibly support different formats. You can compress the files using the mechanisms you know already, thus greater flexibility for you.
Conclusion
I’ve tried to make the functionality as easy to use as possible, providing different means by which the effort you put in to style your installation can be retained and transferred.
Future wise, I hope to port the code to other themes / plugins on a case by case basis. Almost certainly down to the number of settings to make the effort worth while.
- Network fonts – 16th March 2025
- Static translate – 16th February 2025
- Subsections – 16th January 2025
Great post Gareth !
It’s so interesting to understand the background to how this functionality has been added to Adaptable.
And yes, I think the ability to customise the Theme on a test site and then easily transfer that is amazing !
It may also work as a simple ‘template’ for new sites 🙂