Cómo crear una extensión tipo ClipArt para Apache OpenOffice
y no pasarse 10 pueblos
Este va a ser el primero de los casos que vamos a estudiar, por no decir "destripar".
Lo primero que como alumno aventajado de SuperMan debes saber es que
|
Una extensión no es más que un conjunto de carpetas y archivos comprimidos en formato zip, al que se le ha cambiado la extensión .zip por .oxt |
Lástima que a diferencia de Batman no tenga un nombre típico para tí, estimad@ aprendiz. Así que no te llamaré Robin. Nunca he sido muy ingenioso para los nombres, así que te llamaré Lobezn@. Al menos, a tu pareja, le encantará.
Pues bien, Lobezn@, para aprender cómo está hecha una extensión lo mejor que puedes hacer es descargar una y destriparla. Dado que es un sencillo y simple archivo comprimido en formato zip, no te será difícil. Por ejemplo, puedes descargar uno cualquiera de los (en la actualidad, 18) cliparts que hemos creado desde open-office.es, y que puedes encontrar aquí: Blog de extensiones de open-office.es.
En este tutorial vamos a utilizar como base la extensión Caricaturas Gente 03 SVG.
Para descargarlo en tu equipo, seleccionando Guardar en lugar de Ejecutar cuando tu navegador te lo pregunte.
Vamos a analizar qué contiene cada uno de esos ingredientes necesarios para cocinar con éxito esta receta.
Los ingredientes
Crear una carpeta que contiene la extensión
El primer paso que tendrás que dar es sencillo. Crea una carpeta con el nombre que deseas dar a la extensión. En ella almacenaremos todos los archivos que se precisan para crear la extensión.
Un lugar recomendable puede ser el propio Escritorio, o la carpeta Mis Documentos, para que sea de fácil acceso.
Eso sí, el nombre de la carpeta debe empezar por una letra de la a a la z, y el resto del nombre puede contener letras, números y el signo de subrayado. Ni espacios ni ningún otro signo o símbolo deberás utilizar (tampoco la ñ o la ç), pues es muy probable que más tarde no puedas subir la extensión a la web oficial manteniendo el mismo nombre.
Si seguiste nuestro consejo y has descomprimido el clipart Caricaturas Gente 03 SVG] verás que todo el contenido de la extensión se encuentra dentro de la carpeta Caricaturas_Gente_03_SVG.
Crear un ClipArt con la Galería
En nuestra guía de Draw dispones de un ejemplo completo para crear tus propios diseños e integrarlos en un nuevo tema de la Galería. Visita Dibujando a escala en Draw. Si tu clipart lo componen imágenes tipo bitmap (.jpg, .png) o gráficos vectoriales (.svg) previamente creados te será aún más sencillo.
Si no conoces la Galería de OpenOffice aquí te la presentamos: Lobezn@, esta es la Galería de OpenOffice. Galería, este-a es Lobezn@.
En cualquier caso, para crear una extensión tipo ClipArt lo primero que necesitas es un conjunto de imágenes.
Así que ahora que ya os conocéis l@s dos, deberás crear un Nuevo tema en la Galería, con un nombre adecuado para el tema de tu clipart, y arrastrar dentro del tema las diferentes imágenes. Para ello puedes insertar las imágenes en un documento de Draw o de Writer, y arrastrarlas hasta la ventana de la Galería. Las imágenes pueden estar en formato .png, .jpg, .gif, o .svg, y es probable que soporte otros, pero no lo he probado. Pero no tienes por qué limitarte a crear un clipart de imágenes. La Galería admite también sonidos e incluso vídeos.
La ventaja de utilizar imágenes en formato .svg es que son redimensionables sin pérdida de calidad, y que su tamaño en bytes suele ser reducido, dado que se trata de imágenes vectoriales. La desventaja, es que algunas imágenes contienen datos que dejan a veces colgado a nuestra suite durante un buen rato, siendo en alguna ocasión necesario cerrarla a mano. Cuando esto ocurra, lo recomendable es prescindir de esa imagen.
Lo que sí deberás cuidar es el tamaño que alcanza tu colección de imágenes, pues más tarde hay que subir el proyecto a la web oficial de extensiones, y un tamaño excesivo puede ser un problema; a los usuarios, bajarla, también.
Una vez finalizado el clipart deberás acceder al lugar donde está almacenado para copiarlo dentro de la carpeta de nuestra extensión.
Tu clipart se almacena en la carpeta del perfil de usuario de Apache OpenOffice.
- Si eres usuario de Windows y no sabes como llegar hasta esta carpeta, dado que es una carpeta oculta del sistema, puedes consultar este sencillo truco
- Si eres usuario de GNU/Linux, desde tu aplicación para recorrer carpetas, activa Mostrar carpetas ocultas (generalmente Ctrl + H) y accede a la carpeta /home/<nombre del usuario>/.openoffice.org/3/user
- Si eres usuario de Mac... vaya, no tengo un mac, pero me han dicho que está en /Users/<nombre del usuario>/Library/Application Support/OpenOffice.org/3/user
En el interior de la carpeta gallery se encuentra tu clipart, formado por tres archivos. No uno, ni dos. Tres, de extensiones .sdg, .sdv y el más importante para nosotros, .thm
Podrás identificarlos fácilmente por su fecha y hora de creación, o también, por su nombre desde la propia Galería.
Tan sólo tendrás que hacer clic con el botón secundario sobre el título del tema en la lista de temas, y seleccionar Propiedades. Desde ahí puedes... vaya, la ruta es tan larga que no puedes leer el nombre, pero al menos puedes ver la fecha y hora de última modificación, lo que nos servirá para identificar nuestros tres archivos.
Conocido el nombre, o la fecha y hora de última modificación, busca en la carpeta el archivo con extensión .thm que coincida. Selecciona ahora los tres archivos con el mismo nombre, cópialos y pégalos en tu carpeta de la extensión, pero no a nivel raíz de la carpeta, sino en el interior de una carpeta que llamarás SI o SI gallery, todo en minúsculas. Es necesario que el nombre sea todo en minúsculas, y en inglés. Si no sabes inglés, con que se llame gallery será suficiente :)
La parte más divertida y creativa de nuestra extensión ya está hecha. Ahora necesitamos completar la parte informática. Tendrás que estar muy atent@, querid@ Lobezn@, pues un error en este punto, una coma mal puesta, borrar accidentalmente una sola letra o escribir una de más puede dar al traste con horas y horas de trabajo. Tienes que estar muy atent@ y ser muy cuidados@.
Una técnica recomendable es utilizar otra extensión ya creada, y sustituir en ella sólo aquellos valores que la convertirán en la nuestra. Como más cómodo te encuentres.
Contenido de description.xml
En la carpeta de nuestra extensión crearemos un nuevo archivo vacío que llamaremos SI o SI description.xml. Al igual que antes, todo en minúsculas y en inglés, aunque ya no repetiré el chiste. Este documento puede ser editado con cualquier editor de texto plano, como por ejemplo el bloc de notas (para los de Windows) o el gEdit (para los de GNU/Linux). Si eres de los primeros, deberías probar el Notepad++. No es conveniente editarlo con Writer, Word, o cualquier editor de textos con formato.
Este archivo contiene en su interior la definición de los elementos que se mostrarán al usuario al instalar la extensión en el administrador de extensiones.
Empieza por este texto, que puedes copiar y pegar en tu documento:
<?xml version="1.0" encoding="UTF-8"?> <description xmlns="http://openoffice.org/extensions/description/2006" xmlns:xlink="http://www.w3.org/1999/xlink">
y termina por este otro
</description>Se utiliza lo que se llama un lenguaje de marcas o lenguaje de etiquetas, de forma que:
- El nombre de cada comando viene encerrado entre un par de símbolos < >.
- Cada comando está formado por un par de etiquetas que encierran un valor, con este formato: <comando>valor</comando>
- Es posible que se utilice el formato reducido <comando valor />.
- Si deseamos agregar un comentario, deberemos encerrarlo entre los códigos <!-- y -->
Entre estos dos bloques se insertarán las diferentes secciones que definen la información mostrada al instalar la extensión.
Sección version
<!-- modify version value if appropirate --> <version value="1.0" />
Como ves, hemos insertado un comentario y un comando reducido, indicando que la versión es la 1.0
Sección license
Importante, pero opcional, es la información sobre la licencia. Veamos este ejemplo:
<!-- if license should be shown up at installation, add folder resources/ and include the license text there as license_en.txt--> <registration> <simple-license accept-by="user" default-license-id="en" suppress-on-update="true"> <license-text xlink:href="resources/license_en.txt" lang="en" license-id="en" /> </simple-license> <simple-license accept-by="user" default-license-id="es" suppress-on-update="true"> <license-text xlink:href="resources/license_es.txt" lang="es" license-id="es" /> </simple-license> </registration>
El código establece que la licencia debe ser aceptada por el usuario, solamente en el momento de la instalación, y no en caso de actualización por nueva versión de la extensión.
Además, se establecen documentos diferentes para distintos idiomas. Si tan sólo se establece el código para el idioma inglés (en) que se considera el idioma por defecto, el documento de licencia se mostrará a todos los usuarios, independientemente de su configuración. En el ejemplo se ha establecido un documento diferente para el idioma español (es), por lo que los usuarios con esta configuración en su suite verán el documento de licencia español en lugar del inglés. Más adelante en el apartado La licencia veremos cual es el contenido de los documentos que se han declarado.
El nombre de la carpeta en realidad puede ser cualquiera, siendo habitual utilizar una carpeta llamada license, en lugar de resources. El nombre de los documentos que contienen las licencias de texto también son de libre elección, si bien lo habitual es utilizar el nombre siguiendo la plantilla license_xx.txt, donde xx es el código del idioma. Cualquier cambio hay que declararlo correctamente en esta sección, por supuesto.
Sección publisher
Sigamos con otra sección: el nombre de quien publica la extensión. En este ejemplo haremos que se muestre un hiperenlace
<publisher> <name lang="en" xlink:href="http://open-office.es">http://open-office.es</name> <name lang="es" xlink:href="http://open-office.es">http://open-office.es</name> </publisher>
Pero podríamos haber utilizado un simple texto, como por ejemplo, tu alias:
<publisher> <name lang="en">Wolverine</name> <name lang="es">Lobezn@</name> </publisher>
En la extensión que hemos propuesto como ejemplo, hemos declarado un enlace a nuestro blog de extensiones.
Sección display-name
Declara el nombre de la extensión:
<!-- replace YOUR EXTENSION NAME by the right name of your extension --> <display-name> <name lang="en">People Cartoons 03 SVG</name> <name lang="es">Caricaturas Gente 03 SVG</name> </display-name>
Creo que no necesita comentarios.
Seccion extension-description
Declara el nombre y carpeta donde se encuentran los archivos con la descripción de nuestra extensión. Esta declaración es opcional, pero resulta muy adecuada, ya que se presentará tanto al instalar como una vez instalada, al hacer clic sobre ella en el administrador de extensiones.
En nuestro ejemplo hemos creado dos archivos, con las descripciones en castellano y en inglés, que hemos llamado respectivamente description_es.txt y description_es.txt. Ambos archivos los hemos almacenado en la carpeta description. Veremos el contenido de los archivos más adelante en el apartado La carpeta description.
<!-- content of the description file (in description folder) is shown in the extension manager. remember to modify it depending on your extension --> <extension-description> <src xlink:href="description/description_en.txt" lang="en" /> <src xlink:href="description/description_es.txt" lang="es" /> </extension-description>
Sección icon
Y para finalizar, la última sección declara el icono que representará a tu extensión. Debe ser una imagen en formato .png de tamaño 48x48 píxeles. Se mostrará en el administrador de extensiones. Su nombre, el que te guste; nosotros la hemos llamado icon.png, y la almacenamos a nivel raíz de la carpeta.
<!-- if you want an icon (48x48px) to show up at the extension manager, add its name here, if not, include this part in the comment --> <icon> <default xlink:href="icon.png" /> </icon>
Pues este paso ya está terminado. Verifica que todo es correcto, que no hay nada de más, ni nada de menos, y guárdalo en la carpeta de la extensión.
El icono
Como hemos comentado anteriormente, el icono debe ser una imagen en formato .png, de tamaño 48x48 píxeles. Es opcional, pero incluirlo hace que se muestre en el administrador de extensiones, lo que le confiere un mejor acabado.
Dado que (más adelante) generaremos una imagen de 150x150 píxeles para subir la extensión a la web oficial de extensiones, podemos crear el icono a partir de esa imagen.
El icono se puede almacenar en una subcarpeta cualquiera dentro de la carpeta de la extensión. En ese caso, habría que indicar en el archivo description.xml la ruta relativa hasta el icono.
Por ejemplo, si guardamos el icono en una carpeta llamada imagenes dentro de la extensión, la sección en description.xml quedaría así:
<icon> <default xlink:href="imagenes/icon.png" /> </icon>
Contenido de manifest.xml
Si el archivo description.xml declara las opciones que se presentarán al usuario al instalar la extensión, manifest.xml declara los archivos que definen qué nuevos elementos se agregarán a nuestro perfil personal en la instalación de AOO.
Muy importante: el archivo manifest.xml debe estar contenido en una carpeta llamada META-INF de forma obligatoria. El administrador de extensiones busca ese archivo en esa carpeta, y si no lo encuentra, se queda colgado o no instala correctamente la extensión.
|
|
El archivo manifest.xml debe estar obligatoriamente almacenado en una carpeta de nombre META-INF |
Cuando se instala una extensión se pueden agregar nuevos menús, opciones, barras de herramientas, carpetas agregadas o que se fusionan con existentes, etc. En nuestro caso tan sólo vamos a fusionar nuestra carpeta galery con la carpeta galery existente en nuestro perfil de usuario.
La información de qué carpetas se van a crear o a fusionar estará contenida en otro archivo, denominado Paths.xcu, que describimos más adelante; en manifest.xml debemos de indicar donde está almacenado ese archivo y de qué tipo de elemento se trata.
El contenido necesario para nuestra extensión es el que mostramos a continuación:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE manifest:manifest PUBLIC "-//OpenOffice.org//DTD Manifest 1.0//EN" "Manifest.dtd"> <manifest:manifest xmlns:manifest="http://openoffice.org/2001/manifest"> <manifest:file-entry manifest:media-type="application/vnd.sun.star.configuration-data" manifest:full-path ="Paths.xcu"/> </manifest:manifest>
Se establece una única sección llamada manifest:manifest, que contiene un comando reducido manifest:file-entry que contiene dos valores:
- cómo se llama y dónde está el archivo que contiene la información sobre el elemento mediante manifest:full-path, y
- qué tipo de elemento se va a crear, mediante manifest:media-type
En nuestro caso hemos almacenado el archivo en la carpeta a nivel raiz, y lo hemos llamado Paths.xcu.
Más adelante, en otros ejemplos de extensiones, veremos cómo se agregan menús, opciones y barras de herramientas.
Contenido de Paths.xcu
Este archivo se suele situar a nivel raiz en la carpeta de la extensión, pero realmente puede estar almacenado en cualquier subcarpeta, y no es obligatorio utilizar este nombre, pero sí usar la extensión xcu. El nombre de Paths es porque lo que define este archivo es una modificación a realizar en las carpetas del perfil del usuario, en inglés Paths. Por ello, lo mejor es dejarlo tal y como está, ya que también es lo más habitual. En caso de cambiar su nombre y localización, deberemos declararlo correctamente en el archivo manifest.xlm.
Veamos su contenido.
<?xml version='1.0' encoding='UTF-8'?> <oor:component-data oor:package="org.openoffice.Office" oor:name="Paths" xmlns:install="http://openoffice.org/2004/installation" xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <node oor:name="Paths"> <node oor:name="Gallery" oor:op="fuse"> <node oor:name="InternalPaths"> <node oor:name="%origin%/gallery" oor:op="fuse"/> </node> </node> </node> </oor:component-data>
A la segunda línea le hemos agregado algunos saltos de línea para que resulte más legible, cosa que se admite en este tipo de archivos. Lo único significativo es que declaramos que vamos a hacer una modificación en las rutas del perfil del usuario Paths, y que AOO debe tomar la subcarpeta galery de nuestra extensión y fundirla fuse con la existente en el perfil.
Es muy importante respetar las mayúsculas/minúsculas, pues, por ejemplo, donde vemos Gallery se refiere a una propiedad del código interno de AOO que no podemos modificar, y donde vemos gallery se refiere a la carpeta del usuario donde residen los temas de la Galería propios del usuario, carpeta cuyo nombre tampoco podemos modificar.
La carpeta description
En ella incluimos uno o más archivos que contienen la descripción de la extensión que se presenta en el momento de la instalación y, posteriormente, al hacer clic sobre la entrada en el administrador de extensiones; cada uno de estos archivos contiene la descripción en un idioma distinto. Es aconsejable que contengan una descripción no muy extensa.
Tanto el nombre de la carpeta como el de los archivos es completamente libre, pero para éstos se recomienda utilizar la plantilla description_xx.txt donde xx es el código del idioma. Sean cuales sean los nombres elegidos, deben estar correctamente declarados en la sección <extension-description> del archivo description.xml.
Si se incluyen en el texto carácteres acentuados, eñes o cedillas es recomendable almacenar el archivo codificado en UTF8 para que se muestren correctamente en el administrador de extensiones. Por ejemplo, en Notepad++ se puede hacer desde el menú Codificación. Si utilizas gEdit, puedes hacerlo desde Guardar como... > Codificación de caracteres.
En nuestro ejemplo hemos incluido dos archivos, description_en.txt y description_es.txt, cuyo contenido reproducimos a continuación:
75 images in SVG format to include in your documents All images were obtained from http://openclipart.org All images are licensed CC0 PD. The extension is licensed Apache 2. |
Contenido de description_en.txt |
75 imágenes en formato SVG para incluir en tus documentos Todas las imágenes fueron obtenidas de http://openclipart.org y están bajo licencia CC0 PD La extensión está bajo licencia Apache 2. |
Contenido de description_es.txt |
Este es el aspecto que presenta la descripción en el administrador de extensiones recien instalada:
La licencia
El deseo de la Apache Software Foundation es que todas las extensiones que se editen para Apache OpenOffice lo hagan con el mismo tipo de licencia que posee la suite, la licencia Apache 2. Pero no todos los desarrolladores ni usuarios están de acuerdo con esa política, y crean extensiones con otros tipos de licencia, como por ejemplo, la licencia GNU GPL de la Free Software Foundation.
Sea cual fuera, la web oficial de Extensiones está albergada en los servidores de sourceforge.net, una forja de software que admite proyectos de varios tipos de licencias, entre ellas las dos anteriormente mencionadas.
Toda extensión debería incluir información sobre el tipo de licencia con la que es compartida en la comunidad.
Por ello, deberías:
- Incluir el tipo de licencia en el archivo en el que indicas la descripción de tu extensión, y que se declara en la sección <extension-description> del archivo description.xml.
- Incluir un archivo con el texto de la licencia original en inglés, y declararlo en la sección <registration> del archivo description.xml, o...
- Incluir un archivo con el información del tipo de licencia y un enlace al texto original en inglés, y declararlo en la sección <registration> del archivo description.xml
En cualquier caso, las licencias suelen indicar que es obligatorio incluir una copia del texto original en inglés que acompañe al soft licenciado, en este caso, a tu extensión.
Por otra parte, es muy conveniente declarar estos archivos en description.xml ya que obligan al usuario a leer y aceptar los términos de la licencia para que se instale la extensión.
Si deseas incluir un texto traducido en Español va a ser complicado. De hecho, las traducciones que he encontrado dicen que "no es la licencia oficial" y que "en caso de duda, hay que remitirse al texto original en inglés". Parece ser que traducir el espíritu legal de las licencias es imposible. En este enlace puedes encontrar una traducción "no oficial" de la licencia GNU GPL.
Como solución rápida, puedes hacer como nosotros: incluir un enlace al texto oficial de la licencia:
License All images were obtained from http://openclipart.org All images are licensed CC0 PD (http://creativecommons.org/publicdomain/zero/1.0/). Copyright 2013 http://open-office.es Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.