Developer Documentation for jUpgrade

Version 1.0

Email: maguirre@matware.com.ar Website: http://www.matware.com.ar

Contributor: Isidro Baquero - Matias Aguirre

Date: 26/04/2011 License:GPL/GNU

Table of Contents
1. Introduction ................................................. ............................................... 3 1.1. History ................................................. ............................................... 3 2. Basics ................................................ ........................................................... 3 2.1. Introduction ........ .................................................. ............................ 3 2.2. File and Directory Structure ........................................................... .. 4 2.3. Migration process of 3rd party extensions ... .................................. 4 2.3. JUpgrade class .................................................................................... 6 3. XML's to update .......................................... .............................................. ..7 3.1. Introduction ....................................................................................7 3.1. XML Collection ................................................ ................................... 7 3.2. XML Extension ................................ ...................................................8 4. Building jUpgrade adapter .......................................................... .............. .8 4.1. Adapter structure ............................................................ ................. 8 4.2. Migration techniques ... .... .................................................. ............ 8 4.2. Access database ... .. ............................................................. ............ 8 5. Developer Guidelines ................................................................. ................ 9 5.3. SVN Access ............................................... ......................................... 9 5.4. Using SVN ...................................................... .................................... 9 6. About the Project ................................................... .................................... 9 6.1. Project ............................................................ ................................... 9 6.3. Home, Forums, Developer Resources .............................................. 9

Preamble Chapter 1. Introduction

1.1. History
This project all began when the Joomla! version 1.5 was released with a major shortcoming: a tool to help users migrate their data from Joomla! 1.0 to Joomla! 1.5. Although Sam Moffat worked on a tool like this, other tasks related to the development of Joomla! kept him very busy. At that point I decided to create mtwMigrator, which was widely accepted in the community at that time. With the development of Joomla! 1.6 running, I had the opportunity to help the project, using all the techniques learned to develop mtwMigrator. After a discussion with the developers I came to the conclusion that they would be too busy with Joomla! 1.6, and that the best way to help was to do something myself. Thus was born jUpgrade.

Chapter 2.Basics
2.1 Introduction
jUpgrade is a component for Joomla! 1.5. It should be installed as an extension through the extension manager. Once installed and configured on a Joomla! 1.5 site, it can be executed and, if everything works properly, it will perform the following tasks: Download the latest version of Joomla! 1.6 to your server (if you use the latest version of jUpgrade, this will be the latest version of Joomla! 1.6) Perform an automatic installation of Joomla! 1.6 Migrate all data from the old Joomla 1.5! site to the newly installed Joomla! 1.6 site

In principle, only the core data will be migrated 100%. For data from third-party extensions, jUpgrade provides the tools necessary to integrate migration schemes specific to each extension, which should be developed by the authors. At the time of writing this documentation, only Adminpraise and Kunena have created a plugin that allows you to migrate your data by jUpgrade.

2.2. File and Directory Structure

com_jupgrade | - controllers | - CSS | - extensions | - images | - include | `- adapters | - js | - languages | - Libraries | sql``views- cpanel `- tmpl

2.3. Migration process of 3rd party extensions

When run, jUpgrade checks if the extensions installed on your system (components, modules, plugins and templates) have specific support for them. For this, jUpgrade looks for an upgrade XML file in 3 different directories in the following order: 1. The first place jUpgrade looks is in the component/module/plugin directory. e.g. ROOT/administrator/components/com_kunena or if this is a module ROOT/ administrator/modules/mod_kunena 2. The second place jUpgrade looks is in the front-end directory: eg ROOT/components/ com_kunena or if this is a module ROOT/modules/mod_kunena 3. The third and last place jUpgrade looks is inside the jUpgrade extensions directory: ROOT/administrator/components/com_jupgrade/extensions

This XML file holds the data needed to easily migrate the tables and extension files. The structure of the XML file is as follows:
<? Xml version = "1.0"?> <! DOCTYPE jupgrade> <jupgrade> <! - List of update servers ->

<updateservers> <server type = "extension" priority = "1" name = "Kunena 1.6 Update Site "> http:// update.kunena.org/kunena16.xml </ server> </ updateservers> <! - Adapter class location and name -> <! <installer> <file> Administrator/components/com_kunena/install/j16upgrade.php </ file> <class> jUpgradeComponentKunena </ class> </ installer> - -> <! - The tables to copy to the new site. -> <tables> <table>kunena_announcement</table> <table>kunena_attachments</table> <table>kunena_categories</table> <table>kunena_config</table> <table>kunena_favorites</table> <table>kunena_groups</table> <table>kunena_messages</table> <table>kunena_messages_text</table> <table>kunena_moderation</table> <table>kunena_polls</table> <table>kunena_polls_options</table> <table>kunena_polls_users</table> <table>kunena_ranks</table> <table>kunena_sessions</table> <table>kunena_smileys</table> <table>kunena_subscriptions</table> <table>kunena_subscriptions_categories</table> <table>kunena_thankyou</table> <table>kunena_users</table> <table>kunena_users_banned</table> <table>kunena_version</table> <table>kunena_whoisonline</table> </table> <! - The folders to copy to the new site. -> <folders> <folder>media/kunena</folder> <folder>administrator/components/com_kunena</folder> <folder>components/com_kunena</folder> </ folders> <! - The categories to copy to the new site. -> <! <Categories> <category section="com_kunena"> </ category> </ categories> -> </ jupgrade>

In the XML file we can add the options needed to migrate the extension through jUpgrade. This can include items like database tables, directories for media files, the updated server url and the category if any.

2.4 The class jUpgrade

This class is used by the adapter for each extension that is added to jUpgrade. More information about this can be found in Chapter 4. In this class there are several methods that can help extension developers to migrate their own data. List of methods:
protected function convertParams ($ params) protected function convertParamsHook (& $ object) protected function & getSourceData ($ select = '*', $ join = null, $ where = null, $ order = null, $ groupby = null, $ debug = null ) protected function setDestinationData ($ rows = null) public function upgrade () protected function cleanDestinationData ($ table = false) protected function copyTable ($ from, $ to = null) protected function clonet ($ from, $ to = null, $ drop = true) public function InsertCategory ($ object, $ parent = false) public function insertAsset ($ object, $ parent = false) public function saveState () public function IsReady () public function upgradeExtension () protected function detectExtension () protected function getUpdateSite () protected function getCopyFolders () protected function getCopyTables () protected function migrateExtensionTables () protected function migrateExtensionFolders () protected function migrateExtensionCustom () protected function migrateExtensionDataHook () public function getPrefix () public function getMapList ($ table = 'categories', $ section = false) protected function getUsergroupIdMap () public function getparams () public function getRequirements () protected function checkTimeout ($ stop = false)

Chapter 3. XML's of update

3.1. Introduction
jUpgrade utilizes the installation/update extension system that is already included in Joomla! 1.6. This system is accessed by accessing the Joomla! Administrator Control Panel and navigating to Extensions > Extension Manager > Update. From here we can click on Find Updates to see which extensions can be installed/upgraded. Once we have that list ejegir an extension and click on Update to install / upgrade. The upgrade system that is included in Joomla! 1.6 requires two XML's to use. One is the Collection XML and the other is Update XML. These files should be in a URL accessible for all users using jUpgrade to migrate your Joomla! extensions.

3.2. XML Collection

This is the XML Collection file,which includes all extensions that can be read by jUpgrade. To add an extension to jUpgrade the following information should be added to this file tagged with 'extension' to the extension name and other attributes that are specified below: name = Name of the extension element = nameextension Joomla type =component / module / plugin version = 1.6 detailsurl = [IMPORTANT] This attribute must point to the xml extension
<extensionset name="Kunena" description="Kunena Extensions List"> <extension name="Kunena" element="com_kunena" type="component" version="1.6" detailsurl="http://www.matware.com.ar/extensions/kunena.xml"/> </extensionset>

If you want to add a module to the collection:

<extensionset name="Kunena" description="Kunena Extensions List"> <extension name="Kunena" element="com_kunena" type="component" version="1.6" detailsurl="http://www.matware.com.ar/extensions/kunena.xml"/> <extension name="Kunena Module" element="mod_kunena" type="module" version="1.6" detailsurl="http://www.matware.com.ar/extensions/mod_kunena.xml"/> </extensionset>

3.3. Update XML

We must update the XML details of our extension. The most important tag in this XML is the downloads that lets Joomla! 1.6 know which is the file to download and install / update.
<? Xml version = "1.0"?> <updates> <update> <! - Description -> <name> Kunena </ name> <description> Kunena for Joomla 1.6 </ description> <element> com_kunena </ element > <type> component </ type> <version> 1.6.3 </ version> <infourl title="Kunena"> http://www.kunena.org </ infourl> <! - The download url of the new package to Be installed -> <downloads> <downloadurl type="full" format="zip"> http://www.matware.com.ar/jfiles/com_kunena_v1.6.4 DEV_b4806_2011-04-26.zip </ downloadURL> </ downloads> <! - Tags -> <tags> <tag> testing </ tag> </ tags> <! - Maintainer description -> <maintainer> Matias Aguirre </ maintainer> <maintainerurl> http://www.matware.com.ar/ </ maintainerurl> <section> Testing </ section> <targetplatform name = " joomla "version =" 1.6 "/> </ update> </ updates>

Chapter 4. Building adapter jUpgrade

4.1. Adapter structure
Coming Soon...

4.2. Migration techniques

Coming Soon...

4.3. Access database

Coming Soon...

Chapter 5. Developer Guidelines

5.1. SVN Access
The jUpgrade source code is hosted onJoomlaCode. To navigate between the files you need to enter here:
http://joomlacode.org/gf/project/joomla/scmsvn/?action=browse&path =% 2Fdevelopment% 2Fbranches% 2F 2Fjupgrade%

5.2. Using SVN

To get a copy of jUpgrade using a SVN versioning system it is necessary to run the following command in the console (Linux):
svn co http://joomlacode.org/svn/joomla/development/branches/jupgrade

For other SVN clients use the same URL:

http://joomlacode.org/svn/joomla/development/branches/jupgrade

Chapter 6. About Project

6.1.Project
JUpgrade is a project for the Joomla! Community, property of Matware, a company created by Matias Aguirre, author of this project. jUpgrade has a GNU license.

6.2. Home, Forums, Developer Resources

http://matware.com.ar/forum/projects/jupgrade.html http://matware.com.ar/ http://matware.com.ar/joomla/jupgrade.html forum / projects / jupgrade / jupgrade-faq.html