Making changes show up during development: Difference between revisions
(Created page with "Sometime, when you are trying to do Moodle development, you edit the code, and nothing seems to change as a result. This is because, to improve performance, Moodle now has all...") |
m (Some enhancements and clarifications that I encountered during my developer experience.) |
||
(8 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
Sometime, when you are trying to do Moodle development, you edit the code, and nothing seems to change as a result. This is because, to improve performance, Moodle now has all sorts of caching built in. When this is happening, this page will try to give you the quickest way to make your changes show up in all situation. | Sometime, when you are trying to do Moodle development, you edit the code, and nothing seems to change as a result. This is because, to improve performance, Moodle now has all sorts of caching built in. When this is happening, this page will try to give you the quickest way to make your changes show up in all situation. | ||
== General advice == | |||
# In your development site, change most of the admin settings like 'Cache language strings', 'Cache JavaScript' to be suitable for development. Note that doing this will slow down your development site a bit. | |||
==General advice== | |||
# In your development site, change most of the admin settings like 'Cache language strings', 'Cache JavaScript' to be | |||
# If in doubt, visit <nowiki>http://your.domain/moodle</nowiki>'''/admin''' to check that the Moodle install is up-to-date. | # If in doubt, visit <nowiki>http://your.domain/moodle</nowiki>'''/admin''' to check that the Moodle install is up-to-date. | ||
# And then <nowiki>http://your.domain/moodle</nowiki>''' | # And then <nowiki>http://your.domain/moodle</nowiki>'''/admin/purgecaches.php''' and click the 'Purge all caches' button. This will slow things down for the next few requests, until the caches have re-populated. Note there is also a CLI tool to purge caches. | ||
# Depending on what you changed in your plugin, then in addition to the above, you may need to remember to increase the version number in version.php, or the changes will not show up. | # Depending on what you changed in your plugin, then in addition to the above, you may need to remember to increase the version number in the plugin's version.php, or the changes will not show up. | ||
# You may have | # You may have forgotten to run grunt. | ||
# If you have just added a new Behat or PHPunit test, you may need to re-run admin/tool/.../cli/init.php. | # If you have just added a new Behat or PHPunit test, you may need to re-run admin/tool/.../cli/init.php | ||
The above steps are a brute force approach. They will probably work, but are probably not the fastest way. | |||
Here's a quick overview about what changes need which actions to be followed with. Below, we list for all the various type of change you can make, the most efficient way to make the change show up. | |||
== | Keep in mind that once you're done developing your plugin, you should '''always''' bump the version number. | ||
{| class="wikitable" | |||
|+ | |||
!Changed | |||
!Delete specific cache | |||
!Purge all caches | |||
!Bump plugin version | |||
!Other | |||
|- | |||
|PHP | |||
|opcache, if enabled | |||
| - | |||
| - | |||
| | |||
|- | |||
|Autoloaded classes | |||
|x | |||
| - | |||
| - | |||
| | |||
|- | |||
|JavaScript | |||
|x | |||
| - | |||
| - | |||
| | |||
|- | |||
|CSS, SCSS, LESS | |||
|x | |||
| - | |||
| - | |||
| | |||
|- | |||
|Language strings | |||
|x | |||
| - | |||
| - | |||
| | |||
|- | |||
|Capabilities | |||
| - | |||
| - | |||
|x | |||
| | |||
|- | |||
|Events | |||
|? | |||
|? | |||
|? | |||
| | |||
|- | |||
|Scheduled tasks | |||
| - | |||
| - | |||
|x | |||
| | |||
|- | |||
|Web services | |||
|? | |||
|? | |||
|? | |||
| | |||
|- | |||
|Database structure | |||
| - | |||
| - | |||
|x | |||
| | |||
|- | |||
|Behat | |||
| - | |||
| - | |||
| - | |||
|see below | |||
|} | |||
== PHP == | |||
After changing the PHP files (*.php), you should just need to press reload (F5) in your browser. | |||
If you somehow have opcache enabled on your server, you may have to delete it depending on your settings. | |||
=== Adding or removing an autoloaded class === | |||
If you get class-not-found errors, you need to either do any of these: | |||
* GUI: visit <nowiki>http://your.domain/moodle</nowiki>'''/admin''' | |||
===Adding or removing an | * File system: Delete the file '''core_component.php''' in the moodledata cache directory. | ||
== JavaScript == | |||
If you get class-not-found errors, you need to visit <nowiki>http://your.domain/moodle</nowiki>'''/admin''' | '''Note''': if you do plugin development run the grunt task from the base directory of your plugin, not Moodle root. This speeds up the build process, because only the js files in your plugin will be build (which is way faster than building everyting from Moodle root). | ||
== | |||
=== AMD Modules === | |||
While changing older [[Javascript Modules|AMD Javascript Module]] source files (amd/src/*.js), if you have Administration -> Appearance -> AJAX and Javascript -> Cache Javascript turned off, then you should just need to reload (F5) in your browser. If JS caching is on, you need to re-run grunt, because Moodle will always prefer to load the minified modules then. | |||
=== ES Modules === | |||
If you're using the newer ES module syntax, you always have to re-run grunt or have it running in watch mode, as the normal js files need to be transpiled by grunt (using babel) to be usable. | |||
== CSS, SCSS, LESS == | |||
After changing the CSS styles (*.css, *.scss, *.less) you may either: | |||
* GUI: Purge all caches via '''/admin/purgecaches.php''' | |||
* CLI: run '''php admin/purgecaches.php''' | |||
* "developer way": Write a mini script that calls '''theme_reset_all_caches()''' | |||
== Language strings == | |||
After changing language pack strings (lang/en/type_plugin.php), you may either: | |||
* Prevention: The best option is to turn off Admin -> Language -> Language settings -> Cache all language strings when doing development. Then you only need to press F5 to refresh to see your changes. | |||
* GUI: Otherwise you need to Purge all caches (or just the Language strings cache) before reloading. | |||
* CLI: run '''php admin/purgecaches.php''' | |||
* "developer_way": Write a mini script that calls '''get_string_manager()->reset_caches()''' | |||
== Capabilities == | |||
After changing capabilities (db/access.php) you need to | |||
# Bump the plugin version number. | |||
# Go to admin -> Notifications. | |||
Then check that the capabilities show up on Site administration > Users > Permissions > Define roles for any role. | |||
== Events == | |||
After changing event listeners (db/events.php) you don't seem to need to do anything. Event listeners don't seem to be cached in any way. | |||
== Scheduled tasks == | |||
After changing scheduled tasks (db/tasks.php) you need to | |||
# Bump the plugin version number. | |||
# Go to admin -> Notifications. | |||
Then check that the task shows up on Admin -> Server -> Scheduled tasks. | |||
== Web services == | |||
After changing web services (db/services.php) ... | |||
== Database structure == | |||
After changing the database scheme (db/install.xml, db/upgrade.php): | |||
== | * Run the update process of you Moodle site before doing any of your custom schema changes. | ||
* Make a database dump now with a recent up to date database. | |||
* Bump the version and then run the upgrade process. | |||
* Check that your changes are in place as you want them, if not restore the dump and rerun the update/install process. | |||
== PHPunit == | |||
After you add/delete/rename any files that contain php unittests, you need to re-run: | |||
$ php admin/tool/phpunit/cli/init.php | |||
If you are doing the kind of development | == Behat == | ||
After you add a new *.feature file, you need to re-run | |||
$ php admin/tool/behat/cli/init.php | |||
== Mobile support for plugins == | |||
If you are doing the kind of development described in [[Mobile support for plugins]], using a pre-built version of the app like https://mobileapp.moodledemo.net/. | |||
Note, these steps were originally written by people mostly on question type plugins. Hopefully they are generally applicable, but if they don't make sense in your case, that might be why. Please edit to improve them. | Note, these steps were originally written by people mostly on question type plugins. Hopefully they are generally applicable, but if they don't make sense in your case, that might be why. Please edit to improve them. | ||
=== General note === | |||
===General note | |||
If there are lots of red error messages appearing in the JavaScript console (but not the very common error 'ERROR Error: Uncaught (in promise): null...' that repeats every minute and fills the console logs!) it is often necessary to clear site data and restart. | If there are lots of red error messages appearing in the JavaScript console (but not the very common error 'ERROR Error: Uncaught (in promise): null...' that repeats every minute and fills the console logs!) it is often necessary to clear site data and restart. | ||
# In browser developer tools, go to Application -> Clear storage. | # In browser developer tools, go to Application -> Clear storage. | ||
# Close the browser, and re-launch. | # Close the browser, and re-launch. | ||
===Adding mobile support to a plugin for the first time=== | ===Adding mobile support to a plugin for the first time=== | ||
# Bump the plugin version number. | # Bump the plugin version number. | ||
# Go to admin -> Notifications. | # Go to admin -> Notifications. | ||
# F5 in the app to restart. | # F5 in the app to restart. | ||
=== HTML template === | |||
=== | After changing an existing template (mobile/*.html), just pull down in the app to refresh. | ||
=== Client-side JavaScript === | |||
After changing an existing client-side JavaScript (mobile/*.js), press F5 in the browser developer tools to restart the app. | |||
=== Server-side classes/output/mobile.php === | |||
=== | |||
??? | ??? | ||
=== Mobile CSS === | |||
# Bump version number in db/mobile.php | |||
# Purge caches (specifically the tool_mobile/plugininfo MUC cache) | |||
=== | |||
# | |||
# | |||
# Press F5 to restart the app. | # Press F5 to restart the app. | ||
Latest revision as of 08:24, 14 November 2023
Sometime, when you are trying to do Moodle development, you edit the code, and nothing seems to change as a result. This is because, to improve performance, Moodle now has all sorts of caching built in. When this is happening, this page will try to give you the quickest way to make your changes show up in all situation.
General advice
- In your development site, change most of the admin settings like 'Cache language strings', 'Cache JavaScript' to be suitable for development. Note that doing this will slow down your development site a bit.
- If in doubt, visit http://your.domain/moodle/admin to check that the Moodle install is up-to-date.
- And then http://your.domain/moodle/admin/purgecaches.php and click the 'Purge all caches' button. This will slow things down for the next few requests, until the caches have re-populated. Note there is also a CLI tool to purge caches.
- Depending on what you changed in your plugin, then in addition to the above, you may need to remember to increase the version number in the plugin's version.php, or the changes will not show up.
- You may have forgotten to run grunt.
- If you have just added a new Behat or PHPunit test, you may need to re-run admin/tool/.../cli/init.php
The above steps are a brute force approach. They will probably work, but are probably not the fastest way.
Here's a quick overview about what changes need which actions to be followed with. Below, we list for all the various type of change you can make, the most efficient way to make the change show up.
Keep in mind that once you're done developing your plugin, you should always bump the version number.
Changed | Delete specific cache | Purge all caches | Bump plugin version | Other |
---|---|---|---|---|
PHP | opcache, if enabled | - | - | |
Autoloaded classes | x | - | - | |
JavaScript | x | - | - | |
CSS, SCSS, LESS | x | - | - | |
Language strings | x | - | - | |
Capabilities | - | - | x | |
Events | ? | ? | ? | |
Scheduled tasks | - | - | x | |
Web services | ? | ? | ? | |
Database structure | - | - | x | |
Behat | - | - | - | see below |
PHP
After changing the PHP files (*.php), you should just need to press reload (F5) in your browser.
If you somehow have opcache enabled on your server, you may have to delete it depending on your settings.
Adding or removing an autoloaded class
If you get class-not-found errors, you need to either do any of these:
- GUI: visit http://your.domain/moodle/admin
- File system: Delete the file core_component.php in the moodledata cache directory.
JavaScript
Note: if you do plugin development run the grunt task from the base directory of your plugin, not Moodle root. This speeds up the build process, because only the js files in your plugin will be build (which is way faster than building everyting from Moodle root).
AMD Modules
While changing older AMD Javascript Module source files (amd/src/*.js), if you have Administration -> Appearance -> AJAX and Javascript -> Cache Javascript turned off, then you should just need to reload (F5) in your browser. If JS caching is on, you need to re-run grunt, because Moodle will always prefer to load the minified modules then.
ES Modules
If you're using the newer ES module syntax, you always have to re-run grunt or have it running in watch mode, as the normal js files need to be transpiled by grunt (using babel) to be usable.
CSS, SCSS, LESS
After changing the CSS styles (*.css, *.scss, *.less) you may either:
- GUI: Purge all caches via /admin/purgecaches.php
- CLI: run php admin/purgecaches.php
- "developer way": Write a mini script that calls theme_reset_all_caches()
Language strings
After changing language pack strings (lang/en/type_plugin.php), you may either:
- Prevention: The best option is to turn off Admin -> Language -> Language settings -> Cache all language strings when doing development. Then you only need to press F5 to refresh to see your changes.
- GUI: Otherwise you need to Purge all caches (or just the Language strings cache) before reloading.
- CLI: run php admin/purgecaches.php
- "developer_way": Write a mini script that calls get_string_manager()->reset_caches()
Capabilities
After changing capabilities (db/access.php) you need to
- Bump the plugin version number.
- Go to admin -> Notifications.
Then check that the capabilities show up on Site administration > Users > Permissions > Define roles for any role.
Events
After changing event listeners (db/events.php) you don't seem to need to do anything. Event listeners don't seem to be cached in any way.
Scheduled tasks
After changing scheduled tasks (db/tasks.php) you need to
- Bump the plugin version number.
- Go to admin -> Notifications.
Then check that the task shows up on Admin -> Server -> Scheduled tasks.
Web services
After changing web services (db/services.php) ...
Database structure
After changing the database scheme (db/install.xml, db/upgrade.php):
- Run the update process of you Moodle site before doing any of your custom schema changes.
- Make a database dump now with a recent up to date database.
- Bump the version and then run the upgrade process.
- Check that your changes are in place as you want them, if not restore the dump and rerun the update/install process.
PHPunit
After you add/delete/rename any files that contain php unittests, you need to re-run:
$ php admin/tool/phpunit/cli/init.php
Behat
After you add a new *.feature file, you need to re-run
$ php admin/tool/behat/cli/init.php
Mobile support for plugins
If you are doing the kind of development described in Mobile support for plugins, using a pre-built version of the app like https://mobileapp.moodledemo.net/.
Note, these steps were originally written by people mostly on question type plugins. Hopefully they are generally applicable, but if they don't make sense in your case, that might be why. Please edit to improve them.
General note
If there are lots of red error messages appearing in the JavaScript console (but not the very common error 'ERROR Error: Uncaught (in promise): null...' that repeats every minute and fills the console logs!) it is often necessary to clear site data and restart.
- In browser developer tools, go to Application -> Clear storage.
- Close the browser, and re-launch.
Adding mobile support to a plugin for the first time
- Bump the plugin version number.
- Go to admin -> Notifications.
- F5 in the app to restart.
HTML template
After changing an existing template (mobile/*.html), just pull down in the app to refresh.
Client-side JavaScript
After changing an existing client-side JavaScript (mobile/*.js), press F5 in the browser developer tools to restart the app.
Server-side classes/output/mobile.php
???
Mobile CSS
- Bump version number in db/mobile.php
- Purge caches (specifically the tool_mobile/plugininfo MUC cache)
- Press F5 to restart the app.