Cómo crear una extensión - Aplicación a la creación de un tema de Galería

TDF LibreOffice en español Document Liberation Project Blogs comunitarios Weblate Nextcloud Redmine Preguntas y respuestas Donar

Pasos a seguir

Una extensión permite añadir funciones a LibO. Las extensiones que se descargan con más frecuencia son :

añadir funciones
añadir temas a la Galería

Sea cual sea la extensión que quieras crear, los pasos a seguir son los mismos:

reunir los archivos en un directorio
configurar los archivos de descripción
crear la extensión
distribuir la extensión

Aquí vamos a mostrarle cómo construir una extensión para añadir imágenes a la Galería. Un ejemplo minimalista (sin imágenes) está disponible aquí.

Preparación de imágenes

Para distribuir imágenes que desea utilizar regularmente en LibO, la solución más sencilla es construir una extensión que añadirá uno o más temas a la Galería que contengan estas imágenes. Estas imágenes pueden estar en diferentes formatos:

imagen de puntos a partir de un archivo PNG, JPEG, GIF, BMP, TIFF, etc.
imágenes vectoriales construidas a partir de objetos de dibujo de Draw: rectángulos, elipses, segmentos, etc.

Por lo tanto, las imágenes deben agruparse en un tema:

haga clic en la pestaña Galería del panel lateral
haga clic en el botón Nuevo tema
escriba el nombre y la ubicación (será necesario para encontrar el archivo)
haga clic en OK

Ahora tienes un nuevo tema vacío. Añade las imágenes que quieras poner en él. Para los archivos de imagen de puntos, no es aconsejable utilizar el método de añadirlos directamente al tema:

botón derecho del ratón sobre el nombre del tema > Propiedades, pestaña Archivos,
Botón Buscar archivos para examinar el disco
Botón Añadir

Utilizando este método, sólo se añade un enlace al tema, y esto complicará la inserción en la extensión. Por lo tanto, es mejor importar el archivo utilizando el menú Insertar > Imagen en un documento Draw, por ejemplo, y luego añadir la imagen al tema de la misma manera que para una imagen vectorial:

ajuste el zoom y las barras de desplazamiento para ver toda la imagen que desea insertar
mantenga pulsada la imagen sin moverla. Al cabo de unos segundos, LibO habrá guardado la imagen: el borde habrá cambiado ligeramente
sin soltar, arrastre hacia el tema.

Si este paso falla (la imagen se mueve al dibujo), necesitas repetir el paso anterior: probablemente no esperaste lo suficiente. Para comprobar que todas tus imágenes están en el tema, haz clic en cada una y deberías ver un nombre como dd2954. Si aparece una ruta, significa que la imagen no está realmente en el tema, sino que sólo hay un enlace a un archivo. Esto complicará mucho la construcción de la extensión. En este caso, arrastre la imagen desde el tema a un documento Draw y, a continuación, vuelva a insertarla en el tema como antes.

Una vez insertadas todas las imágenes que desee, puede darles un nombre:

haga clic con el botón derecho en la imagen del tema > Título

Este título es puramente informativo para el usuario, no necesita ser único.

A continuación, vaya a la ubicación que encontró al crear el tema y recupere los 3 archivos que componen cada tema: sgxxxx.sdg, sgxxxx.sdv y sgxxxx.thm. xxxx es el número del tema. Este número debe ser único en el mismo directorio. Como la extensión creará sus propios directorios, no es necesario que el número sea único para todos los temas de un usuario.

Construcción de archivos de configuración

Consiste en un único archivo con la extensión .OXT. Como todos los archivos con formato OpenDocument, es un archivo comprimido. La mejor manera de construir una extensión es obtener una extensión del mismo tipo que la que desea construir. Por ejemplo, para añadir un tema de Galería, recupere Galería de Piezas de Puzzle del sitio de extensiones. No instale la extensión directamente, pero guarde el archivo. Descomprima el archivo en un directorio nuevo (si es necesario, cambie la extensión del archivo a .ZIP). En este directorio encontrará todos los archivos de configuración de la extensión. Debe identificar lo que es esencial para que la extensión funcione y lo que añade la extensión. Lo mínimo está contenido en esta extensión.

Contenido de una extensión

Directorio `Gallery`

Este directorio contiene los archivos del tema. Tenemos que borrar todo el contenido y sustituirlo por nuestros archivos sgxxxx.sdg, sgxxxx.sdv y sgxxxx.thm.

Directorio `META-INF`

Este directorio está presente en todas las extensiones y es necesario para instalar la extensión. Contiene el archivo manifest.xml que declara los archivos de la extensión. A priori no es necesario modificarlo, salvo para corregir alguna ruta.

<?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>

Esta es la declaración del archivo Paths.xcu como archivo de configuración. Para asegurarse de que su extensión es compatible con todos los sistemas operativos, por favor asegúrese de que los nombres de archivo son sensibles a mayúsculas y minúsculas.

Directorio `description`

Este directorio no es obligatorio, pero contiene archivos de texto que describen la extensión en diferentes idiomas. Este texto se utiliza en el gestor de extensiones para describir la extensión. Si no hay ningún archivo en el idioma de la interfaz, se utiliza el archivo en inglés. También puede proporcionar un único archivo de descripción.

Directorio `licencias`

Este directorio no es obligatorio, pero contiene los archivos de texto para las licencias en diferentes idiomas. Si no tiene previsto validar una licencia al instalar la extensión, este directorio no es necesario. Sin embargo, es aconsejable disponer de un archivo de texto que indique la licencia que se utilizará en la extensión, por ejemplo haciendo referencia a las licencias GNU-GPL, LGPL, PDL, etc.

Otros directorios

Pueden existir otros directorios, pero no son necesarios para el funcionamiento y la instalación de la extensión.

Otros archivos

En la raíz del archivo :

cualquier descripción o archivo de licencia. No hay necesidad de poner estos archivos en directorios separados. Es más limpio, eso es todo.
Archivo description.xml: este es un archivo muy importante, y entraremos en más detalle sobre él a continuación
Archivo paths.xcu: este archivo declara la función de la extensión y cómo instalarla. Así, para una extensión de Galería:

<?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>

No hay nada que cambiar en él.

un archivo de imagen: se trata de una imagen de 42x42 puntos en formato PNG que se mostrará en el gestor de extensiones.

Archivo `Description.xml`

Este es el archivo que contendrá toda la información que desee personalizar. Debes tener cuidado de rellenarlo con los aspectos específicos de tu extensión: nombres de archivos (! mayúsculas/minúsculas), si se utiliza o no una característica, etc.

La página wiki (en inglés) https://wiki.openoffice.org/wiki/Documentation/DevGuide/Extensions/Example describe los distintos elementos que la componen. Echemos un vistazo a los elementos principales.

Estructura

El archivo comienza con una cabecera:

<?xml version="1.0" encoding="UTF-8"?>
<description xmlns="http://openoffice.org/extensions/description/2006" xmlns:d="http://openoffice.org/extensions/description/2006"
    xmlns:xlink="http://www.w3.org/1999/xlink">

y debe terminar con una etiqueta end

</description>

En medio, hay una serie de entradas del tipo:

<palabra-clave value="valor de la palabra clave" />

o

<palabra-clave>
    <sub-entrada-de-palabra-clave>
</palabra-clave>

Entre las entradas, algunas son obligatorias otras opcionales.

Identificador

Este identificador debe ser único en todo el mundo. Por eso recomendamos utilizar una cadena de caracteres en minúsculas, en orden inverso al dominio. Por ejemplo:

es.mi_dominio.mi_nombre.mi_extension

Así se utiliza en description.xml:

<identificador value="es.mi_dominio.mi_nombre.mi_extension" />

Número de versión

Si desea beneficiarse del sistema de actualización automática de extensiones, es importante rellenar esta sección. A priori, existen 3 niveles de numeración: mayor, menor, micro.

<version value="1.0.2" />

El número de versión de la extensión, gestionado por el desarrollador de la extensión, no debe confundirse con el número de versión de LibO.

Dependencias

Se debe indicar el número de versión de OOo/LibO a partir del cual la extensión es funcional.

<dependencies>
    <OpenOffice.org-minimal-version value="2.0" d:name="OpenOffice.org 2.0"/>
</dependencies>

Para las extensiones que utilizan características específicas disponibles sólo a partir de la versión 3.5, LibreOffice introduce un campo LibreOffice-minimal-version (véase la página Wiki correspondiente).

Ejemplo de uso:

<description 
     xmlns="http://openoffice.org/extensions/description/2006" 
     xmlns:d="http://openoffice.org/extensions/description/2006" 
     xmlns:l="http://libreoffice.org/extensions/description/2011" 
     xmlns:xlink="http://www.w3.org/1999/xlink"> 
    <dependencies> 
        <l:LibreOffice-minimal-version value="3.5" d:name="LibreOffice 3.5" /> 
    </dependencies> 
</description>

Plataformas compatibles

Si la extensión es independiente de la plataforma (que es el caso de un tema de Galería), lo especificamos así:

<platform value="all" />

En caso contrario, damos una lista:

<platform value="windows_x86" />

Nombre mostrado

El nombre mostrado en el gestor de extensiones se declara de la siguiente forma:

<display-name>
    <name lang="en">Gallery of danger signs</name>
    <name lang="fr">Galerie des symboles de dangers</name>
    <name lang="es">Galería de símbolos de peligro</name>
    <name lang="de">Gallery von Gefahrzeichen</name>
</display-name>

Imagen

La imagen utilizada en el gestor de extensiones se declara de la siguiente manera:

<icon>
    <default xlink:href="feu42.png" />
</icon>

Presta atención a la ubicación del archivo si lo has puesto en un subdirectorio, y presta atención a mayúsculas/minúsculas. La imagen debe ser de 42x42 para que no se distorsione.

Puedes definir otra imagen para interfaces definidas en alto contraste (deficientes visuales):

<icon>
    <default xlink:href="images/icon.png" />
    <high-contrast xlink:href="images/icon_hc.png" />
</icon>

Descripción

El texto de descripción que se mostrará en el gestor de extensiones, debe guardarse en un archivo (ver más arriba):

<extension-description>
    <src xlink:href="description/description_en.txt" lang="en" />
    <src xlink:href="description/description_fr.txt" lang="fr" />
    <src xlink:href="description/description_es.txt" lang="es" />
    <src xlink:href="description/description_de.txt" lang="de" />
</extension-description>

Los archivos deben estar en formato UTF-8.

Otra información

Hay otras secciones disponibles, pero no son imprescindibles:

validación de una licencia :

<registration>
    <simple-license accept-by="admin" suppress-on-update="true" >
        <license-text xlink:href="registration/license_de-DE.txt" lang="de-DE" />
        <license-text xlink:href="registration/license_en-GB.txt" lang="en-GB" />
        <license-text xlink:href="registration/license_en-NZ.txt" lang="en-NZ" />
        <license-text xlink:href="registration/license_en-US.txt" lang="en-US" />
    </simple-license>
</registration>

Si el campo accept-by ha sido rellenado por el admin, entonces será posible instalar la extensión para todos los usuarios. Si quieres que cada usuario valide la licencia, el campo debe ser rellenado con user.

Crear la extensión

Selecciona todos los archivos y directorios que componen tu extensión y crea un archivo ZIP a partir de ellos
Cambia la extensión del archivo ZIP a OXT
Ya está. Su extensión está lista para ser distribuida.

Este procedimiento rápido no crea un archivo muy limpio. Le recomendamos que siga este procedimiento, que crea un archivo válido en formato OpenDocument.

Distribuir la extensión

Sube tu extensión al sitio oficial de intercambio de extensiones https://extensions.libreoffice.org/ para que todo el mundo pueda beneficiarse de ella.

No olvides que LibO debe reiniciarse completamente (incluido el inicio rápido) para que la extensión se tenga en cuenta.