Documentacin de jUpgrade para Desarrolladores

Version 1.0

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

Contribuidores: Isidro Baquero - Matias Aguirre

Fecha: 26/04/2011 Licencia: GPL/GNU

ndice de contenidos
1. Introducin ................................................................................................. 3 1.1. Historia .............................................................................................. 3 2. Conceptos Bsicos......................................................................................3 2.1. Introduccion........ .............................................................................. 3 2.2. Estructura de Archivos y Directorios ............................................... 4 2.3. Proceso de migracion de extensiones de 3ros ............................4 2.3. La clase jUpgrade .............................................................................. 6 3. XMLs de actualizacion ............................... ............................................... 7 3.1. Introduccion .................................................................................. 7 3.2. Collection XML ................................................................................. 7 3.3. XML de actualizacion ................................ ........................................8 4. Creando el adaptador de jUpgrade........................................................... 9 4.1. Estructura del Adaptador................................................................ 9 4.2. Tcnicas de Migracin .... .............................................................. 9 4.2. Acceso a base de datos .. .............................................................. 9 5. Directrices para desarrolladores............................................................... 10 5.3. Acceso al SVN ....................................... ......................................... 10 5.4. Usando el SVN .................................................................................. 10 6. Acerca del Proyecto ................................................................................... 10 6.1. El Proyecto ................................................ ................................... 10 6.3. Pgina principal, Foro, Recursos para Desarrolladores ................ 10

Prembulo Captulo 1. Introduccin

1.1. Historia
Todo comenz cuando la versin 1.5 de Joomla fue liberada con una importante carencia: una herramienta que ayudara a los usuarios a migrar sus datos desde la antigua versin 1.0 a la nueva. A pesar de que Sam Moffat trabajaba en una herramienta de este tipo, otras tareas internas relacionadas con el desarrollo de Joomla lo mantuvieron muy ocupado. En ese momento decid crear mtwMigrator, que tuvo una gran aceptacin en la comunidad en aquellos tiempos. Con el desarrollo de Joomla 1.6 en marcha tuve la oportunidad de ayudar al proyecto, usando todas las tcnicas aprendidas para desarrollar mtwMigrator. Tras una discusin con los desarrolladores llegu a la conclusin de que estaran demasiado ocupados con el desarrollo de Joomla 1.6, y que la mejor manera de ayudar era hacer algo yo mismo. As es como naci jUpgrade.

Captulo 2. Conceptos Bsicos

2.1 Introduccin
jUpgrade es un componente para Joomla 1.5. Debe ser instalado como una extensin ms a travs del gestor de extensiones. Una vez instalado y configurado en un sitio Joomla 1.5, podr ser ejecutado y, si todo funciona correctamente, deber realizar las siguientes tareas: Descargar en el servidor donde est instalado el sitio que lo ejecuta un paquete de instalacin de Joomla 1.6 (si se usa la ltima versin de jUpgrade, ser la versin ms reciente de Joomla 1.6) Realizar una instalacin automtica de Joomla 1.6 Migrar todos los datos del antiguo sitio basado en Joomla 1.5 al sitio Joomla 1.6 recin instalado En principio slo los datos del core sern migrados al 100%. Para los datos de extensiones de terceros, jUpgrade proporciona las herramientas necesarias para integrar mecanismos de migracin especficos para cada extensin, que debern ser desarrollados por sus autores. En el momento de escribir esta documentacin, nicamente Kunena y Adminpraise han creado

un plugin que permite migrar sus datos mediante jUpgrade.

2.2. Estructura de Archivos y Directorios

com_jupgrade |-- controllers |-- css |-- extensions |-- images |-- includes | `-- adapters |-- js |-- languages |-- libraries |-- sql `-- views `-- cpanel `-- tmpl

2.3. Proceso de migracion de extensiones de 3ros

Al ejecutar jUpgrade, la herramienta comprueba si las extensiones instaladas en el sistema (componentes, mdulos, plugins y plantillas) tienen soporte especfico para ellas. Para esto, jUpgrade busca el archivo XML necesario en 3 directorios distintos en el siguiente orden: 1. El primer lugar donde busca el XML es el directorio del componente en el administrador. ej: ROOT/administrator/components/com_kunena o si este es un modulo ROOT/administrator/modules/mod_kunena 2. El segundo lugar es el directorio del componente pero en el front-end: ej: ROOT/ components/com_kunena o si este es un modulo ROOT/modules/mod_kunena 3. Tercero y ultimo busca dentro del directorio extensions en jUpgrade: ROOT/ administrator/components/com_jupgrade/extensions En este XML pondremos los datos necesarios para migrar las tablas y archivos de nuestra extension facilmente. La estructura de este XML es la siguiente:
<?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> </tables> <!-- 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>

En este XML podremos agregar las opciones que necesita saber jUpgrade para migrar una extension como las tablas, los directorios de archivos multimedia, la url del servidore de actualizacion y las categorias si existiesen.

2.4 La clase jUpgrade

Esta clase es usada por el adaptador de cada extensin que haya sido aadida a jUpgrade. Ms informacin sobre esto en el Captulo 4. En esta clase existen varios mtodos que pueden ayudar a los desarrolladores de extensiones a migrar sus propios datos. Lista de mtodos:
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 cloneTable($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)

Captulo 3. XMLs de actualizacion

3.1. Introduccin
jUpgrade utiliza para la instalation/actualizacion de extensiones el sistema de actualizacion incluido en Joomla 1.6. Este sistema se accede ingresando al back-end de Joomla 1.6 y yendo al menu Extensions > Extension Manager > Update. Luego debemos clickear en Find Updates para ver cuales extensiones tenemos para instalar/actualizar. Una vez que tenemos esa lista podremos ejegir una extension y clickear en Update para instalarla/actualizarla. Este sistema de actualizacion incluido en Joomla 1.6 necesita dos XMLs para funcionar. Uno es el Collection XML y el XML de actualizacion. Estos archivos deben estar en una URL visible para el acceso de todos los usuarios que utilicen jUpgrade para migrar sus instalaciones de Joomla.

3.2. Collection XML

Este es el Collection XML, que incluye todas las extensiones que pueden ser ledas por jUpgrade. Para aadir una extensin a jUpgrade, debe aadirse a este archivo una etiqueta extension con el nombre de la extensin y otros atributos que se especifican a continuacin: name = Nombre de la extensin element =Nombre de la extensin en Joomla type = componente/mdulo/plugin version = 1.6 detailsurl = [IMPORTANTE] Este atributo debe apuntar al xml de la extensin
<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>

Si quiere aadir un mdulo a la coleccin:

<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. XML de actualizacion

En el XML de actualizacion debemos poner los detalles de nuestra extension. El tag mas importante en este XML es el de downloads que le permite saber a Joomla 1.6 cual es el archivo a descargar e instalar/actualizar.
<?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.4DEV_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>

Captulo 4. Creando el adaptador para jUpgrade

4.1. Estructura del Adaptador

En construccion

4.2. Tcnicas de Migracin

En construccion

4.3. Acceso a base de datos

En construccion

Captulo 5. Directrices para desarrolladores

5.1. Acceso al SVN
El codigo fuente de jUpgrade esta alojado en los servidores de JoomlCode. Para navegar entre los archivos es necesario ingresar aqui:
http://joomlacode.org/gf/project/joomla/scmsvn/? action=browse&path=%2Fdevelopment%2Fbranches%2Fjupgrade%2F

5.2. Usando el SVN

Para obtener una copia de jUpgrade utilizando el sistema de versiones SVN es necesario ejecutar el siguiente comando en la consola (Linux):
svn co http://joomlacode.org/svn/joomla/development/branches/jupgrade

Para otros clientes de SVN utilizar la misma URL:

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

Chapter 6. Acerca del Proyecto

6.1. El Proyecto
jUpgrade es un proyecto destinado a la comunidad Joomla propiedad de Matware, empresa creada por Matias Aguirre author del proyecto. Este proyecto tiene una licencia GNU.

6.2. Pgina principal, Foro, Recursos para Desarrolladores

http://matware.com.ar/joomla/jupgrade.html http://matware.com.ar/forum/projects/jupgrade.html http://matware.com.ar/forum/projects/jupgrade/jupgrade-f-a-q.html