Development/Tutorials/Plasma4/ComicPlugin (es)

[esta traducción está en progreso]

Abstracto

Este tutorial describirá cómo crear tu propio plugin ("Agregar comics") para el plasmoid de Tira de cómic. Necesitas al menos KDE 4.2 para crear plugins.

En general, puedes crear plugins en cualquier lenguaje soportado por Kross, aunque este tutorial se focaliza en QtScript (JavaScript, ECMAScript), ya que es soportado por cualquier instalación de KDE.

No necesitas tener experiencia en QtScript para escribir plugins de comics, frecuentemente es suficiente adaptar plugins existentes. Pero en cualquier caso, http://www.w3schools.com/JS/default.asp (en inglés) es una buena referencia y tutorial para Javascript.

Ten en cuenta que no muestra todas las características soportadas, por el momento.

Tipos de comics

El motor de datos de comic soporta tres tipos de comics.

1. date (fecha)
2. number (número)
3. string (cadena)

Esa es la manera en que los comics se identifican, como "garfield:2000-01-01" para 'date' o "xkcd:100" para 'number'. 'string' podría ser cualquier cosa.

A veces el sitio web donde se publica tu comic no tiene una forma fácil de conseguir una fecha o un número para cada comic, o da uno que no ayuda a acceder a un comic específico. En ese caso deberías usar 'string'.

La idea es que el identificador debería ser suficiente para conseguir un comic específico, por ejemplo "xkcd:100". La primera parte dice qué plugin debe cargarse y la segunda parte le dice a tu plugin que comic cargar. Tu plugin no recibirá más información del motor de datos que eso.

Estructura del paquete

Los plugins de comic se proveen como paquetes que se pueden subir a www.kde-files.org y se pueden descargar directamente desde el plasmoid.

Primero, crea una carpeta donde vayas a trabajar. Necesitas una estructura así:

• ./metadata.desktop
• ./icon.png
• ./contents/code/main.es

Después, necesitas poner los archivos en un paquete ".comic", que es un archivo zip. Puedes hacer esto con el comando:

zip -r mi_comic.comic contents/code/main.es metadata.desktop

donde "mi_comic" es el nombre del comic que quieres agregar.

El archivo metadata.desktop

Cada plugin de comic necesita un archivo metadata.desktop como el siguiente:

[Desktop Entry]
Name=Mi Comic
Comment=Mi Comic
Type=Service
X-KDE-ServiceTypes=Plasma/Comic
Icon=icon.png

X-KDE-Library=plasma_comic_krossprovider
X-KDE-PluginInfo-Author=Tu nombre
X-KDE-PluginInfo-Email=Tu dirección de email
X-KDE-PluginInfo-Name=mi_comic
X-KDE-PluginInfo-Version=0.1
X-KDE-PluginInfo-Website=http://plasma.kde.org/
X-KDE-PluginInfo-License=GPLv2
X-KDE-PluginInfo-EnabledByDefault=true
X-KDE-PlasmaComicProvider-SuffixType=Date

En las líneas "Name" y "Comment", agrega el nombre del comic que quieres agregar. Aparecerá en la lista de comics con ese nombre (eso no es el diálogo de "Obtener cómics nuevos..."). También puedes poner el nombre del comic en varios idiomas. Por ejemplo:

Name=My Comic
Comment=My Comic
Name[es]=Mi Comic
Comment[es]=Mi Comic
Name[de]=Mein Comic
Comment[de]=Mein Comic

Sólo necesitas "Icon" si tienes un icono para tu comic -- como un favicon -- y lo quieres agregar. En este ejemplo, el archivo se llama "icon.png".

X-KDE-PluginInfo-Name es muy importante, ya que es el nombre de tu plugin. El motor de datos de comic usará este nombre para identificar qué plugin debe cargarse. Ese nombre tambpen se usa si pruebas tu plugin con plasmaengineexplorer. No se permiten espacios en el nombre.

X-KDE-PlasmaComicProvider-SuffixType es el tipo de comic, como se dijo en la sección anterior ('date', 'number', o 'string').

El código

En las primeras dos secciones mostraré qué funciones y objetos están disponibles. Si quieres, puedes saltear estas secciones y usarlas solo como referencia.

Funciones disponibles

Hay diferentes funciones que puedes usar o puedes (o tienes que) agregar:

function init()
comic.pageRequest(url, id)
function pageRetrieved(id, data, metadata)
comic.combine(image, position)

Además, hay algunas funciones relacionadas con el manejo de fechas, similares a QDate.

Por supuesto, puedes agregar otras funciones si las necesitas.

init()

El motor de datos llama a init(), por lo tanto debes incluirla. El motor solo cargará el plugin (y por lo tanto llamará a init()) si el comic que necesita no está en el caché.

comic.requestPage(url, id, metadata)

Pide al motor de datos que descargue url. También puedes especificar metadata (se explicará después), pero es opcional. id dice qué tipo de descarga es. Hay tres ids distintos:

• comic.Page
• comic.User
• comic.Image

Tanto comic.Page como comic.User están diseñados para descargar páginas web (solo texto, no datos binarios), mientras que comic.Image se usa para la imagen del comic. No importa demasiado si usas Page o User...

También puedes especificar metadata, como el "referrer". Fíjate en DESIGN.metadata (en inglés) qué datos están soportados.

var infos = {
             "accept": "text/html, image/jpeg, image/png, text/*, image/*, */*",
             "referrer": "www.example.com/index.html"
            }
comic.requestPage( "www.example.com/image.jpg", comic.image, info );
comic.requestPage( "www.example.com/image.jpg", comic.image ); //también funciona, no usa metadata

Si la descarga es exitosa, el motor de datos llamará la función pageRetrieved.

pageRetrieved(id, data)

pageRetrieved solo se llama si le pediste al motor de datos que descargue algo. data son los datos descargados, en un stream de bytes convertido a Unicode is the downloaded data in a byte stream converted to unicode (pero no siempre; ver comic.textCodec en [Objetos disponibles]) mientras que id define qué tipo de descarga fue. Puedes convertir el stream de bytes a un String si es necesario:

var dataString = data.toString();
var begin = dataString.indexOf( "test" ); //no funcionaría sin convertir

Aquí podrías buscar el URL del comic, el título, el autor, el identificador del siguiente comic, etc. Por lo que solo necesitas implementar esta función si tienes que buscar algo en una página HTML o si quieres modificar la imagen.

comic.combine(image, position)

TODO

Objetos disponibles

En esta sección se describen los objetos disponibles. Solo comic.identifier, y otras propiedades en algunos casos descritos luego, tienen un valor inicial.

comic.comicAuthor = "Randall Munroe";      //el autor o autores del comic
comic.websiteUrl = "http://xkcd.com/42/";  //la dirección a la página de este comic
comic.shopUrl = "http://store.xkcd.com/";  //si hay una tienda para el comic
comic.title = "Geico";                     //título del comic; también podría ser un capítulo, etc.
comic.additionalText = "David did this";   //texto adicional que se mostrará
comic.textCodec = "Windows-1251";          //Usa esto solo si el codec no se reconoce automáticamente! Así que prueba primero si funciona sin esto.
comic.isLeftToRight = false;               //true por defecto, usar solo si el comic no es de izquierda a derecha (agregado en 4.3)
comic.isTopToBottom = false;               //true por defecto, usar solo si el comic no es de arriba a abajo (agregado en 4.3)

Ver la documentación de Qt para una lista de codecs que puedes usar en comic.textCodec.