Adding theme upgrade code - Revision history

Sarjona: This page will not be migrated to new devdocs

2024-05-03T13:39:49Z

This page will not be migrated to new devdocs

← Older revision		Revision as of 13:39, 3 May 2024
Line 1:		Line 1:
			{{Template:WillNotMigrate}}

	{{Template:Themes}}		{{Template:Themes}}
	As themes have got considerably more advanced in Moodle 2 there is now on occasion a need to write upgrade code for a theme. This quick tutorial looks at just how to do that.		As themes have got considerably more advanced in Moodle 2 there is now on occasion a need to write upgrade code for a theme. This quick tutorial looks at just how to do that.

Mudrd8mz: Text replacement - "`" to ""`


2021-07-14T13:31:02Z
Text replacement - "<code php>" to "<syntaxhighlight lang="php">"

				
				
				
				
				
				← Older revision
				Revision as of 13:31, 14 July 2021
				
Line 14:
Line 14:
The following is an example of what a version.php file for a theme looks like. The following is an example of what a version.php file for a theme looks like.



<code php> <syntaxhighlight lang="php">
<?php <?php



Line 115:
Line 115:



The upgrade.php file should contain just a single function that needs to be named following a strict naming scheme. In the case of my theme that for this example I've called mythemename that function will be as follows: The upgrade.php file should contain just a single function that needs to be named following a strict naming scheme. In the case of my theme that for this example I've called mythemename that function will be as follows:
<code php> <syntaxhighlight lang="php">
<?php <?php



Line 133:
Line 133:
For the following example let's assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb. For the following example let's assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb.



<code php> <syntaxhighlight lang="php">
<?php <?php

`Mudrd8mz: Text replacement - "`" to ""

2021-07-14T13:04:26Z

Text replacement - "</code>" to "</syntaxhighlight>"

← Older revision		Revision as of 13:04, 14 July 2021
Line 26:		Line 26:
	$plugin->requires = 2010122500;		$plugin->requires = 2010122500;
	$plugin->maturity = MATURITY_STABLE;		$plugin->maturity = MATURITY_STABLE;
	</~~code~~>		</syntaxhighlight>

	The first thing to notice here is that we are setting properties of an object called $plugin, this object will be used to describe our theme.		The first thing to notice here is that we are setting properties of an object called $plugin, this object will be used to describe our theme.
Line 75:		Line 75:
	return true;		return true;
	}		}
	</~~code~~>		</syntaxhighlight>

	This special function is called when a theme is first installed (if it has a version.php file and it has been newly added to your Moodle site) or the first time that the theme has a version.php file if you are developing or upgrading a theme.		This special function is called when a theme is first installed (if it has a version.php file and it has been newly added to your Moodle site) or the first time that the theme has a version.php file if you are developing or upgrading a theme.
Line 98:		Line 98:
	return true;		return true;
	}		}
	</~~code~~>		</syntaxhighlight>

	Looking at this code it does the following things:		Looking at this code it does the following things:
Line 125:		Line 125:
	return true;		return true;
	}		}
	</~~code~~>		</syntaxhighlight>

	This special function gets called when ever the admin is upgrading the site and gives our theme the opportunity to run any upgrade code it requires.		This special function gets called when ever the admin is upgrading the site and gives our theme the opportunity to run any upgrade code it requires.
Line 160:		Line 160:
	return true;		return true;
	}		}
	</~~code~~>		</syntaxhighlight>

	Looking at this code it does the following things:		Looking at this code it does the following things:

Mudrd8mz: Text replacement - "`" to ""`


2021-07-14T13:03:49Z
Text replacement - "<code php>  " to "<syntaxhighlight lang="php">"

				
				
				
				
				
				← Older revision
				Revision as of 13:03, 14 July 2021
				
Line 68:
Line 68:



For this example I have called my theme ''mythemename'' so the function will be as follows: For this example I have called my theme ''mythemename'' so the function will be as follows:
<code php> <syntaxhighlight lang="php">defined('MOODLE_INTERNAL') || die();
  
defined('MOODLE_INTERNAL') || die(); 



function xmldb_theme_mythemename_install() { function xmldb_theme_mythemename_install() {
Line 83:
Line 81:
The install function can perform any upgrade routines you require. For the following example let's assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb. The install function can perform any upgrade routines you require. For the following example let's assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb.



<code php> <syntaxhighlight lang="php">defined('MOODLE_INTERNAL') || die();
  
defined('MOODLE_INTERNAL') || die(); 



function xmldb_theme_mythemename_install() { function xmldb_theme_mythemename_install() {



Leaco: added some necessary apostrophes, added a few commas, and corrected a variable name
2017-08-09T11:54:33Z
added some necessary apostrophes, added a few commas, and corrected a variable name

				
				
				
				
				
				← Older revision
				Revision as of 11:54, 9 August 2017
				
Line 31:
Line 31:
We are setting four properties here, version, component, requires, and maturity. The version property is required and the rest are optional however it is best practice to put them in as well. We are setting four properties here, version, component, requires, and maturity. The version property is required and the rest are optional however it is best practice to put them in as well.
===The version property=== ===The version property===
The version property is the version number of our theme and needs to be an integer, although you can set it to any integer value you want it is '''HIGHLY''' recommended to use the date format shown above as it is used everywhere else throughout Moodle. The version property is the version number of our theme and needs to be an integer, although you can set it to any integer value you want, it is '''HIGHLY''' recommended to use the date format shown above as it is used everywhere else throughout Moodle.



The format is YYYYMMDDXX : The format is YYYYMMDDXX :
Line 81:
Line 81:
This special function is called when a theme is first installed (if it has a version.php file and it has been newly added to your Moodle site) or the first time that the theme has a version.php file if you are developing or upgrading a theme. This special function is called when a theme is first installed (if it has a version.php file and it has been newly added to your Moodle site) or the first time that the theme has a version.php file if you are developing or upgrading a theme.



The install function can perform any upgrade routines you require. For the following example lets assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb. The install function can perform any upgrade routines you require. For the following example let's assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb.



<code php> <code php>
Line 135:
Line 135:
Upgrade code within this function should be written in a special style where each operation is written as a block and the theme version is upgraded incrementally after each operation. Upgrade code within this function should be written in a special style where each operation is written as a block and the theme version is upgraded incrementally after each operation.



For the following example lets assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb. For the following example let's assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb.



<code php> <code php>
Line 167:
Line 167:



Looking at this code it does the following things: Looking at this code it does the following things:
# It compares and the '''$oldversion''' to the version we set (2011032900) and our version is newer it runs the upgrade code. # It compares the '''$oldversion''' to the version we set (2011032900), and if our version is newer it runs the upgrade code.
# The upgrade code gets the current settings so that we can change them. # The upgrade code gets the current settings so that we can change them.
# It creates a new setting called settinga and we give it settingb's value. # It creates a new setting called settinga and we give it settingone's value.
# It deletes settingone as we no longer want it. # It deletes settingone as we no longer want it.
# It repeats the last two steps for settingb/settingtwo. # It repeats the last two steps for settingb/settingtwo.
Line 176:
Line 176:



==Done== ==Done==
Just like that we have added upgrade code to our theme that renames two settings. To do that we had to add a version.php file and a upgrade.php file. Just like that we have added upgrade code to our theme, that renames two settings. To do that we had to add a version.php file and a upgrade.php file.



Leaco: removed unnecessary apostrophes
2017-08-09T11:32:08Z
removed unnecessary apostrophes

				
				
				
				
				
				← Older revision
				Revision as of 11:32, 9 August 2017
				
Line 1:
Line 1:
{{Template:Themes}} {{Template:Themes}}
As theme's have got considerably more advanced in Moodle 2 there is now on occasion a need to write upgrade code for a theme. This quick tutorial looks at just how to do that. As themes have got considerably more advanced in Moodle 2 there is now on occasion a need to write upgrade code for a theme. This quick tutorial looks at just how to do that.



==Why?== ==Why?==
Line 10:
Line 10:
For those of you who are already familiar with writing Moodle plugins you will be familiar with the version.php, however for many themer's the reality is that they've never gone beyond adding a settings page so this will be new. For those of you who are already familiar with writing Moodle plugins you will be familiar with the version.php, however for many themer's the reality is that they've never gone beyond adding a settings page so this will be new.



The version.php file is a requirement for many plugin types, however for theme's it is optional. The idea is that it contains just two or three lines of code that tell Moodle what version the plugin is and a little bit about where it is meant to be, or what version of Moodle it requires. The version.php file for a theme should be created within the theme's base directory e.g. ''moodle/theme/mythemename/version.php''. The version.php file is a requirement for many plugin types, however for themes it is optional. The idea is that it contains just two or three lines of code that tell Moodle what version the plugin is and a little bit about where it is meant to be, or what version of Moodle it requires. The version.php file for a theme should be created within the theme's base directory e.g. ''moodle/theme/mythemename/version.php''.



The following is an example of what a version.php file for a theme looks like. The following is an example of what a version.php file for a theme looks like.





Damyon at 05:00, 1 December 2016
2016-12-01T05:00:44Z


				
				
				
				
				
				← Older revision
				Revision as of 05:00, 1 December 2016
				
Line 1:
Line 1:
{{Themes}} {{Template:Themes}}
As theme's have got considerably more advanced in Moodle 2 there is now on occasion a need to write upgrade code for a theme. This quick tutorial looks at just how to do that. As theme's have got considerably more advanced in Moodle 2 there is now on occasion a need to write upgrade code for a theme. This quick tutorial looks at just how to do that.






Damyon: /* Why? */
2016-12-01T04:56:28Z
Why?

				
				
				
				
				
				← Older revision
				Revision as of 04:56, 1 December 2016
				
Line 3:
Line 3:



==Why?== ==Why?==
As part of the Moodle 2 revamp theme's have been given the same abilities as many of the other plugin types within Moodle. They are now able to have settings pages, database tables, they can override renderers, and they can do all sorts of great things. Themes are able to have settings pages, database tables, they can override renderers, and they can do all sorts of great things.
  
Unfortunately this change has its positives and negatives, on the positive you can now really get some cool stuff happening within a theme, the downside is just like any other plugin you need to think about those who are already using your theme when you make changes. 



If you are changing the name of a setting, or if you are changing the database schema for the theme you will need to add upgrade code to your theme so that those who are already using your theme are moved along nicely and don't lose the effort they've put into customising and setting up your theme. If you are changing the name of a setting, or if you are changing the database schema for the theme you will need to add upgrade code to your theme so that those who are already using your theme are moved along nicely and don't lose the effort they've put into customising and setting up your theme.



Tsala: moved Themes 2.0 adding upgrade code to Adding theme upgrade code: simpler title
2013-04-22T14:18:06Z
moved Themes 2.0 adding upgrade code to Adding theme upgrade code: simpler title

				
				← Older revision
				Revision as of 14:18, 22 April 2013
				
(No difference)



Tsala: themes template
2013-04-22T14:17:48Z
themes template

				
				
				
				
				
				← Older revision
				Revision as of 14:17, 22 April 2013
				
Line 1:
Line 1:
{{Themes}}
As theme's have got considerably more advanced in Moodle 2 there is now on occasion a need to write upgrade code for a theme. This quick tutorial looks at just how to do that. As theme's have got considerably more advanced in Moodle 2 there is now on occasion a need to write upgrade code for a theme. This quick tutorial looks at just how to do that.



Line 178:
Line 179:
==Done== ==Done==
Just like that we have added upgrade code to our theme that renames two settings. To do that we had to add a version.php file and a upgrade.php file. Just like that we have added upgrade code to our theme that renames two settings. To do that we had to add a version.php file and a upgrade.php file.

==More information== 
* [[Themes 2.0]] 
* [[Themes 2.0 creating your first theme]] 
* [[Themes 2.0 adding a settings page]]

← Older revision		Revision as of 13:31, 14 July 2021
Line 14:		Line 14:
	The following is an example of what a version.php file for a theme looks like.		The following is an example of what a version.php file for a theme looks like.

	<~~code~~ php>		<syntaxhighlight lang="php">
	<?php		<?php

Line 115:		Line 115:

	The upgrade.php file should contain just a single function that needs to be named following a strict naming scheme. In the case of my theme that for this example I've called mythemename that function will be as follows:		The upgrade.php file should contain just a single function that needs to be named following a strict naming scheme. In the case of my theme that for this example I've called mythemename that function will be as follows:
	<~~code~~ php>		<syntaxhighlight lang="php">
	<?php		<?php

Line 133:		Line 133:
	For the following example let's assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb.		For the following example let's assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb.

	<~~code~~ php>		<syntaxhighlight lang="php">
	<?php		<?php

← Older revision		Revision as of 13:03, 14 July 2021
Line 68:		Line 68:

	For this example I have called my theme ''mythemename'' so the function will be as follows:		For this example I have called my theme ''mythemename'' so the function will be as follows:
	<~~code~~ php>		<syntaxhighlight lang="php">defined('MOODLE_INTERNAL') \|\| die();

	defined('MOODLE_INTERNAL') \|\| die();

	function xmldb_theme_mythemename_install() {		function xmldb_theme_mythemename_install() {
Line 83:		Line 81:
	The install function can perform any upgrade routines you require. For the following example let's assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb.		The install function can perform any upgrade routines you require. For the following example let's assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb.

	<~~code~~ php>		<syntaxhighlight lang="php">defined('MOODLE_INTERNAL') \|\| die();

	defined('MOODLE_INTERNAL') \|\| die();

	function xmldb_theme_mythemename_install() {		function xmldb_theme_mythemename_install() {

← Older revision		Revision as of 11:54, 9 August 2017
Line 31:		Line 31:
	We are setting four properties here, version, component, requires, and maturity. The version property is required and the rest are optional however it is best practice to put them in as well.		We are setting four properties here, version, component, requires, and maturity. The version property is required and the rest are optional however it is best practice to put them in as well.
	===The version property===		===The version property===
	The version property is the version number of our theme and needs to be an integer, although you can set it to any integer value you want it is '''HIGHLY''' recommended to use the date format shown above as it is used everywhere else throughout Moodle.		The version property is the version number of our theme and needs to be an integer, although you can set it to any integer value you want, it is '''HIGHLY''' recommended to use the date format shown above as it is used everywhere else throughout Moodle.

	The format is YYYYMMDDXX :		The format is YYYYMMDDXX :
Line 81:		Line 81:
	This special function is called when a theme is first installed (if it has a version.php file and it has been newly added to your Moodle site) or the first time that the theme has a version.php file if you are developing or upgrading a theme.		This special function is called when a theme is first installed (if it has a version.php file and it has been newly added to your Moodle site) or the first time that the theme has a version.php file if you are developing or upgrading a theme.

	The install function can perform any upgrade routines you require. For the following example ~~lets~~ assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb.		The install function can perform any upgrade routines you require. For the following example let's assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb.

	<code php>		<code php>
Line 135:		Line 135:
	Upgrade code within this function should be written in a special style where each operation is written as a block and the theme version is upgraded incrementally after each operation.		Upgrade code within this function should be written in a special style where each operation is written as a block and the theme version is upgraded incrementally after each operation.

	For the following example ~~lets~~ assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb.		For the following example let's assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb.

	<code php>		<code php>
Line 167:		Line 167:

	Looking at this code it does the following things:		Looking at this code it does the following things:
	# It compares ~~and~~ the '''$oldversion''' to the version we set (2011032900) and our version is newer it runs the upgrade code.		# It compares the '''$oldversion''' to the version we set (2011032900), and if our version is newer it runs the upgrade code.
	# The upgrade code gets the current settings so that we can change them.		# The upgrade code gets the current settings so that we can change them.
	# It creates a new setting called settinga and we give it ~~settingb~~'s value.		# It creates a new setting called settinga and we give it settingone's value.
	# It deletes settingone as we no longer want it.		# It deletes settingone as we no longer want it.
	# It repeats the last two steps for settingb/settingtwo.		# It repeats the last two steps for settingb/settingtwo.
Line 176:		Line 176:

	==Done==		==Done==
	Just like that we have added upgrade code to our theme that renames two settings. To do that we had to add a version.php file and a upgrade.php file.		Just like that we have added upgrade code to our theme, that renames two settings. To do that we had to add a version.php file and a upgrade.php file.

← Older revision		Revision as of 11:32, 9 August 2017
Line 1:		Line 1:
	{{Template:Themes}}		{{Template:Themes}}
	As ~~theme's~~ have got considerably more advanced in Moodle 2 there is now on occasion a need to write upgrade code for a theme. This quick tutorial looks at just how to do that.		As themes have got considerably more advanced in Moodle 2 there is now on occasion a need to write upgrade code for a theme. This quick tutorial looks at just how to do that.

	==Why?==		==Why?==
Line 10:		Line 10:
	For those of you who are already familiar with writing Moodle plugins you will be familiar with the version.php, however for many themer's the reality is that they've never gone beyond adding a settings page so this will be new.		For those of you who are already familiar with writing Moodle plugins you will be familiar with the version.php, however for many themer's the reality is that they've never gone beyond adding a settings page so this will be new.

	The version.php file is a requirement for many plugin types, however for ~~theme's~~ it is optional. The idea is that it contains just two or three lines of code that tell Moodle what version the plugin is and a little bit about where it is meant to be, or what version of Moodle it requires. The version.php file for a theme should be created within the theme's base directory e.g. ''moodle/theme/mythemename/version.php''.		The version.php file is a requirement for many plugin types, however for themes it is optional. The idea is that it contains just two or three lines of code that tell Moodle what version the plugin is and a little bit about where it is meant to be, or what version of Moodle it requires. The version.php file for a theme should be created within the theme's base directory e.g. ''moodle/theme/mythemename/version.php''.

	The following is an example of what a version.php file for a theme looks like.		The following is an example of what a version.php file for a theme looks like.

← Older revision		Revision as of 05:00, 1 December 2016
Line 1:		Line 1:
	{{Themes}}		{{Template:Themes}}
	As theme's have got considerably more advanced in Moodle 2 there is now on occasion a need to write upgrade code for a theme. This quick tutorial looks at just how to do that.		As theme's have got considerably more advanced in Moodle 2 there is now on occasion a need to write upgrade code for a theme. This quick tutorial looks at just how to do that.

← Older revision		Revision as of 04:56, 1 December 2016
Line 3:		Line 3:

	==Why?==		==Why?==
	~~As part of the Moodle 2 revamp theme's have been given the same abilities as many of the other plugin types within Moodle. They~~ are ~~now~~ able to have settings pages, database tables, they can override renderers, and they can do all sorts of great things.		Themes are able to have settings pages, database tables, they can override renderers, and they can do all sorts of great things.

	Unfortunately this change has its positives and negatives, on the positive you can now really get some cool stuff happening within a theme, the downside is just like any other plugin you need to think about those who are already using your theme when you make changes.

	If you are changing the name of a setting, or if you are changing the database schema for the theme you will need to add upgrade code to your theme so that those who are already using your theme are moved along nicely and don't lose the effort they've put into customising and setting up your theme.		If you are changing the name of a setting, or if you are changing the database schema for the theme you will need to add upgrade code to your theme so that those who are already using your theme are moved along nicely and don't lose the effort they've put into customising and setting up your theme.

← Older revision	Revision as of 14:18, 22 April 2013
(No difference)

Adding theme upgrade code - Revision history

Sarjona: This page will not be migrated to new devdocs

Mudrd8mz: Text replacement - "" to ""

Mudrd8mz: Text replacement - "" to ""

Mudrd8mz: Text replacement - " " to ""

Leaco: added some necessary apostrophes, added a few commas, and corrected a variable name

Leaco: removed unnecessary apostrophes

Damyon at 05:00, 1 December 2016

Damyon: /* Why? */

Tsala: moved Themes 2.0 adding upgrade code to Adding theme upgrade code: simpler title

Tsala: themes template

Mudrd8mz: Text replacement - "`" to ""`

`Mudrd8mz: Text replacement - "`" to ""

Mudrd8mz: Text replacement - "`" to ""`