Definición de Contenido Estructurado OpenCms

Fri May 22 23:11:00 CEST 2009       Sergio Raposo Vargas       Manuales y tutoriales

La presente guía pretende constituir un material de referencia para la definición de contenido XML estructurado en OpenCms. El contenido estructurado puede ser utilizado para crear ‘contenidos especiales’ para Carteleras de Cine, Horoscopos, Infografías y otros tipos  de contenido.

Introducción y Objetivos

Básicamente la tarea comprenderá dos conjuntos de acciones diferenciadas:

  1. Aquellas que tengan que ver con la administración llevada a cabo desde el Workplace de OpenCms, lo que puede realizarse desde cualquier Web Browser, a través de la dirección en que se encuentre nuestro sistema.
  2. La modificación de los archivos de configuración de OpenCms, para lo cual deberá accederse a la ubicación del servidor que soporte la instancia del sistema que estamos utilizando.

Debido a que muy probablemente nos encontremos accediendo remotamente al servicio, deberemos valernos de algún método que nos permita tener acceso a los archivos necesarios desde donde nos encontremos. Puede optarse por una herramienta como PuTTY, o cualquier otra que nos permita conectarnos al servidor destino y acceder a sus archivos.

Nuestro objetivo sera entonces el de crear un tipo de contenido estructurado y facilitar su manipulación desde el Workplace. Podremos crear un nuevo tipo definido por el usuario, seleccionándolo desde la interfaz de creación, y editar su contenido, a partir del formulario que generará OpenCms con los parámetros que le indiquemos.

Nuestro interés se centra en ciertos archivos de configuración ubicados en el path <rutaTomcat>/webapps/opencms/WEB-INF/config (por ejemplo, para sistemas Linux suele ser por defecto: /usr/share/tomcat5/webapps/opencms/WEB-INF/config).

Opencms posee dos formas de realizar la definición de un tipo de contenido estructurado:

  • La primera opción implica la modificación de los archivos opencms-vfs.xml y opencms-workplace.xml. Esta opción no es recomendada debido a su complejidad.
  • La segunda opción implica colocar los archivos que definirán la nueva estructura dentro de un modulo separado, y editar la definición de dicho módulo dentro del archivo opencms-modules.xml, que se encuentra en la misma ruta que los dos anteriores, y se encarga de albergar el “esqueleto” de los módulos definidos en nuestro sistema. Esta es la opción recomendada que utilizaremos.

En resumen, esta última opción implica agregar información a opencms-modules.xml sobre el nuevo contenido en dos niveles:

  • Una referencia al archivo xsd que definirá nuestro contenido, lo que puede lograrse a través del elemento <type> de <resourcetypes>, más precisamente en su item <param>.

      Ejemplo: <param name=”schema”>”Path xsd”</param>

  • Detalles sobre el tipo de contenido en la vista de Explorador del Workspace (nombre, descripción, icono, etc), usando el elemento <explorertype> de <explorertypes>.

Ejemplo: <explorertype name=”nombreContenido“    key=”claveNuevoContenido” icon=”imagen.gif” reference=”xmlcontent“>

A continuación, describiremos paso a paso las tareas a realizar para implementar la opción 2.

Paso 1: Creación del Módulo
 
Desde la vista de Administración, estando en Offline procedemos a la creación de un nuevo módulo. Como nombre de package usaremos com.tfsla.contenidos.prueba, y para el nombre del módulo utilizaremos, por ejemplo, Definicion de contenido estructurado. Es importante tildar los campos Create Modulefolder y Create classes subfolder entre las opciones que ofrece el recuadro Module folders. De lo contrario deberemos dirigirnos al mencionado opencms-modules.xml para definirlo manualmente, o realizarlo luego desde el Workplace.

Una vez creado el módulo, debe corroborarse que se haya generado automáticamente un Export Point para el subdirectorio classes que se eligió crear anteriormente. Para esto seleccionamos el nombre del módulo creado dentro de la vista de administración, con lo cual accederemos a un conjunto de opciones, entre las que se encuentra Module exportpoints. Una vez allí, podremos observar que la carpeta classes del módulo creado (/system/modules/com.tfsla.contenidos.prueba/classes/) se mapea en WEB-INF/classes, lo que nos indica que fue correctamente creado. De lo contrario deberá elegirse New exportpoint y completarse los campos de forma manual.

Luego de esto nos encargaremos de los recursos. Volvemos a la vista de administración con las opciones de nuestro flamante módulo y seleccionamos esta vez, Module Resources. Seguramente se encontrará el path de nuestro módulo (/system/modules/com.tfsla.contenidos.prueba/).

Nuestra lista de recursos debería incluir rutas a archivos utilizados en la configuración de contenido estructurado, localizados en distintas partes del VFS. En particular el camino hacia la carpeta que contiene iconos para listar el contenido estructurado en la interfaz del Workplace. Éste es por defecto: /system/workplace/resources/filetypes/, que procedemos a añadir a nuestra lista de recursos.

Paso 2: Creación del esquema XSD

Así como optamos anteriormente por crear un módulo separado que contenga los elementos de nuestro nuevo tipo de contenido, haremos lo propio con los archivos xsd que definirán la estructura del mismo. Para esto nos colocamos dentro del módulo creado (/system/modules/com.tfsla.contenidos.prueba/) y vamos a New->Folder, en la vista de Explorador. Le pondremos el nombre schemas a la carpeta, que es el que se utiliza comúnmente para estos fines. Nos limitaremos sólo a nombrarlo, sin añadir cualquier otra propiedad.

Dentro de schemas, procederemos a generar un nuevo recurso, esta vez, un archivo del tipo Text File, al que nombraremos como contenidos.xsd.

A continuación, procederemos a editarlo, para dar lugar a un nuevo tipo de contenido con una estructura similar a la de una noticia.

Nos basaremos en el ejemplo que proporciona Alkacon, con algunas modificaciones. Podemos encontrarlo dentro del tutorial llamado “OpenCms XML content documentation”, que viene con la versión que utilizamos de OpenCms.

Nuestro contenido llevará un título, una cantidad de hasta tres subtítulos y un cuadro de texto.

A continuación se transcribe el xsd del que haremos uso:

<xsd:schema xmlns:xsd=”http://www.w3.org/2001/XMLSchema” elementFormDefault=”qualified”> 
        <xsd:include schemaLocation=”opencms://opencms-xmlcontent.xsd”/>    
        <xsd:element name=”TfsTypes type=”OpenCmsTfsTypes/> 
        <xsd:complexType name=”OpenCmsTfsTypes“>
               <xsd:sequence>
                       <xsd:element name=”TfsType” type=”OpenCmsTfsType” minOccurs=”0″ maxOccurs=”unbounded”/>
               </xsd:sequence>
        </xsd:complexType>
        <xsd:complexType name=”OpenCmsTfsType“>
               <xsd:sequence>
                  <xsd:element name=”Titulo” type=”OpenCmsString” />
                   <xsd:element name=”Subtitulo” type=”OpenCmsString” maxOccurs=”3″/>
                  <xsd:element name=”Texto” type=”OpenCmsHtml” />
               </xsd:sequence>
               <xsd:attribute name=”language” type=”OpenCmsLocale” use=”required”/>
        </xsd:complexType> 
 </xsd:schema>

Como se puede observar, este archivo contiene el nombre del elemento raíz (TfsTypes, que debe terminar siempre con una “s”) y el tipo del contenido XML (que debe llevar el mismo nombre precedido del prefijo OpenCms).

Debajo de estas definiciones podemos ver la del elemento hijo con nombre TfsType (igual a su padre pero sin la “s”), y a continuación una segunda definición de tipo complejo, que contiene la secuencia de elementos con sus correspondientes tipos de datos. Aquí usamos OpenCmsString para cadenas cortas sin contenido HTML, y OpenCmsHtml que permite almacenar texto con contenido HTML.

Debe editarse el contenidos.xsd creado con esta información, y guardarse para finalizar la etapa de definición.

Paso 3: Modificación de archivos de configuración

Como mencionamos anteriormente, el archivo de configuración que modificaremos se llama opencms-modules.xml y se encuentra por defecto en el path

/usr/share/tomcat5/webapps/opencms/WEB-INF/config en sistemas Linux.

Hay que tener en cuenta que para modificar este tipo de archivos es necesario tener ciertos permisos, que, por lo general, no son frecuentes en usuarios normales del sistema. El root siempre puede llevar a cabo estas actualizaciones, por lo que es recomendable, o bien ingresar como éste, o adquirir sus permisos (por ejemplo, en Linux el comando sudo su nos permite que nuestro uid y gid reales y efectivos se seteen a los del superusuario, y podamos ejecutar comandos como él sin necesidad de estar logueados a root).

En primer lugar debemos identificar la parte del archivo opencms-module.xml que editaremos a continuación. Dicha sección del fichero será la que contenga las definiciones sobre el módulo que creamos. En nuestro caso se trata de la siguiente:

         <module>
            <name>com.tfsla.contenidos.prueba</name>
            <nicename><![CDATA[Definicion de contenido estructurado.]]></nicename>
            <class/>
            <description/>
            <version>0.2</version>
            <authorname/>
            <authoremail/>
            <datecreated/>
            <userinstalled/>
            <dateinstalled/>
            <dependencies/>
            <exportpoints>
                <exportpoint uri=”/system/modules/com.tfsla.contenidos.prueba/classes/” destination=”WEB-INF/classes/”/>
            </exportpoints>
            <resources>
                <resource uri=”/system/modules/com.tfsla.contenidos.prueba/”/>
                <resource uri=”/system/workplace/resources/filetypes/”/>
            </resources>
            <parameters/>
        </module>

Para localizar este fragmento podemos valernos de varios recursos si contamos con un editor sofisticado, sin embargo este no es siempre el caso, ya que, por lo general, nos valemos de versiones del sistema operativo concebidas con el único fin de soportar la instancia del OpenCms del que nos servimos. Si utilizamos vi para la edición (nos basaremos en dicho editor por encontrarse en la mayoría de los casos disponible), podremos localizar esta porción facilmente a través del comando de búsqueda :/ , seguido del nombre de nuestro módulo (com.tfsla.contenidos.prueba). El cursor se posicionará entonces en el sector deseado dentro del xml.

Para proceder a la edición de esta parte, nos basaremos en un módulo ya existente en el sistema, a fin de copiar la estructura necesaria, modificando las secciones que merezcan un tratamiento especial. Esto nos permitirá reutilizar un código ya probado y evitar cualquier error debido a restricciones inherentes.

Nos dirigimos, dentro del mismo opencms-modules.xml, a la sección que define el módulo org.opencms.frontend.templateone.xmlcontentdemo.

Nuestro interés se encuentra en los elementos etiquetados como <resourcetypes> y <explorertypes>.

Dentro de <resourcetypes> nos interesa el siguiente fragmento:

            <resourcetypes>
                <type class=”org.opencms.file.types.CmsResourceTypeXmlContent” name=”article” id=”25“>
                    <param name=”schema”>/sites/default/xmlcontentdemo/article.xsd</param>
                </type>
            </resourcetypes> 

Marcamos en rojo lo que debe cambiarse. En name colocaremos el nombre de lo que deseamos crear. En nuestro caso lo bautizamos TfsType. En id deberemos optar por un identificador que sólo pertenezca al tipo que definiremos, es decir, debe ser único en el sistema OpenCms que estamos usando. Una buena opción sería comenzar a partir de 100, ya que hay escasas posibilidades de que en la declaración de contenidos se haya alcanzado este valor. Es importante aclarar que si se utiliza un id previamente definido, nuestra definición se corresponderá a la de aquella que lo haya usado, basándose nuestro tipo en la estructura creada para la misma.

Finalmente, en la etiqueta <param> correspondiente (marcada en rojo también), colocamos el path donde se halla nuestro xsd:

system/modules/com.tfsla.contenidos.prueba/schemas/contenidos.xsd.

Con respecto a los elementos de <explorertypes>, el fragmento que extraeremos desde xmlcontentdemo será éste: 

            <explorertypes>
                <explorertype name=”article” key=”fileicon.article” icon=”article.gif” reference=”xmlcontent”>
                    <newresource page=”structurecontent” uri=”newresource_xmlcontent.jsp?newresourcetype=article” order=”25” autosetnavigation=”false” autosettitle=”false”/>
                    <accesscontrol>
                        <accessentry principal=”GROUP.Administrators” permissions=”+r+v+w+c”/>
                        <accessentry principal=”GROUP.Projectmanagers” permissions=”+r+v+w+c”/>
                        <accessentry principal=”GROUP.Users” permissions=”+r+v+w+c”/>
                    </accesscontrol>
                </explorertype>
            </explorertypes>

Cambiaremos el atributo name a TfsType, key a fileicon.TfsType, y icon a xmlcontent.gif. En la uri, la palabra article coloreada debe ser reemplazada por TfsType y order al número elegido anteriormente, por ejemplo, 101. La parte restante puede dejarse sin cambios, al menos para los fines del presente artículo.

Resumiendo, el archivo opencms-modules.xml, en la porción de nuestro módulo deberá tener la siguiente apariencia:

        <module>
            <name>com.tfsla.contenidos.prueba</name>
            <nicename><![CDATA[Definicion de contenido estructurado.]]></nicename>
            <class/>
            <description/>
            <version>0.2</version>
            <authorname/>
            <authoremail/>
            <datecreated/>
            <userinstalled/>
            <dateinstalled/>
            <dependencies/>
            <exportpoints>
                <exportpoint uri=”/system/modules/com.tfsla.contenidos.prueba/classes/” destination=”WEB-INF/classes/”/>
            </exportpoints>
            <resources>
                <resource uri=”/system/modules/com.tfsla.contenidos.prueba/“/>
                <resource uri=”/system/workplace/resources/filetypes/”/>
            </resources>
            <parameters/>
            <resourcetypes>
                <type class=”org.opencms.file.types.CmsResourceTypeXmlContent” name=”TfsType” id=”101“>
                    <param name=”schema”>/system/modules/com.tfsla.contenidos.prueba/schemas/contenidos.xsd</param>
                </type>
            </resourcetypes>
            <explorertypes>
                <explorertype name=”TfsType” key=”fileicon.TfsType” icon=”xmlcontent.gif” reference=”xmlcontent”>
                    <newresource page=”structurecontent” uri=”newresource_xmlcontent.jsp?newresourcetype=TfsType” order=”101” autosetnavigation=”false” autosettitle=”false”/>
                    <accesscontrol>
                        <accessentry principal=”GROUP.Administrators” permissions=”+r+v+w+c”/>
                        <accessentry principal=”GROUP.Projectmanagers” permissions=”+r+v+w+c”/>
                        <accessentry principal=”GROUP.Users” permissions=”+r+v+w+c”/>
                    </accesscontrol>
                </explorertype>
            </explorertypes>
        </module>

Una vez editada esta sección del archivo abandonamos el editor y nos preparamos a la próxima etapa, nuevamente desde el Workplace. Nuestra incursión en los archivos de configuración se da por finalizada de esta manera.

Paso 4: Creación del archivo properties

Nos colocamos entonces en la vista del Explorador, en el Workplace de nuestro OpenCms y accedemos al path

/system/modules/com.tfsla.contenidos.prueba/classes/com/tfsla/contenidos/prueba/

para la creación de un archivo que nos permitirá definir cómo este tipo de contenido es llamado cuando es listado en la interfaz del Workplace.

Todo esto se logra a través de un archivo .properties (tabla hash), que bautizaremos como workplace.properties.

Damos New, para crear un nuevo Text File, con el nombre que mencionamos, y lo llenamos con lo siguiente: 

fileicon.TfsType = TfsType

title.TfsType = Create new TfsType 

Guardamos esta información y ya tenemos nuestro archivo properties listo para nuestra nueva definición.

 Paso 5: Creación de un recurso del tipo definido

Antes de proceder, reiniciaremos Tomcat, a fin de dar lugar a las modificaciones llevadas a cabo. 

Finalmente resta crear un nuevo elemento para probar nuestra definición. Vamos a New->Structured content, y veremos que entre las opciones que nos presenta el sistema, se encuentra la de nuestro flamante TfsType. Seleccionamos el tipo mencionado y luego lo editamos para ver que el formulario se creó de acuerdo a los parámetros colocados en el archivo contenidos.xsd.

De esta manera finaliza el proceso de definición de contenido XML estructurado. 

Información adicional y enlaces útiles:

  • Tutorial Oficial de Alkacon Software sobre contenidos estructurados llamado “OpenCms XML content Documentation”. Interesante para la definición de esquemas XSD. Carece de contenido sobre la utilización del tipo creado desde la interfaz del Workplace:

http://195.14.236.181/opencms/opencms/alkacon-documentation/documentation-xmlcontent/

  • Tutorial Flash para la creación de contenido estructurado:

http://www.wdogsystems.com/opencms/opencms/demos/structured_content_editing.html

  • Herramienta PuTTY, útil para el acceso remoto al servidor que contenga la instancia de OpenCms que usamos:

http://www.tartarus.org/~simon/putty-snapshots/x86/putty.exe