MANUAL

DESARROLLAR COMPONENTE

EN JOOMLA

Versión 1.0 Jesús García Pérez

Desarrollar componente en Joomla

Jesús García Pérez

Contenido 1

REQUISITOS. .................................................................................................................................. 4

2

INTRODUCCIÓN. ............................................................................................................................ 4

3

MODELO-VISTA-CONTROLADOR. .................................................................................................. 4 3.1

Introducción .......................................................................................................................... 5

3.2

Estableciendo el controlador ................................................................................................ 7

3.3

Ajustando la vista .................................................................................................................. 8

4

Añadir un tipo de elemento de menú ......................................................................................... 10

5

Añadiendo un modelo ................................................................................................................. 10

6

Añadir una petición de variable en el tipo de menu ................................................................... 12

7

Usar la base de datos .................................................................................................................. 13 7.1

Añadir un nuevo tipo de campo .......................................................................................... 13

7.2

Mostrar el mensaje elegido................................................................................................. 16

8

Lado de administrador básico ..................................................................................................... 18 8.1

Crear el controlador general ............................................................................................... 19

8.2

Crear la vista ........................................................................................................................ 20

8.3

Crear el modelo ................................................................................................................... 24

9

Traducciones ............................................................................................................................... 25 9.1

Introducción ........................................................................................................................ 25

9.2

Añadir una traducción al lado público ................................................................................ 26

9.3

Añadir una traducción a la gestión del componente .......................................................... 26

9.4

Opciones para la localización de los ficheros de idiomas ................................................... 26

9.5

Añadir traducciones a la instalación del componente ........................................................ 27

10

Añadir una barra de herramientas .......................................................................................... 27

10.1

Añadir controladores específicos ........................................................................................ 30

10.2

Añadir una vista de edición ................................................................................................. 32

10.3

Añadir un modelo y modificar el existente ......................................................................... 33

11

Añadir adornos en el back-end ............................................................................................... 35

11.1

Añadir algunos iconos ......................................................................................................... 36

11.2

Modificar las vistas .............................................................................................................. 36

11.3

Modificar el archivo principal de entrada ........................................................................... 39

11.4

Añadir algunas cadenas de palabras en el archivo de idioma ............................................ 40

12

Añadir verificaciones de formulario ........................................................................................ 40

2

Desarrollar componente en Joomla

Jesús García Pérez

12.1

Verificar el formulario (lado del cliente) ............................................................................. 40

12.2

Verificar el formulario (lado del servidor) ........................................................................... 47

13

Añadir categorías .................................................................................................................... 48

13.1

Introducción ........................................................................................................................ 48

13.2

Modificar el SQL .................................................................................................................. 48

13.3

Modificar el formulario ....................................................................................................... 48

13.4

Modificar el tipo de menú ................................................................................................... 49

13.5

Gestionar el submenú ......................................................................................................... 50

13.6

Añadir algunas cadenas de traducciones ............................................................................ 53

14

Añadir parámetros de configuración ...................................................................................... 53

14.1

Usar la configuración de parámetros como valor por defecto ........................................... 54

14.2

Modificar el SQL .................................................................................................................. 55

14.3

Modificar el lado del administrador .................................................................................... 58

14.4

Modificar el lado público..................................................................................................... 59

14.5

Añadir algunas cadenas de traducción ............................................................................... 62

15

Describiendo el ACL (Lista de control de Acceso) ................................................................... 63

15.1

Restringir el acceso al componente .................................................................................... 63

15.2

Mostrar solamente los botones correctos de la barra de herramientas ............................ 64

15.3

Añadir ajustes de permisos en las preferencias del componente ...................................... 66

15.4

Ajustar el valor en la tabla de recursos ............................................................................... 67

16

Añadir un script para instalar/desinstalar/actualizar.............................................................. 70

16.1

Crear el archivo de script de la extensión ........................................................................... 70

16.2

Añadir algunas claves de idioma ......................................................................................... 72

17

Añadir un servidor para actualizaciones ................................................................................. 73

18

Bibliografía .............................................................................................................................. 75

3

Desarrollar componente en Joomla

Jesús García Pérez

1 REQUISITOS. Necesita Joomla 1.6 o una versión posterior para seguir este tutorial.

2 INTRODUCCIÓN. Este manual pretende mostrar algunas nociones básicas sobre creación de componentes en Joomla. Ha sido desarrollado siguiendo la bibliografía, por tanto, el contenido más extensamente se puede encontrar en ella. Joomla 1.6 se construye usando 3 aplicaciones (o partes) diferentes: - Instalación (installation). Para instalar Joomla. Se usa solamente una vez en la primera instalación. - Administrador (administrator). Se encuentra en el directorio administrator/components. Se usa para gestionar el contenido. - Pública. Se encuentra en el directorio components y se usa para mostrar el contenido al público de la web. Estas 2 últimas partes se llaman com_componentname/componentname.php y van situadas cada una en su directorio o carpeta. El prefijo com_ es un vestigio histórico de Joomla. La dirección para comprobar el componente en la parte del sitio es: http://localhost/joomla/index.php?option=com_grtic Y desde la parte de administración http://localhost/joomla/administrator/index.php?option=com_grtic El archivo grtic.xml contendrá información del componente y la descripción de los archivos que forman el portal.

3 MODELO-VISTA-CONTROLADOR.

4

Desarrollar componente en Joomla

Jesús García Pérez

Input --> Processing --> Output Controller --> Model --> View

En el Framework (marco de trabajo) de Joomla 1.6, los componentes de terceros dividen su código en tres partes principales: - modelos.Datos. Gestionan los datos (SGBD). - controladores.Lógica de negocio. Realizan tareas, establecen y obtienen el estado de los modelos y solicitan las visualizaciones a las vistas. Responde a eventos del usuario, invoca peticiones al modelo y a la vista. - vistas.Interfaz de usuario. Muestran el contenido de acuerdo con el tipo (error, feed, html, json, raw, xml) y la presentación elegida por el controlador

3.1 Introducción

5

Desarrollar componente en Joomla

Jesús García Pérez

grtic.php Este va a ser el punto de entrada de nuestro componente. controller.php Este archivo contiene nuestro controlador base. views/grtic/view.html.php Este archivo recupera los datos necesarios y coloca sobre la plantilla. views/grtic/tmpl/default.php Esta es la plantilla donde nuestro proyecto. grtic.xml Este fichero XML que le dice a Joomla cómo instalar nuestro documento.

Joomla sabe qué componente tiene que cargar porque busca en la cadena de consulta de la petición el parámetro option, del cual obtiene el nombre del componente a cargar. Es decir, nosotros para llamar a nuestro componente Grtic, introduciremos en joomla la URL acabada con index.php?option=com_grtic. Esto muestra la página principal de nuestro componente, que por defecto carga la vista con el mismo nombre del componente, es decir, la vista con nombre Grtic. Resumiendo en cuanto el nombre del archivo para el punto de entrada debe de ser el mismo que el del componente. En nuestro caso como nuestro componente se llama Grtic durante la instalación Joomla creará una carpeta llamada com_grtic y el punto de entrada debe denominarse como grtic.php.

6

Desarrollar componente en Joomla

Jesús García Pérez

Cuando se carga el componente, se ejecuta el punto de entrada a este, .com_grtic/grtic.php; en este archivo tienen lugar varios procesos:  

Crearemos una instancia de nuestro componente, en nuestro caso los llamamos botanic, por lo tanto la clase intanciada será grticController como veremos en el siguiente apartado. Una vez instanciada ejecutaremos la tarea (task) solicitada.

En los siguientes apartados describiremos de forma más detallada cada uno de los archivos básicos que compondrán nuestro componente.

3.2 Estableciendo el controlador site/grtic.php (punto de acceso del componente grtic) Crea el objeto controlador llamado grticControllercon el método estático getInstance de la clase JControllerusando el archivo controller.php

Según la introducción del modelo MVC (Model-View-Controller) el controlador es el responsable de responder a las acciones del usuario, en concreto en una aplicación web, a la acción de un usuario (generalmente) se responde con una página web. Digamos que el controlador es gestor de la aplicación, se mantiene a la escucha de todas las peticiones, ejecuta la lógica de la aplicación, y muestra la vista apropiada para cada caso. Como hemos visto anteriormente es en el punto de entrada donde se creará una instancia del controlador añadiéndole el prefijo de grtic:$controller = JController::getInstance(grtic);. site/controller.php Es el controlador que extiende JController. Por defecto presenta la vista llamada grtic.Este controlador mostrará la vista grtic por defecto como veremos a continuación en el siguiente apartado.

7

Desarrollar componente en Joomla

Jesús García Pérez

3.3 Ajustando la vista Cuando JControllerdesea mostrar una vista, buscará determinados ficheros en el directorio component/com_[component_name]/views/[name of view]/. El nombre de la carpeta de la vista por defecto es el nombre del componente. En nuestro caso la ruta es component/com_grtic/views/grtic/. El archivo que contendrá el código de la vista se llama view.[view_mode].php. El modo de vista por defecto, y probablemente el único modo de vista por defecto que puede necesitar es html. Así que nosotros damos el nombre a la vista view.html.php. site/views/grtic/view.html.php Mostrará datos de la vista por defecto, del archivo tmpl/default.php. El mensaje por defecto está contenido en la variable $this->msg.

8

Desarrollar componente en Joomla

Jesús García Pérez

El método display de la clase Jview es llamado con la tarea display de la clase JController. En nuestro caso, este método mostrará datos usando el archivo tmpl/default.php. site/views/grtic/tmpl/default.php La vista por defecto. Aquí es donde adornamos la información.

Este archivo de plantilla se incluirá en la clase JView. Por lo tanto, aquí $this hace referencia a la clase grticViewgrtic Resultado: se ve por defecto el mensaje contenido en la variable $this->msgdel archivo view.html.php. 9

Desarrollar componente en Joomla

Jesús García Pérez

4 Añadir un tipo de elemento de menú En el marco de trabajo de Joomla 1.6, los componentes se ejecutan usando elementos de menú (menuitems). Si vas al gestor de menús de tu instalación de Joomla, este elemento del menú no existe. Añadir esta funcionalidad es fácil en Joomla. Simplemente con el archivo site/views/grtic/tmpl/default.xml.

Por el momento la cadena no se traducirá en el lado del administrador. Veremos en otro artículo posterior como se llevan a cabo las traducciones. Archivo con el código: com_grtic1.zip

5 Añadiendo un modelo En el marco de trabajo de Joomla 1.6, los modelos son los responsables de gestionar los datos. site/models/grtic.php contiene la clase grticModelgrtic que es el modelo principal, extiende a JModelItem.

10

Desarrollar componente en Joomla

Jesús García Pérez

La primera función que se tiene que escribir para un modelo es la función get. Esta devuelve los datos a quien los llama (return $this->msg;). En nuestro caso, los llamará la vista grticViewgrtic. Por defecto, el modelo llamado grticModelgrtic es el modelo principal asociado a esta vista. Ahora la clase grticViewgrtic le pide al modelo los datos usando la función get de la clase JView. También se ha añadido una comprobación de errores. site/views/grtic/view.html.php Contiene la clase grticViewgrtic que extiende a JView.

11

Desarrollar componente en Joomla

Jesús García Pérez

6 Añadir una petición de variable en el tipo de menu Por el momento, el mensaje mostrado siempre es Gestión de recursos TIC.Joomla2.5 da la posibilidad de añadir parametros a los tipos de menu. En nuestro caso, esto se hace en el archivo site/views/grtic/tmpl/default.xml.

site/models/grtic.phpEl modelo tiene que ser modificado para poder elegir entre los dos mensajes diferentes (que son elegidos por el usuario con el campo definido abajo):

12

Desarrollar componente en Joomla

Jesús García Pérez

7 Usar la base de datos Los componentes suelen gestionar sus datos usando la base de datos. Durante la fase de Instalación/Desinstalación/Actualización de un componente, usted puede ejecutar peticiones SQL a través del uso de archivos de texto SQL. admin/sql/install.mysql.utf8.sql y admin/sql/updates/mysql/0.0.6.sql archivos de instalación. Crean la tabla del componente (se llama grtic)e inserta valores en la tabla. La tabla contiene los campos id (campo que se autoincremente) y titulo(contiene los valores detítulos). DROP TABLE IF EXISTS `#__grtic`; CREATE TABLE `#__grtic` ( `id` int(11) NOT NULL AUTO_INCREMENT, `titulo` varchar(25) NOT NULL, PRIMARY KEY (`id`) ) ENGINE=MyISAM AUTO_INCREMENT=0 DEFAULT CHARSET=utf8; INSERT INTO `#__grtic` (`titulo`) VALUES ('Gestión de recursos TIC'), ('Recursos TIC'), ('Escuela TIC 2.0');

De igual forma tenemos el archivo de desinstalación. admin/sql/uninstall.mysql.utf8.sqlarchivo de desinstalación. Elimina la tabla del componente. DROPTABLEIFEXISTS`#__gritic`;

7.1 Añadir un nuevo tipo de campo Por el momento, hemos usado código duro (hard-code) para los tipos de campos de los mensajes. 13

Desarrollar componente en Joomla

Jesús García Pérez

Hard-code, término del mundo de la informática, hace referencia a una mala práctica en el desarrollo de software que consiste en incrustar datos directamente en el código fuente del programa, en lugar de obtener esos datos de una fuente externa como un fichero de configuración o parámetros de la línea de comandos, o un archivo de recursos.Considerada como un antipatrón de diseño, se trata de una práctica por abandonar, ya que requiere la modificación del código fuente cada vez que cambian los datos, cuando lo conveniente sería que el usuario final pudiera cambiar estos detalles fuera del código fuente del programa. Necesitamos usar nuestra base de datos para elegir el mensaje. site/views/grtic/tmpl/default.xml se modifica para indicarar la ruta donde está el nuevo tipo de dato. Se modifica el tipo de datos que ahora en vez de type=list va a ser type=grtic. Esto introduce un nuevo tipo de campo y le dice a Joomla que busque la definición del campo en la carpeta /administrator/components/com_grtic/models/fields

admin/models/fields/grtic.php Obtiene de la base de datos los valores de los campos id y titulo.Contiene la clase JFormFieldgrticque extiende a JFormFieldList.

14

Desarrollar componente en Joomla

Jesús García Pérez

El nuevo tipo de campo muestra una lista desplegable de mensajes de la cual elegir. Puedes ver el resultado de este cambio en el gestor de menús. Hay que mirar en los tipos de elementos grtic. 15

Desarrollar componente en Joomla

Jesús García Pérez

7.2 Mostrar el mensaje elegido Cuando un elemento de menú de este componente se Crea/Actualiza, Joomla almacena el identificador del mensaje. El modelo grticModelgrtic tiene ahora que computar el mensaje de acuerdo con este identificador y los datos almacenados en la base de datos. site/models/grtic.phpContiene el modelo grticModelgrtic

16

Desarrollar componente en Joomla

Jesús García Pérez

El modelo ahora le pide a la clase tabla Tablegrtic que le proporcione el mensaje. Esta clase de tabla tiene que ser definida en el archivo admin/tables/grtic.php. Admin/tables/grtic.phpcontiene la clase grticTablegrtic que extiende JTable.

17

Desarrollar componente en Joomla

Jesús García Pérez

No debería notar ninguna diferencia, pero si accede a la base de datos debería ver una tabla llamada jos_grtic con dos columnas: id y titulo. Archivo con el código: grtic2.zip

8 Lado de administrador básico Diseñar una interfaz básica del lado del administrador nos lleva a crear, al menos, un tríptico Modelo-Vista-Controlador. Tenemos que modificar el punto de entrada a la administración de nuestro componente, el archivo admin/grtic.php admin/grtic.phppunto de entrada a la administración de nuestro componente

18

Desarrollar componente en Joomla

Jesús García Pérez

8.1 Crear el controlador general El punto de entrada tiene ahora una instancia de un controlador prefijado grtic. Vamos a crear un controlador básico para el lado del administrador: admin/controller.php Controlador básico de la parte de administración. Este controlador mostrará la vista grtic por defecto. Clase grticController que extiende JController.

19

Desarrollar componente en Joomla

Jesús García Pérez

8.2 Crear la vista admin/views/grtics/view.html.php la vista básica del componente en la parte de administración. Clase grticViewgrtics que extiende JView.

20

Desarrollar componente en Joomla

Jesús García Pérez

Las vistas se muestran usando layouts o plantillas (templates), que se encuentran en el directorio tmpl. La vista por defecto: admin/views/grtics/tmpl/default.php admin/views/grtics/tmpl/default.php donde realmente está el código HTML que muestra la vista. En nuestro caso la tabla donde se muestra el contenido de los elementos de la base de datos (los títulos).

21

Desarrollar componente en Joomla

Jesús García Pérez

En Joomla, las vistas muestran datos usando posiciones.Esta posición llama a varias subposiciones (head, foot y body). Cada subposición corresponde a un archivo prefijado con el nombre de la posición principal (default), y un guión bajo. admin/views/grtics/tmpl/default_head.phpcontiene la cabecera de la plantilla (de la tabla).

-

checkAll es una función javascript definida en el núcleo de Joomla que marcará todos los checkboxes con un sólo click.

admin/views/grtics/tmpl/default_body.php Contiene el cuerpo de la plantilla (de la tabla), donde se muestran los elementos del listado.

22

Desarrollar componente en Joomla

Jesús García Pérez

- JHtml::_ es una función de ayuda (helper) que mostrará el HTML. En este caso mostrará una casilla de verificación para cada elemento. admin/views/grtics/tmpl/default_foot.php El pie de la plantilla (de la tabla), que muestra la paginación.

-

JPagination es una clase de Joomla capaz de gestionar y mostrar objetos de paginación. Sirve para generar el objeto paginador con el que podremos navegar por las diferentes páginas del listado.

23

Desarrollar componente en Joomla

Jesús García Pérez

8.3 Crear el modelo Como hemos visto en la clase anterior, la vista hace una llamada al modelo para recoger los datos. La vista grtics le pide al modelo los datos. En Joomla, existe una clase capaz de gestionar una lista de datos: JModelList. La clase JModelList y sus clases herederas necesitan solamente un método: * getListQuery que construye una petición SQL. y dos mandatos: *list.startpara determinar el desplazamiento de la lista. *list.limit para determinar la longitud de la lista. Los métodos getItems y getPagination se definen en la clase JModelList. Estos métodos no necesitan ser definidos en la clase grticModelgrtic.

Grtic almacena su contenido en la base de datos, por tanto es ahí de donde obtendremos la información que mostraremos en la vista. En Joomla hay una clase para gestionar la información de la base de datos: JModelList. Esta clase tiene un metodo llamado getListQuery, que nos devolvera un listado de objetos, es decir, un listado con la información que en la vista hemos pedido. Además tiene varios estados:  

list.start: para determinar el desplazamiento de la lista. list.limit: para determinar la medida de la lista, es decir, el número de elementos de la lista.

Los métodos getItems y getPagination están definidos en la clase JModelList. admin/models/grtics.php El modelo en la parte de administración que construye la sentencia SQL de acceso al listado de datos. Clase grticModelgrtics que extiende JModelList.

24

Desarrollar componente en Joomla

-

Jesús García Pérez

El método _populateState, por defecto, se llama automáticamente cuando se lee el mandato por el método getState.

Ahora puede ver en su componente grticuna tabla con dos columnas, dos filas y cajas de verificación. Puedes hacer click en las cajas de verificación con el fin de seleccionar las diferentes opciones que quiera.

9 Traducciones 9.1 Introducción Joomla gestiona los idiomas para componentes en 4 situaciones diferentes: -

Mostrando un componente en el lado público. Gestionando un componente en el lado del administrador. Gestionando los menús en el lado del administrador. Instalando un componente (nuevo en 1.6). 25

Desarrollar componente en Joomla

Jesús García Pérez

Joomla usa 2 carpetas diferentes para los idiomas: -

Una en administrator/language o language. Otra en la carpeta del componente (administrator/component/*component*/languageocomponent/*component*/language)

Depende de como se haya instalado el componente.

9.2 Añadir una traducción al lado público site/language/en-GB/en-GB.com_grtic.iniEste archivo contendrá la traducción para el lado público. Por el momento este archivo está vacío, no hay cadenas de traducción en este archivo.

9.3 Añadir una traducción a la gestión del componente admin/language/en-GB/en-GB.com_grtic.ini.Este fichero tendrá el idioma con el que se administra el componente.Este archivo contiene la traducción para el lado del administrador. Contiene las palabras y su traducción.Añadir traducciones a la gestión de menús del lado del administrador admin/language/en-GB/en-GB.com_grtic.sys.iniEn este fichero tenemos las traducciones que gestionan los menús en el backend.Este archivo contendrá la traducción para el lado del administrador en los menús. admin/language/en-GB/en-GB.iniPor último añadimos las traducciones que nos sirve para la instalación del componente.

9.4 Opciones para la localización de los ficheros de idiomas A partir dela versión 1.7hay 2maneras de instalarlos archivos de idiomaparauna extensión. Se puedeutilizarunau otraounacombinación de ambos. En la versión1.5se instalará los archivosen las carpetas deidioma del núcleo (ROOT/administrator/language/ and ROOT/language/). La forma-desde el nuevo 1.6-incluye los archivos enuna carpeta de "language"instaladaen la raíz dela extensión. Por lo tanto, una extensiónpuede incluir unacarpeta de idiomacon un.sys.ini. diferente ala instaladaen las carpetas de idiomas del núcleojoomla(este último no estáincluido en esacarpeta de idioma, pero en la raízo cualquier otra carpetaque noestá instalado).Esto permite mostrar 2 descripcionesdiferentes: la sys.inien la carpeta "lenguaje" que se utiliza como mensaje que aparece cuandola instalaciónse ha hecho, y el otro (del .ini) se utiliza para funcionamiento "normal", por ejemplo, cuando la extensiónse edita en elback-end. Esto puede ser extremadamenteútil cuando intalando también usa algunos scriptsy requiereun valor diferente parala descripción. Nota: El archivosys.initambién se utiliza paratraducir el nombrede las extensionesen algunosgestoresde back-endy para proporcionarla traduccióndel menúpara los componentes. Al instalar o actualizarla extensión, es el presentearchivosys.inien la carpeta deextensión del lenguaje deraíz el quemostraráel resultado dela instalaciónde la descripciónkey/value.A partir de entonces, si está presente, el sys.iniasí como el iniinstalado en la carpeta del núcleo de idiomatendrán prioridad sobrelos archivospresentes enla carpeta del idiomaraíz dela extensión. 26

Desarrollar componente en Joomla

Jesús García Pérez

Nota:Una de las ventajasde la instalación delos archivos de lacarpeta de idioma de la extensión es que estos nose tocanen la actualización deun paquete de idioma. La otra ventaja esque esta carpetapuede incluirvarios idiomas(es-ES siempre,es-ES, es-ES, etc) que no requierenque el usuario instaleel paquete de idiomacorrespondiente.Esto es útilya que están disponiblessi,más adelante,un usuario instalael paquetecorrespondiente.

9.5 Añadir traducciones a la instalación del componente language/en-GB/en-GB.iniEste archivo contendrá la traducción para la instalación. La descripción COM_GRTIC_DESCRIPTION se puede usar en el archivo grtic.xml. En este archivo grtic.xml los idiomas son instalados en: * administrator/language para el lado del administrador (mire en la etiqueta xmllanguages) * components/com_grtic/language para el lado público (no hay etiquetas xmllanguages en el lado público del archivo de descripción xml, pero la carpeta de idioma se incluye). Archivo con el código: grtic3.zip

10 Añadir una barra de herramientas En Joomla, el administrador interactúa generalmente con los componentes a través de una barra de herramientas. En el archivo admin/views/grtics/view.html.phpse creará una barra de herramientas básica y un título para el componente. admin/views/grtics/view.html.php se añade la creación de la barra de herramientas básica y un título para el componente. Clase grticViewgrticsque extiende a JView.

27

Desarrollar componente en Joomla

Jesús García Pérez

28

Desarrollar componente en Joomla

Jesús García Pérez

Puede encontrar otras acciones del backend clásicas en el archivo administrator/includes/toolbar.php de su instalación de Joomla. Ya que la vista puede realizar algunas acciones, tenemos que añadir algunos datos de entrada en la vista por defecto. admin/views/grtisc/tmpl/default.phpLa vista por defecto. Muestra la tabla con los datos de entrada y se le han añadido algunos datos de entrada.

29

Desarrollar componente en Joomla

Jesús García Pérez

10.1 Añadir controladores específicos Se han añadido 3 acciones:   

grtics.delete (Borrar un elemento) grtic.edit (Editar un elemento) grtic.add (Añadir un elemento)

Estas son las tareas de composición (controller.task). Por tanto hay que codificar 2 nuevos controladores grticControllergrtics y grticControllergrtic. Para ello crearemos tareas en el controlador específico para después poder llamarlas de la manera controller.tarea admin/controllers/grtics.phpclasegrticControllergrticsqueextiendeJControllerAdmin

30

Desarrollar componente en Joomla

Jesús García Pérez

admin/controllers/grtic.phpclasegrticControllergrticqueextiendeJControllerForm.

31

Desarrollar componente en Joomla

Jesús García Pérez

10.2 Añadir una vista de edición Creamos la vista para editar los elementos. admin/views/grtic/view.html.phpgrticViewgrticqueextiendeJView.Esta usando una posición.

32

vista

mostrará

datos

Desarrollar componente en Joomla

Jesús García Pérez

admin/views/grtic/tmpl/edit.phpPlantilla de la vista de edición, con el formulario de edición

10.3 Añadir un modelo y modificar el existente 33

Desarrollar componente en Joomla

Jesús García Pérez

La vista grticViewgrtic pide formularios y datos a un modelo. Este modelo tiene que proveer los métodos getTable, getForm y loadData (llamados desde el controlador JModelAdmin). admin/models/grtic.php clase grticModelgrtic que extiende JModelAdmin

34

Desarrollar componente en Joomla

Jesús García Pérez

Este modelo hereda de la clase JModelAdmin y usa su método loadForm. Este método busca los formularios en la carpeta forms. Además tendremos que crear un archivo XML que nos permitira definir los diferentes campos del formulario. Esto lo ha incorporado el nuevo Joomla! 1.6. admin/models/forms/grtic.xml información sobre los campos del formulario

11 Añadir adornos en el back-end Para poder gestionar nuestro programa necesitamos ejecutar acciones. Donde colocar estas acciones es decisión de cada uno. Joomla nos pone a su disposición una clase que no ayudará a este propósito:JToolBarHelper. Por ahora sólo vamos a dedicarnos a mostrar esta barra de herramientas y cambiar los iconos de nuestro componenente. Más adelante investigaremos como realizar las solicitudes de la aplicación y como responder a éstas. Nos interesaremos en la siguiente instrucción: JToolBarHelper::title(JText::_('COM_GRTIC_MANAGER_GRTICS'),'grtic'); En el primer parámetro title introducimos el título un texto que deseemos (generalmente el título del componente). Si añadimos un segundo parámetro este sirve para poner el nombre de clase CSS que deseemos (en nuestro caso 'grtic'). En este segundo parámetro podemos introducir más de una palabra separada con un espacio en blanco lo que producirá más de un nombre de clase. Con este nombre de clase aprovecharemos para insertar el icono de nuestra aplicación. 35

Desarrollar componente en Joomla

Jesús García Pérez

Como se verá se ha añadido un método ($this->addToolBar()) en nuestro fichero admin/views/grtics/view.html.php que ejecuta la instrucción anteriormente explicada. También observaréis que hemos creado otro método ($this->setDocument()) que se valdrá de objtetogetDocument que utilizaremos para insertar el título de la página y añadir el css para colocar nuestro icono. Este icono tendrá un tamaño de 48x48 píxeles (el icono de la barra del menú de 16x16 píxeles se notificará a través del archivo xml como se observará más adelante).

11.1 Añadir algunos iconos Con su gestor y editor de archivos favorito cree una imagen de 16x16 y otra de 48x48 en la carpeta media/images y añada una etiqueta media en el archivo de instalación (grtic.xml). Modifique la etiqueta menu para usar el nuevo icono.

11.2 Modificar las vistas admin/views/grtics/view.html.php Clase grticViewgrtics que extiende JView.

36

Desarrollar componente en Joomla

Jesús García Pérez

Esta vista usa un segundo parámetro para la función JToolBarHelper::title. Se usará para construir una clase CSS para el título. El método _setDocument establece el título en el navegador. admin/views/grtic/view.html.php Clase grticViewgrtic que extiende JView.

37

Desarrollar componente en Joomla

Jesús García Pérez

38

Desarrollar componente en Joomla

Jesús García Pérez

Esta vista también usa el segundo parámetro de la función JToolBarHelper::title para establecer el título en el navegador.

11.3 Modificar el archivo principal de entrada admin/grtic.php se indica el icono de 48x48. 39

Desarrollar componente en Joomla

Jesús García Pérez

11.4 Añadir algunas cadenas de palabras en el archivo de idioma admin/language/en-GB/en-GB.com_grtic.ini Se anaden las líneas de la traducción.

12 Añadir verificaciones de formulario 12.1 Verificar el formulario (lado del cliente) Los formularios pueden verificarse en el lado público usando código javascript. admin/views/grtic/tmpl/edit.php en este archivo lo añadimos.

40

Desarrollar componente en Joomla

Jesús García Pérez

Puede que hayas notado que el formulario HTML contenido en el archivo admin/views/grtic/tmpl/edit.php ahora tiene la clase CSS form-validate. Y que hemos añadido una llamada a JHTML::_('behavior.formvalidation'); para decirle a Joomla que use su validación de formularios Javascript. admin/models/forms/grtic.xml Se indica que el campo titulo tiene que ser verificado.

41

Desarrollar componente en Joomla

Jesús García Pérez

Nótese que ahora la clase CSS es "inputboxvalidate-titulo" y que el atributo requiredesta definido como true. Esto significa que este campo es obligatorio y que tiene que ser verificado por el encargado de la validacion de formularios del marco de trabajo de Joomla. admin/models/forms/grtic.js el archive javascript que valida el campo.

Esto añade un encargado al validador de formularios de Joomla para todos los campos que contengan la clase de CSS "validate-titulo". Cada vez que el campo titulo se modifique, el encargado se ejecutara para verificar su validación (no dígitos). El último paso es verificar el formulario cuando se pulsa en el botón enviar. admin/views/grtic/submitbutton.js se valida el formulario cuando se pulsa el botón de enviar.

42

Desarrollar componente en Joomla

Jesús García Pérez

Esta función verificara que todos los formularios con la clase de CSS "form-validate" sean válidos. Nótese que esto mostrará un mensaje de alerta traducido por el marco de trabajo de Joomla. admin/views/grtic/view.html.phpLa clase de la vista grticViewgrtic tiene que ser modificada para usar estos archivos Javascript.

43

Desarrollar componente en Joomla

Jesús García Pérez

44

Desarrollar componente en Joomla

Jesús García Pérez

Esta vista ahora: 45

Desarrollar componente en Joomla

Jesús García Pérez

* verifica que el modelo no contenga errores; * añade 2 archivos Javascript; * inyecta la traduciónjavascript usando la función JText::script del núcleo de Joomla. admin/models/grtic.phpEl último paso es implementar una función getScript en el modelo grticModelgrtic.

46

Desarrollar componente en Joomla

Jesús García Pérez

12.2 Verificar el formulario (lado del servidor) Verificar el formulario en el lado del servidor se hace por herencia de la clase JControllerForm. Hemos especificado en el archivo admin/models/forms/grtic.xml que la función de validación del servidor usará el archivo titulo.php. admin/models/rules/titulo.php Clase JFormRuleTitulo que extiende JFormRule.

47

Desarrollar componente en Joomla

Jesús García Pérez

13 Añadir categorías 13.1 Introducción El marco de trabajo de Joomla ha implementado el uso de categorías para todos los componentes. Añadir la capacidad de categorizar a un componente es bastante simple.

13.2 Modificar el SQL Para gestionar categorías tenemos admin/sql/install.mysql.utf8.sql

que

cambiar

las

tablas

SQL

en

el

fichero

DROP TABLE IF EXISTS `#__grtic`; CREATE TABLE `#__grtic` ( `id` int(11) NOT NULL AUTO_INCREMENT, `titulo` varchar(25) NOT NULL, `catid` int(11) NOT NULL DEFAULT '0', PRIMARY KEY (`id`) ) ENGINE=MyISAM AUTO_INCREMENT=0 DEFAULT CHARSET=utf8; INSERT INTO `#__grtic` (`titulo`) VALUES ('Gestión de recursos TIC'), ('Recursos TIC'), ('Escuela TIC 2.0'); yadmin/sql/updates/mysql/0.0.12.sql ALTER TABLE `#__grtic` ADD `catid` int(11) NOT NULL DEFAULT '0'

13.3 Modificar el formulario Un mensaje grtic puede ahora pertenecer a una categoría. Tenemos que modificar el formulario de ediciónadmin/models/forms/grtic.xml

48

Desarrollar componente en Joomla

Jesús García Pérez

Nótese que la categoría puede ser 0, que representa sin categoría.

13.4 Modificar el tipo de menú El tipo de menú grtic muestra una lista desplegable de todos los mensajes. Si el mensaje está categorizado tenemos que mostrar también la categoría.Ahora se mostrará la categoría entre paréntesis. admin/models/fields/grtic.phpclase JFormFieldgrtic que extiende JFormFieldList

49

Desarrollar componente en Joomla

Jesús García Pérez

13.5 Gestionar el submenú 50

Desarrollar componente en Joomla

Jesús García Pérez

El componente com_categories permite establecer el submenú usando un archivo de ayuda. admin/helpers/grtic.php clase grticHelper, componente de ayuda

Esta función se llamará automáticamente por el componente com_categories. Nótese que esto cambiará: * elsubmenu * algunas propiedades CSS (para mostrar iconos) * el título del navegador si el submenú está categorizado * el título y añade un botón de preferencias Tenemos que cambiar el controlador general para llamar a esta función y modificar el punto de entrada del componente (la clase CSS .icon-48-grticesta ahora establecida en la función addSubmenu) admin/controller.php controlador general del componente grtic.

51

Desarrollar componente en Joomla

Jesús García Pérez

admin/grtic.php se le añade que incluya el archivo de ayuda

52

Desarrollar componente en Joomla

Jesús García Pérez

13.6 Añadir algunas cadenas de traducciones admin/language/en-GB/en-GB.com_grtic.iniAlgunas cadenas tienen que traducirse. COM_GRTIC="GRTIC" COM_GRTIC_ADMINISTRATION="GRTIC - Administración" COM_HELLOWORLD_ADMINISTRATION_CATEGORIES="GRTIC - Gategorías" COM_GRTIC_GRTIC_CREATING="GRTIC - Creación" COM_GRTIC_GRTIC_DETAILS="Detalles" COM_GRTIC_GRTIC_EDITING="GRTIC - Edición" COM_GRTIC_GRTIC_ERROR_UNACCEPTABLE="Algunos valorea son inaceptables" COM_GRTIC_GRTIC_FIELD_CATID_DESC="Los mensajes pertenecen a la categoría" COM_GRTIC_GRTIC_FIELD_CATID_LABEL="Categoría" COM_GRTIC_GRTIC_FIELD_TITULO_DESC="Este mensaje será mostrado" COM_GRTIC_GRTIC_FIELD_TITULO_LABEL="Mensaje" COM_GRTIC_GRTIC_HEADING_TITULO="Título" COM_GRTIC_GRTIC_HEADING_ID="Id" COM_GRTIC_MANAGER_GRTIC_EDIT="GRTIC gestor: Editarmensaje" COM_GRTIC_MANAGER_GRTIC_NEW="GRTIC gestor: Nuevo mensaje" COM_GRTIC_MANAGER_GRTICS="GRTIC gestor" COM_GRTIC_N_ITEMS_DELETED_1="Un mensaje eliminado" COM_GRTIC_N_ITEMS_DELETED_MORE="%d mensajes eliminados" COM_GRTIC_SUBMENU_MESSAGES="Mensajes" COM_GRTIC_SUBMENU_CATEGORIES="Categorías"

14 Añadir parámetros de configuración El marco de trabajo de Joomla permite el uso de parámetros almacenados en cada componente. 53

Desarrollar componente en Joomla

Jesús García Pérez

admin/config.xmlcontiene los parámetros

Este archivo será leído por el componente com_config del núcleo de Joomla. Por el momento hemos definido solamente un parámetro: ¿se muestra o no se muestra el título de la categoría en el lado público? La mejor manera de establecer los parámetros es añadir un botón de Preferencias en la barra de herramientas. admin/views/grtics/view.html.php Se añade ese botón

14.1 Usar la configuración de parámetros como valor por defecto Queremos definir este parámetro individualmente en todos los datos grtic. admin/models/forms/grtic.xml se añade el parámetro para la categoría

54

Desarrollar componente en Joomla

Jesús García Pérez

Definimos el mismo parámetro para cada mensaje con un valor adicional: Use global (Usar Global).

14.2 Modificar el SQL 55

Desarrollar componente en Joomla

Jesús García Pérez

Los datos ahora contienen un parámetro nuevo: params. admin/sql/install.mysql.utf8.sqlLa estructura SQL tiene que modificarse añadiendo el parámetro params. DROP TABLE IF EXISTS `#__grtic`; CREATE TABLE `#__grtic` ( `id` int(11) NOT NULL AUTO_INCREMENT, `titulo` varchar(25) NOT NULL, `catid` int(11) NOT NULL DEFAULT '0', `params` TEXT NOT NULL DEFAULT '', PRIMARY KEY (`id`) ) ENGINE=MyISAM AUTO_INCREMENT=0 DEFAULT CHARSET=utf8; INSERT INTO `#__grtic` (`titulo`) VALUES ('Gestión de recursos TIC'), ('Recursos TIC'), ('Escuela TIC 2.0');

admin/sql/updates/mysql/0.0.13.sqlLa estructura SQL tiene que modificarse añadiendo el parámetro params. ALTERTABLE`#__helloworld`ADD`params`VARCHAR(1024)NOTNULLDEFAULT'';

Admin/tables/grtic.phpLa función Tablegrtic debe modificarse para que coordine con estos parámetros: se almacenarán en un formato JSON y se obtendrán en una clase JParameter. Tenemos que sobrecargar los métodos bind y load.

56

Desarrollar componente en Joomla

Jesús García Pérez

57

Desarrollar componente en Joomla

Jesús García Pérez

14.3 Modificar el lado del administrador La vista de edición del lado del administrador tiene que mostrar las opciones al administrador. admin/views/grtic/tmpl/edit.php

58

Desarrollar componente en Joomla

Jesús García Pérez

14.4 Modificar el lado público El lado público se tiene que modificar de acuerdo con el nuevo parámetro show_category. Tenemos que modificar el modelo: -

tiene que fusionar los parámetros globales con los individuales. tiene que proporcionar la categoría.

site/models/grtic.php 59

Desarrollar componente en Joomla

Jesús García Pérez

60

Desarrollar componente en Joomla

Jesús García Pérez

La vista le pide la categoría al modelo. site/views/grtic/view.html.php:

61

Desarrollar componente en Joomla

Las posiciones pueden ahora site/views/grtic/tmpl/default.php:

Jesús García Pérez

mostrar

correctamente

la

categoría

o

no

mostrarla.

14.5 Añadir algunas cadenas de traducción Algunas cadenas se tienen que añadir al archivo admin/language/en-GB/en-GB.com_grtic.ini: COM_GRTIC="GRTIC" COM_GRTIC_ADMINISTRATION="GRTIC - Administración"

62

Desarrollar componente en Joomla

Jesús García Pérez

COM_HELLOWORLD_ADMINISTRATION_CATEGORIES="GRTIC - Gategorías" COM_GRTIC_GRTIC_CREATING="GRTIC - Creación" COM_GRTIC_GRTIC_DETAILS="Detalles" COM_GRTIC_GRTIC_EDITING="GRTIC - Edición" COM_GRTIC_GRTIC_ERROR_UNACCEPTABLE="Algunos valorea son inaceptables" COM_GRTIC_GRTIC_FIELD_CATID_DESC="Los mensajes pertenecen a la categoría" COM_GRTIC_GRTIC_FIELD_CATID_LABEL="Categoría" COM_GRTIC_GRTIC_FIELD_TITULO_DESC="Este mensaje ser´ mostrado" COM_GRTIC_GRTIC_FIELD_TITULO_LABEL="Mensaje" COM_GRTIC_GRTIC_FIELD_SHOW_CATEGORY_LABEL="Mostrarcategoría" COM_GRTIC_GRTIC_FIELD_SHOW_CATEGORY_DESC="si se configura para mostrar, el título de la categoría de los mensajes se mostrarán." COM_GRTIC_GRTIC_HEADING_TITULO="Título" COM_GRTIC_GRTIC_HEADING_ID="Id" COM_GRTIC_MANAGER_GRTIC_EDIT="GRTIC gestor: Editarmensaje" COM_GRTIC_MANAGER_GRTIC_NEW="GRTIC gestor: Nuevo mensaje" COM_GRTIC_MANAGER_GRTICS="GRTIC gestor" COM_GRTIC_N_ITEMS_DELETED_1="Un mensaje eliminado" COM_GRTIC_N_ITEMS_DELETED_MORE="%d mensajes eliminados" COM_GRTIC_SUBMENU_MESSAGES="Mensajes" COM_GRTIC_SUBMENU_CATEGORIES="Categorías" COM_GRTIC_CONFIG_TITULO_SETTINGS_LABEL="Configuración de los mensajes" COM_GRTIC_CONFIG_TITULO_SETTINGS_DESC="Configuraciones que se aplicarán a todos los mensajes por defecto"allmessagesby default"

15 Describiendo el ACL (Lista de control de Acceso) Cada componente tiene su propio ACL (Lista de control de acceso. Se pueden especificar en el archivo access.xml ubicado en la raíz de la carpeta del administrador. Este archivo describe el ACL para el componente com_grtic en una sección diferente. En este ejemplo hemos elegido separar los diferentes ACL en dos secciones: componentes y mensajes. admin/access.xml

15.1 Restringir el acceso al componente La idea principal del ACL es restringir acciones a grupos de usuarios. La primera acción a restringir es el acceso al componente en sí mismo. Modificamos el archivo admin/grtic.php:

63

Desarrollar componente en Joomla

Jesús García Pérez

15.2 Mostrar solamente los botones correctos de la barra de herramientas Los botones de la barra de herramientas se tienen que mostrar dependiendo de los permisos de ACL. Modificamos el archivo admin/views/grtics/view.html.php:

64

Desarrollar componente en Joomla

Jesús García Pérez

Modificamos el archivo admin/views/grtic/view.html.php:

65

Desarrollar componente en Joomla

Jesús García Pérez

Estos dos archivos usan el método getActions definido en el archivo admin/helpers/grtic.php. Vamos a modificarlo.

15.3 Añadir ajustes de permisos en las preferencias del componente Como ahora usamos permisos ACL en nuestro componente, necesitamos ajustarlos a nivel del componente. admin/config.xml

66

Desarrollar componente en Joomla

Jesús García Pérez

15.4 Ajustar el valor en la tabla de recursos Para ajustar el recurso de cada mensaje tenemos que hacer dos cosas. Primero, el 'core.edit' ACL "right" se coge del mensaje en sí mismo, después del componente. admin/models/grtic.php

67

Desarrollar componente en Joomla

Jesús García Pérez

Segundo, ajustar el nombre del recurso, su título y su padre en la tabla grtic. admin/tables/grtic.php

68

Desarrollar componente en Joomla

Jesús García Pérez

69

Desarrollar componente en Joomla

Jesús García Pérez

16 Añadir un script para instalar/desinstalar/actualizar 16.1 Crear el archivo de script de la extensión Instalar, actualizar y desinstalar un componente puede requerir operaciones especiales que no pueden ser logradas por las operaciones básicas descritas en el archivo XML principal. Joomla ofrece una 70

Desarrollar componente en Joomla

Jesús García Pérez

nueva propuesta para solventar este problema. Consiste en usar un archivo de scripts PHP que contenga una clase que use cinco métodos: * preflight, que se ejecuta antes de instalar y actualizar (prevuelo) * install (instalar) * update (actualizar) * uninstall (desistalar) * postflight, que se ejecuta después de instarlar y actualizar (postvuelo) Escribir un script de extensión consiste en declarar com_ComponentNameInstallerScript y que tenga 5 métodos. script.php

71

una

clase

cuyo

nombre

sea

Desarrollar componente en Joomla

Jesús García Pérez

Este archivo de script redirigiráal usuario al componente com_grtic cuando esté instalado y mostrará mensajes cuando esté actualizado o desinstalado.

16.2 Añadir algunas claves de idioma admin/language/en-GB/en-GB.com_grtic.sys.ini COM_GRTIC="Gestión de recursos TIC" COM_GRTIC_DESCRIPTION="Portal de gestión de recursos TIC" COM_GRTIC_GRTIC_VIEW_DEFAULT_DESC="Esta vista muestra un mensajes seleccionado" COM_GRTIC_GRTIC_VIEW_DEFAULT_TITLE="GrTIC" COM_GRTIC_INSTALL_TEXT="Grtic Install script" COM_GRTIC_MENU="Gestión de recursos TIC" COM_GRTIC_POSTFLIGHT_DISCOVER_INSTALL_TEXT="Grticdescrubimientoposvuelo del instalación" COM_GRTIC_POSTFLIGHT_INSTALL_TEXT="Grticposvuelo del script de instalación" COM_GRTIC_POSTFLIGHT_UNINSTALL_TEXT="Grticposvuelo del script de desinstalación" COM_GRTIC_POSTFLIGHT_UPDATE_TEXT="Grticposvuelo del script de actualización" COM_GRTIC_PREFLIGHT_DISCOVER_INSTALL_TEXT="Grticdescrubimientoposvuelo del instalación" COM_GRTIC_PREFLIGHT_INSTALL_TEXT="Grticposvuelo del script de instalación" COM_GRTIC_PREFLIGHT_UNINSTALL_TEXT="Grticposvuelo del script de desinstalación"

72

script

de

script

de

Desarrollar componente en Joomla

Jesús García Pérez

COM_GRTIC_PREFLIGHT_UPDATE_TEXT="Grticposvuelo del script de actualización" COM_GRTIC_UNINSTALL_TEXT="Grtic script de desinstalación" COM_GRTIC_UPDATE_TEXT="Grtic script de actualización""

17 Añadir un servidor para actualizaciones Para añadir la funcionalidad de un servidor para actualizaciones ajuste el archivo grtic.xml para que se parezca a este: grtic.xml

73

Desarrollar componente en Joomla

Jesús García Pérez

También tienes que poner un archivo XML en tu servidor que contenga toda la información de actualizaciones. grtic-update.xml

74

Desarrollar componente en Joomla

Jesús García Pérez

Necesitas añadir un nuevo update-node (nodo de actualización) cada vez que se publique una nueva versión. Aquí concluye el tutorial sobre la creación de componentes para Joomla. Esperamos que les haya sido de utilidad.

18 Bibliografía -

Tutorial en inglés sobre el que se ha desarrollado el manual: http://docs.joomla.org/Developing_a_Model-ViewController_%28MVC%29_Component_for_Joomla!1.6.

Otras referencias que ha servido de ayuda: -

http://www.infosol.es/es/tutoriales.html http://www.webferrol.com/index.php/es/articulos-es/joomla-es/20-creacion-de-uncomponente-en-joomla-es http://ayudajoomla.com/joomla/programacion/356-desarrollo-de-componentes-para-joomla16.html

75