Consejos de Instalación Cocoon 2 para Principiantes

Una vez que has intalado Cocoon querr�s empezar a hacer algo que valga la pena con el sistema. El primer encuentro con Cocoon tendr� lugar en el sitemap de Cocoon, que resulta que es un fichero situado justo en el directorio ra�z ($cocoon_root) de la aplicaci�n web Cocoon: sitemap.xmap.

Como leeras en cualquier lugar, el fichero sitemap.xmap es el coraz�n de Cocoon y, para poder conseguir que Cocoon haga algo para nosotros, primero tendremos que modificar este fichero. Luego vamos y al abrir el fichero y nos encontramos con una estructura XML realmente compleja! Hay una clara necesidad de mantener esto tan inalterable como sea posible. No s�lo querr�s dejar intacta y operativa la infraestructura de Cocoon, sino que tambi�n tendr�s el sentimiento de mantener tu trabajo claramente separado de la distribuci�n de Cocoon.

�La Soluci�n: Separar tu Trabajo mediante el uso de subsitemaps

Como Cocoon se ha dise�ado para un alta escalabilidad, hay un concepto de "divide y vencer�s" dentro del concepto de sitemap.

�Parte I; Usar las Posibilidades Existentes

Te voy a ense�ar un detalle justo en el medio del fichero $cocoon_root/sitemap.xmap de la distribuci�n original (cerca de la l�nea 860): Ah� podr�s encontrar el siguiente fragmento de c�digo (hemos eliminado los comentarios):

<map:pipeline>
  <map:match pattern="mount/*/**">
    <map:mount check-reload="yes" src="mount/{1}/" uri-prefix="mount/{1}"/>
  </map:match>
</map:pipeline>

Esta peque�a parte del sitemap nos permite separar limpiamente nuestro trabajo del resto de cocoon. �Qu� hace esto? Mira la definici�n pattern="mount/*/**" de la segunda l�nea. Este patr�n de correspondencia es interpretado por cocoon de esta forma:

• a - Cualquier URL que apunte a la aplicaci�n web Cocoon.
• b - seguida por un 'mount/'
• c - seguida por un nombre de carpeta arbitrario (el primer "*" del patr�n)
• d - seguido por una '/' (la "/" del patr�n)
• e - seguida por un path de profundidad arbitraria ("**" en el patr�n).

Cuando el int�rprete encuentra el caracter comod�n "*" o la secuencia "**" en el patr�n, actualmente resuelve el valor real en par�metros locales del sitemap, donde el primer caracter comod�n se coloca en el par�metro {1}, el segundo caracter comod�n se sit�a en el par�metro {2}, ...

Se aplican las siguientes reglas:

• Un �nico "*" se resuelve en cualquier secuencia de caracteres entre dos caracteres '/'.
• Un doble "**" se resuelve en cualquier secuencia de caracteres delimitada por una '/*' en el lado derecho, o una '*/' en el lado izquierdo.

Estas reglas abstractas se pueden entender mejor con el siguiente ejemplo. En �l aplicamos la URL (dada en la primera l�nea) al patr�n de correspondencia (en la segunda l�nea):

http://localhost:8080/cocoon/ mount/ work/index.xml   <-- URL
~~~~~~~~~~~a~~~~~~~~~~~~~~~~~ ~~b~~~ ~~c~d~e~~~~~~~ 
                              mount/   * / **         <-- patr�n
                                      {1}  {2}        <-- par�metros-del-sitemap

Aqu� Cocoon asocia el string "work" al par�metro {1} y el string "index.xml" al par�metro {2}. Estos par�metros se pueden utilizar libremente dentro de un pipeline, como hemos visto arriba. En ese caso s�lo hemos utilizado el {1} dento de la etiqueta <map:mount>.

Cocoon intentar� abrir un subsitemap dentro de la carpeta indicada por el atributo src de la etiqueta <map:mount>. En este ejemplo ser�a $cocoon_root/mount/{1}/ que se resuelve $cocoon_root/mount/work/ seg�n lo que hemos aprendido arriba.

Si echamos un vistazo al directorio $cocoon_root veremos que ya existe una carpeta llamada mount. Todo lo que tenemos que hacer ahora es crear una carpeta con el mismo nombre que el par�metro {1} ("work" en el ejemplo de arriba) dentro de la carpeta mount y empezar a trabajar dentro de ella. Ya est�mos listos para conectar nuestra carpeta work con cocoon:

�Parte II: Conectar nuestra Carpeta "work" con Cocoon

Cada vez que se accede a Cocoon con una URL de la forma http://localhost:8080/cocoon/mount/{tu_carpeta}/{path_de_profundidad_arbitraria}, buscar� dentro de la carpeta $cocoon_root/mount/{tu_carpeta} un fichero sitemap.xmap. Dentro del fichero $cocoon_root/mount/{tu_carpeta}/sitemap.xmap definiremos los componentes espec�ficos de nuestro proyecto, por ejemplo pipelines. Al principio de nuestro desarrollo este fichero ser� muy peque�o.

Asumamos que queremos servir un contenido XML que es serializado como salida HTML usando una transformaci�n XSL. Creo que este es el "caso de utilizaci�n" m�s sencillo para Cocoon. Asumimos que la transformaci�n XSLT est� en el fichero mytransform.xsl y que todos los ficheros que queremos servir terminan en .xml. La configuraci�n es bastante sencilla:

• Entra en tu carpeta de trabajo (work).
• Crea en ella un fichero sitemap.xmap con el siguiente contenido:

  
  <?xml version="1.0"?>
  <map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
  
    <map:components>
      <map:generators   default="file"/>
      <map:transformers default="xslt"/>
      <map:readers      default="resource"/>
      <map:serializers  default="html"/>
      <map:matchers default="wildcard"/>
    </map:components>
  
    <map:pipelines>
      <map:pipeline>
        <!-- xml files -->
        <map:match pattern="*.html">
          <map:generate src="{1}.xml"/>
          <map:transform src="mytransform.xsl"/>
          <map:serialize type="html"/>
        </map:match>
      </map:pipeline>
    </map:pipelines>
  </map:sitemap>
  
  

��Qu� hemos Conseguido?

Primero le hemos dicho a Cocoon que empiece una transformaci�n XSLT siempre que intentemos recuperar un fichero HTML desde la carpeta work, por ejemplo con la siguiene URL:

 
http://localhost:8080/cocoon/mount/work/index.html

conseguimos que Cocoon busque un fichero llamado index.xml dentro de la carpeta work. Luego ese fichero se transforma utilizando la transformaci�n XSLT almacenada en mytransform.xsl. Finalmente se serializa el resultado utilizando el serializador HTML. El resultado final es que se env�a al navegador un fichero HTML est�ndar.

Por favor, recuerda s�lo un punto importante: los patrones de correspondencia est�n totalmente separados de los nombres reales de los ficheros en tu carpeta. Por ejemplo, podr�amos elegir el patr�n *.xml en lugar *.html y dejar el resto del pipeline como est�. Con esto Cocoon enviar� de vuelta nuestro resultado en HTML, si encuentra la URL:

http://localhost:8080/cocoon/mount/work/index.xml

(como ves aqu�: aunque solicitamos el fichero index.xml, obtenemos un resultado en HTML!)

�Ap�ndice: ficheros de ejemplo

Un fichero index.xml que puedes poner en tu carpeta work:

<?xml version="1.0"?>
    <page>
      <title>Basic XML/XSL Transformation Example </title>
      <greeting>Hello World</greeting>
    </page>

Una hoja de estilo XSL que puedes utilizar como mytransform.xsl:

<?xml version="1.0"?>
   <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">

    <xsl:template match="page">
     <html>
      <head>
       <title><xsl:value-of select="title"/></title>
      </head>
      <body>
       <h1><xsl:value-of select="title"/></h1>
       <p><xsl:value-of select="greeting"/></p>
      </body>
     </html>
    </xsl:template>

   </xsl:stylesheet>