Archived

Difference between revisions of "Managing Component Updates (Manifest file)"

From Joomla! Documentation

(11 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{review}}
+
{{version/tutor|2.5}}{{Chunk:Managing Component Updates - Contents}}{{review}}
{{RightTOC}}
 
This tutorial is for Joomla {{JVer|1.6}} {{JVer|1.7}}
 
== Articles in this series ==
 
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_1|Overview]]
 
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_2|Manifest file]]
 
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_3|Script.php]]
 
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_4|Update SQL files]]
 
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_5|Component release files]]
 
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_6|How to use this example]]
 
  
 
== Manifest File (democompupdate.xml) ==
 
== Manifest File (democompupdate.xml) ==
Line 34: Line 25:
 
Joomla stores this value in the ''manifest_cache'' field of the ''extensions'' table.  The ''extensions'' table is where the custom code in the ''script.php'' file reads the version string of the currently installed component, and compares it to the version string of the update.
 
Joomla stores this value in the ''manifest_cache'' field of the ''extensions'' table.  The ''extensions'' table is where the custom code in the ''script.php'' file reads the version string of the currently installed component, and compares it to the version string of the update.
  
The custom component code uses this comparison to abort an update, if the version sequence is not allowed.  Joomla also compares this string to the SQL update file names, to determine which SQL commands to execute.
+
The custom component code uses this comparison to abort an update if the version sequence is not allowed.  Joomla also compares this string to the SQL update file names, to determine which SQL commands to execute.
  
 
<source lang="xml">
 
<source lang="xml">
 
<version>1.0</version>
 
<version>1.0</version>
 
</source>
 
</source>
 +
 +
=== Joomla version ===
 +
The component developer records in the manifest file the version of Joomla that is required to run the component.
 +
<source lang="xml">
 +
<extension type="component" version="1.6" method="new">
 +
</source>
 +
 +
Your component installation script.php file can use this value to control whether a component installation or update should be allowed or not allowed.
  
 
=== schemapath ===
 
=== schemapath ===
Line 54: Line 53:
 
=== #__schemas table ===
 
=== #__schemas table ===
 
The SQL files have a second function.
 
The SQL files have a second function.
In addition to potentially modifying the MySQL database, Joomla uses the names of these SQL files to key updates to the ''version_id'' field in the ''#__schemas'' table for your component.
+
In addition to potentially modifying the MySQL database, Joomla uses the names of these SQL files to enable updates to the ''version_id'' field in the ''#__schemas'' table for your component.
 
It is important to have an SQL file for EVERY version of your component.
 
It is important to have an SQL file for EVERY version of your component.
 
The file should be empty if you have no SQL code to execute when updating to that version.
 
The file should be empty if you have no SQL code to execute when updating to that version.
Line 64: Line 63:
  
 
If your new component version is not executing the SQL file as expected, check the ''#__schemas'' table to see if the previous version was correctly recorded.
 
If your new component version is not executing the SQL file as expected, check the ''#__schemas'' table to see if the previous version was correctly recorded.
If it is not, then your update will not execute the SQL file.
+
If it is not, then your update will not execute the SQL file when updating from that version to a newer version.
  
 
== The entire manifest file ==
 
== The entire manifest file ==
Here is the entire manifest file for version 1.0.
+
Here is the entire manifest file for democompupdate version 1.0.
  
 
<source lang="xml">
 
<source lang="xml">
Line 113: Line 112:
 
*[[User:sm990|Kim Eckert]]
 
*[[User:sm990|Kim Eckert]]
  
[[category:Joomla! 1.6]]
+
[[Category:Joomla! 1.6]]
[[category:Joomla! 1.7]]
+
[[Category:Joomla! 1.7]]
[[Category:Tutorials]]
+
[[Category:Joomla! 2.5]]
 
[[Category:Component Development]]
 
[[Category:Component Development]]

Revision as of 07:03, 24 May 2013

This page has been archived. This page contains information for an unsupported Joomla! version or is no longer relevant. It exists only as a historical reference, it will not be improved and its content may be incomplete and/or contain broken links.

<sidebar>

  • Managing Component Updates
    • J2.5:Managing Component Updates|Overview
    • J2.5:Managing Component Updates (Manifest file)|Manifest file
    • J2.5:Managing Component Updates (Script.php)|Script.php
    • J2.5:Managing Component Updates (Update SQL files)|Update SQL files
    • J2.5:Managing Component Updates (Component release files)|Component release files
    • J2.5:Managing Component Updates (How to use this example)|How to use this example
  • Help
    • JDOC:How to Contribute to Joomla! Documentation|Contribute to Joomla! Docs
    • JDOC:Documentation_Translators|Translate Joomla! Docs
    • Help:Cheatsheet|Editing Help
    • Sandbox|Play in the Sandbox
    • JDOC:Wiki_policy|JDOC's Policies
    • JEDL|Documentation License
    • helppage|More Help

</sidebar>

Copyedit.png
This Page Needs Your Help

This page is tagged because it NEEDS REVIEW. You can help the Joomla! Documentation Wiki by contributing to it.
More pages that need help similar to this one are here. NOTE-If you feel the need is satistified, please remove this notice.


Manifest File (democompupdate.xml)[edit]

The manifest file in this example is very similar to that of normal components. Important contents for this example include:

sql folder[edit]

Note the inclusion of the SQL folder in the administration files section. This tells Joomla to copy the contents of this folder to the web site during install or update. The schemapath declaration below depends on Joomla copying these files during the install or update process.

<administration>
	<files folder="admin"> 
		<folder>sql</folder> 
	</files>
</administration>

name[edit]

This is the name of the component. The 'getParam($key)' method in the script.php file uses this value to identify the correct row in the extensions table. The manifest_cache field in the extensions table has the version string for the currently installed component.

<name>COM_DEMOCOMPUPDATE</name>

version[edit]

Joomla stores this value in the manifest_cache field of the extensions table. The extensions table is where the custom code in the script.php file reads the version string of the currently installed component, and compares it to the version string of the update.

The custom component code uses this comparison to abort an update if the version sequence is not allowed. Joomla also compares this string to the SQL update file names, to determine which SQL commands to execute.

<version>1.0</version>

Joomla version[edit]

The component developer records in the manifest file the version of Joomla that is required to run the component.

<extension type="component" version="1.6" method="new">

Your component installation script.php file can use this value to control whether a component installation or update should be allowed or not allowed.

schemapath[edit]

This defines the directory that contains SQL files for component incremental database updates. You may choose to put the SQL files somewhere else in your component release, but make sure their location is documented here.

<update> 
	<schemas> 
		<schemapath type="mysql">sql/updates</schemapath> 
	</schemas> 
</update>

#__schemas table[edit]

The SQL files have a second function. In addition to potentially modifying the MySQL database, Joomla uses the names of these SQL files to enable updates to the version_id field in the #__schemas table for your component. It is important to have an SQL file for EVERY version of your component. The file should be empty if you have no SQL code to execute when updating to that version. You must have a file or the version_id will not get updated correctly. Joomla uses the version_id in the #__schemas table as the from version when calculating updates from an older version to a new version.

It is important to include these schemapath lines in your manifest file, even if you have no SQL commands to execute. By including these lines and including empty SQL files, the version_id value will be correctly maintained in the #__schemas table.

If your new component version is not executing the SQL file as expected, check the #__schemas table to see if the previous version was correctly recorded. If it is not, then your update will not execute the SQL file when updating from that version to a newer version.

The entire manifest file[edit]

Here is the entire manifest file for democompupdate version 1.0.

<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="1.6" method="new">
	<name>COM_DEMOCOMPUPDATE</name>
	<creationDate>2011 05 11</creationDate>
	<author>Your Name Here</author>
	<copyright>Free to copy</copyright>
	<license>none</license>
	<version>1.0</version>
	<description>Test the Install and Update Process</description>
	<!-- Runs on install/uninstall/update; New in 1.6 -->
	<scriptfile>script.php</scriptfile>
	<install>
		<sql>
			<file driver="mysql" charset="utf8">sql/install_data.sql</file>
		</sql>
	</install>
	<uninstall>
		<sql>
			<file driver="mysql" charset="utf8">sql/uninstall.sql</file>
		</sql>
	</uninstall>
	<update>
		<schemas>
			<schemapath type="mysql">sql/updates</schemapath>
		</schemas>
	</update>
	<files folder="site">
		<filename>democompupdate.php</filename>
		<filename>controller.php</filename>
		<folder>models</folder>
		<folder>views</folder>
	</files>
	<administration>
		<files folder="admin">
			<folder>sql</folder>
		</files>
	</administration>
</extension>

Contributors[edit]