Development/Tutorials/Plasma4/ComicPlugin (es): Difference between revisions

    From KDE TechBase
    (Translated explanation of requestPage)
    (translate pageRetrieved)
    Line 120: Line 120:


    Si la descarga es exitosa, el motor de datos llamará la función pageRetrieved.
    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'':
    <code javascript>
    var dataString = data.toString();
    var begin = dataString.indexOf( "test" ); //no funcionaría sin convertir
    </code>
    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.

    Revision as of 03:31, 31 October 2009


    Development/Tutorials/Plasma/ComicPlugin


    [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.