Creando módulos Plug and Play para OpenCms 8
De OpenCmsWiki
Contenido |
Introducción a los módulos de OpenCms
OpenCms 8 nos ofrece una nueva forma de preconfigurar el comportamiento de nuestros nuevos recursos creando un comportamiento por defecto. De esta forma, los recursos podrán estar listo para ser usados nada más instalar nuestro módulo. Evidentemente seguiremos pudiendo cambiar esta configuración por defecto para darle un comportamiento personalizado en el caso que sea necesario.
Los parámetros a definir usando esta nueva técnica son:
- Formatter por defecto
- Parámetros (setting) por defecto
- Nombre del repositorio (carpeta) donde guardaremos los recursos de este tipo
- Patrón utilizado para crear nuevos recursos del mismo tipo
La idea principal por lo tanto es la posibilidad de crear módulos lo más genérico posibles que permita por un lado personalizar al máximo la funcionalidad o aplicar la configuración por defecto.
Crear módulo plug & play paso a paso
Los pasos a dar para crear un módulo plug & play son:
- Crear un módulo desde la vista de administración.
- Crear un contenido estructurado dentro del módulo.
- Crear los formatters correspondientes que dan forma al nuevo contenido estructurado.
- Crear un recurso de tipo "Module configuration" que se encuentra en el grupo de recursos "Other options" en el raiz del módulo y llamarlo ".config".
- Configurar en este recurso el comportamiento por defecto de nuestro contenido estructurado.
- Añadir en el xsd la configuración de los formatters a aplicar según los distintos tipos de contenedores (containers) y los parámetros que el usuario podrá configurar desde el ADE.
¿Qué es un formatter?
Una vez creado el recurso debemos crear los formatters que le den forma a nuestro nuevo tipo de contenido. Los formatters no son más que una jsp que son capaces de leer la información registrada en el recurso y mostrarla por pantalla o usarla para su proposito. Estas jsp utilizarán el tag Cms:formatter.
Un recurso puede tener diferentes formatters que se aplicarán según el tamaño y el tipo del contenedor donde se agregue.
XSD: Configurar formatters por defecto
Para configurar los distintos formatters del recurso añadiremos dentro del bloque xsd:appinfo la siguiente entrada:
<formatters> <formatter minwidth="X1" maxwidth="X2" type="IDENTIFICADOR_DEL_CONTAINER" uri="ruta_jsp_formatter1.jsp"/> ... </formatters>
Los valores a configurar son:
- uri (Obligatorio): Ruta dentro del VFS de la jsp que dará forma al contenido estructurado.
- mindwidth ()Obligatorio): Ancho mínimo del formatter. Este valor indica el ancho mínimo que debe tener un container para poder aplicar este formatter.
- maxwidth: Ancho máximo del formatter. Este valori ndica el ancho máximo que podrá tener el container para poder aplicar el formatter.
- type: India el tipo de contenair donde se puede aplicar. Cuando creamos nuestros templates debemos definir nuestros contenedores y le tendremos que asignar un tipo a cada uno. Por ejemplo: column y center. En el caso que no queramos distinguir entre los contenedores podemos usar el valor '*' para englobarlos a todos.
Por lo tanto, OpenCms 8 decidirá que formatter aplicar a un recurso según el ancho y el tipo del contenedor donde se va a agregar. Debemos intentar que los anchos no se pisen, es decir, que no haya dos posibles formatters a aplicar para un mismo contenedor.
Ejemplo del recurso v8news.xsd:
<formatters> <formatter minwidth="400" uri="/system/modules/com.alkacon.opencms.v8.news/formatters/detail.jsp"/> <formatter minwidth="150" maxwidth="300" uri="/system/modules/com.alkacon.opencms.v8.news/formatters/side.jsp"/> </formatters>
En este ejemplo vemos como el formatter detail se aplicará para contenedores mayores de 400 y el side.jsp se aplicará para aquellos que tengan un ancho entre 150 y 300. Con esta configuración no existiría ningún formatter por defecto para la contenedores menores de 150 y comprendidos entre 300 y 400.
XSD: Setting por defecto
Desde el ADE: Advance Direct Edit un usuario podrá configurar cada caja (formatter utilizando el botón de setting.
Los campos a configurar podrán ser definidos por defecto en el XSD y personalizados si es necesario en cada sites. Para ello solo tendremos que añadir en el XSD, dentro del bloque xsd:appinfo la siguiente entrada:
<settings> <setting name="NOMBRE_PARAMETRO" nice-name="ETIQUETA" default="VALOR_POR_DEFECTO" type="TIPO" widget="WIDGET" widget-config="CONFIG_WIDGET" /> </settings>
Los campos a configurar son:
- name: Nombre del parametro que nos servirá posteriormente para recuperar el valor indicado por el usuario.
- nice-name: Etiqueta que el usuario verá en el ADE al editar el campo.
- default: Valor por defecto que se le asignará al parámetro si el usuario no lo rellena.
- type: Tipo del campo
- widget: Forma de edición del campo. Los posibles widgets son: checkbox, datebox, multiselect, radio, textarea, select, string, vfslink
- widget-config: Campo donde poder configurar el widget seleccionado, por ejemplo, indicando para un select los posibles valores de la lista.
Ejemplo de configuración del recurso v8article:
<settings> <setting name="boxschema" nice-name="%(key.v8.article.setting.boxschema)" default="box_schema3" type="string" widget="select" widget-config="box_schema3:Schema White|box_schema1:Schema Blue|box_schema2:Schema Red" /> <setting name="imgalign" nice-name="%(key.v8.article.setting.imgalign)" type="string" widget="select" widget-config="left:%(key.v8.article.image.left)|right:%(key.v8.article.image.right)|top:%(key.v8.article.image.top)|lefthl:%(key.v8.article.image.lefthl)|righthl:%(key.v8.article.image.righthl)" /> <setting name="hidetitle" nice-name="%(key.v8.article.setting.hidetitle)" type="string" widget="checkbox" /> <setting name="keephtml" nice-name="%(key.v8.article.setting.keephtml)" type="string" widget="checkbox" /> </settings>
El resultado de este ejemplo es:
Module Configuration
Para crear una configuración por defecto de nuestro contenido estructurado debemos crear un recurso llamado .config de tipo "Module Configuration" que se encuentra dentro del grupo "Other options":
Este recurso está formado por dos pestañas: Resource Type y Property configuration
Resource Type
Esta formado por los campos:
- Type name: Deberemos indicar el resourcetypename que queremos preconfigurar.
- Folder: En este campo podremos elegir entre asignar un path absoluto por defecto o el nombre de una carpeta. En el segundo caso se creará una carpeta con el nombre indicado en la carpeta .content del site actual.
- Name pattern: patrón que usaremos para crear los nuevos recurso. Por defecto es: resourcetypename-%(number).html.
- Detail pages disabled.
La pantalla es:
Property configuration
