Development/Tutorials/Plasma4/ComicPlugin

Note: this tutorial is not finished yet

Abstract

This tutorial will describe how to create your own plugin ("add comics") for the comic plasmoid. You need at least KDE 4.2 to be able to create plugins.

In general you can create plugins in any language supported by Kross, though this tutorial will focus on QtScript (JavaScript, ECMAScript), as this is supported by any KDE installation out of the box.

You do not have to be experienced in QtScript to be able to write comic plugins, often adapting existing plugins is enough. But in any case http://www.w3schools.com/JS/default.asp is a good reference and tutorial for javascript.

Keep in mind that not all supported features are discussed here at the moment.

Type of comics

There are three different types of comics that are supported by the comic dataengine.

1. date
2. number
3. string

That is the way the comics are identified, like "garfield:2000-01-01" or "xkcd:100", string can be anything.

Sometimes the website your comic is published on neither have an easy way to get a date or a number to a comic strip or that would not help to access the strip, in that case you should use string.

The idea of this is that the type should be enough to get the comic e.g. "xkcd:100". The first part tells what plugin should be loaded and the last part tells your plugin what comic strip should be loaded. Your plugin won't get more information from the dataengine on the request than that.

Package Structure

The comic plugins are provided as packages that can be uploaded to www.kde-files.org and easily downloaded from that place directly from the applet.

First create a folder you want to work in. Than you need a structure like the following:

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

Later you need to zip the files to a ".comic"-package, you can do that with e.g.

zip -r my_comic.comic contents/code/main.es metadata.desktop icon.png

where "my_comic" is the name of the comic you want to add.

The metadata.desktop file

Every comic plugin needs a metadata.desktop file like the following:

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

X-KDE-Library=plasma_comic_krossprovider X-KDE-PluginInfo-Author=Your Name X-KDE-PluginInfo-Email=Your email-adress X-KDE-PluginInfo-Name=my_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 In the "Name" and "Comment" section add the name of the comic you want to add. It will show up in the comic list (that is not the "Get New Comics..."-dialog) under that name. You could also translate the name of the comic to different languages e.g.

Name[de]=Mein Comic Comment[de]=Mein Comic

You only need "Icon" if you have an icon for your comic -- like a favicon -- that you want to add. Here it is called "icon.png"

X-KDE-PluginInfo-Name is very important, as that is the name of your plugin. The comic dataengine will use this name to identify what comic plugin should be loaded. You need that if you test your plugin with the plasmaengineexplorer. There is no white-space allowed in the name.

X-KDE-PlasmaComicProvider-SuffixType is the type of the comic as discussed the section above.

The Code

In the first two sections I am discussing what functions and objects are available, if you want skip these sections and use them only as reference if needed.

Available functions

There are different functions that you can use or can (have to) add:

function init() comic.pageRequest(url, id) function pageRetrieved(id, data)

You can in fact add other functions if you need them.

init()

init() is being called by the dataengine, so you need to include it. The dataengine will only call your plugin and thus init() if the asked for comic strip has not been cached.

pageRequest(url, id)

Ask the dataengine to download url for you. id specifies of what type the download is. There are three different ids:

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

Both comic.Page and comic.User are intended to be used for downloading web-pages (so only text) -- it is not really important which one you use -- while comic.Image is used for the actual comic image.

If the download was successful the dataengine will call pageRetrieved.

pageRetrieved(id, data)

pageRetrieved is only called if you asked the dataengine to download something for you. data is the downloaded data in a byte stream converted to unicode, while id defines what data has been downloaded.

Here you could search in the data for the url to the comic strip, the title of the comic, the comic's author, the next identifier etc. So you only need to implement that function if you want to find something in data or if you want to modify the image.

Available objects

In this section all (NOT YET) available objects that you can assign something are listed and described. Only comic.identifier and some other identifiers in special cases -- as discussed below -- have something assigned to them initially.

comic.comicAuthor = "Randall Munroe"; //the author or authors of the comic strip comic.websiteUrl = "http://xkcd.com/42/"; //the address to the page where the strip is comic.shopUrl = "http://store.xkcd.com/"; //if there is a shop for the comic comic.title = "Geico"; //the title of the comic strip, can be also the chapter etc. comic.additionalText = "David did this"; //additional text, that will be shown as tooltip in the comic applet. comic.textCodec = "Windows-1251"; //Only set the codec of the web content if it is not automatically recognized! So test first if it works without setting it.

Identifier

There are five "identifier" objects, that react differently depending on the type of the comic.

comic.identifier //the identifier of the recent comic strip comic.firstIdentifier //the first comic strip e.g. number 1 comic.lastIdentifier //the last (most recent) comic strip e.g. number 42 comic.previousIdentifier //the previous identifier of the current strip e.g. number 40 comic.nextIdentifier //the next identifier of the current strip e.g. 41

comic.identifier is the identifier the dataengine is being asked for, so it is already set, though you can assign something different to it if needed.

If there is a nextIdentifier then the dataengine will cache the comic strip, it does not need to be downloaded again in the future.

date

comic.identifier will always be an actual date that exists, if no exact date has been specified by the caller of the dataengine it will be today.

comic.firstIdentifier //has to be manually specified comic.lastIdentifier //if not specified will be today

If you are assigning something to comic.lastIdentifier, then comic.identifier will be reassigned that day automatically, but only if comic.identifier was a day after comic.lastIdentifier e.g.:

comic.identifier = date.fromString("2009-01-12"); print(comic.identifier); //2009-01-12 comic.lastIdentifier = date.fromString("2009-01-10"); print(comic.identifier); //now it would be 2009-01-10

comic.lastIdentifier = date.fromString("2009-02-01"); print(comic.identifier); //still 2009-01-10 In any case comic.identifier will be in the specified range.

If you do not set both (!) comic.previousIdentifier and comic.nextIdentifier then they will be set automatically according to this rules:

• comic.previousIdentifier = comic.identifier - 1 day;
• comic.previousIdentifier never will be a day before comic.firstIdentifier
• comic.nextIdentifier = comic.identifier + 1 day;
• comic.nextIdentifier never will be a day after comic.lastIdentifier

You should set the identifiers yourself if the comic is _not_ end-to-end e.g. 2009-01-12, 2009-01-14, 2009-02-01, ... If you are not sure also set the identifiers yourself.

number

comic.identifier will either be a specific number, or if no number has been specified by the caller of the dataengine it will be "0". As a result of that you can not have a comic that is identified by number "0", if there would be one you have to shift everything see http://kde-files.org/content/show.php/Digital+Purgatory+(en)?content=98222 for an example)

comic.firstIdentifier //if not specified will be "1" comic.lastIdentifier //has to be manually specified

If comic.identifier is 0 and you assigning something to comic.lastIdentifier, then comic.identifier will be reassigned that number automatically e.g.:

comic.identifier = 0; print(comic.identifier); //0 comic.lastIdentifier = 42; print(comic.identifier); //now it would be 42

comic.lastIdentifier = 100; print(comic.identifier); //still 42 In any case comic.identifier will be in the specified range.

If you do not set both (!) comic.previousIdentifier and comic.nextIdentifier then they will be set automatically according to this rules:

• comic.previousIdentifier = comic.identifier - 1;
• comic.previousIdentifier never will be smaller than comic.firstIdentifier
• comic.nextIdentifier = comic.identifier + 1;
• comic.nextIdentifier never will be larger than comic.lastIdentifier

You should set the identifiers yourself if the comic is _not_ end-to-end e.g. 1,4,5,9 ... If you are not sure also set the identifiers yourself.

string

Here you have to set everything you want to use yourself, nothing is set automatically. comic.identifier will either be a specific string, or if no string has been specified by the caller of the dataengine it will be an empty string (length = 0).

Examples

In this section there are some working examples -- for every type of comic one -- that should give you more insight of what comic plugins look like. You can look at other examples by downloading comic plugins either directly from kde-files.org or by installing further comics by using the "Get New Comics..."-dialog, then you find the installed comics and their code at

~./kde4/share/apps/plasma/comics/ # maybe ".kde" in your case

number

This example shows the implementation of the comic plugin for xkcd.com /*

*   Copyright (C) 2007 Tobias Koenig <[email protected]>
*   Copyright (C) 2009 Matthias Fuchs <[email protected]>
*
*   This program is free software; you can redistribute it and/or modify
*   it under the terms of the GNU Library General Public License version 2 as
*   published by the Free Software Foundation
*
*   This program is distributed in the hope that it will be useful,
*   but WITHOUT ANY WARRANTY; without even the implied warranty of
*   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
*   GNU General Public License for more details
*
*   You should have received a copy of the GNU Library General Public
*   License along with this program; if not, write to the
*   Free Software Foundation, Inc.,
*   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
*/

function init() {

   comic.comicAuthor = "Randall Munroe";
   comic.websiteUrl = "http://xkcd.com/";
   comic.shopUrl = "http://store.xkcd.com/";

   comic.requestPage(comic.websiteUrl, comic.User);

}

function pageRetrieved(id, data) {

   //find the most recent strip
   if (id == comic.User) {
       var re = new RegExp("Permanent link to this comic: http://xkcd.com/(\\d+)/");
       var match = re.exec(data);
       if ( match != null ) {
           comic.lastIdentifier = match[1];
           comic.websiteUrl += comic.identifier + "/";
           comic.requestPage(comic.websiteUrl, comic.Page);
       } else {
           comic.error();
       }
   }
   if (id == comic.Page) {
       var re = new RegExp("<img src=\"(http://imgs.xkcd.com/comics/[^\"]+)\"");
       var match = re.exec(data);
       if (match != null) {
           comic.requestPage(match[1], comic.Image);
       } else {
           comic.error();
           return;
       }

       //find the tooltip and the strip title of the comic
       re = new RegExp("src=\"http://imgs.xkcd.com/comics/.+\" title=\"([^\"]+)\" alt=\"([^\"]+)\"");
       match = re.exec(data);
       if (match != null) {
           comic.additionalText = match[1];
           comic.title = match[2];
       }
   }

}

string

This example shows the implementation of the Help Desk comic plugin.

/***************************************************************************

*   Copyright (C) 2008 Matthias Fuchs <[email protected]>                     *
*                                                                         *
*   This program is free software; you can redistribute it and/or modify  *
*   it under the terms of the GNU General Public License as published by  *
*   the Free Software Foundation; either version 2 of the License, or     *
*   (at your option) any later version.                                   *
*                                                                         *
*   This program is distributed in the hope that it will be useful,       *
*   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
*   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
*   GNU General Public License for more details.                          *
*                                                                         *
*   You should have received a copy of the GNU General Public License     *
*   along with this program; if not, write to the                         *
*   Free Software Foundation, Inc.,                                       *
*   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA .        *
***************************************************************************/

function init() {

   comic.comicAuthor = "Christopher Wright";
   comic.firstIdentifier = "1996/03/alex-loss-words";
   comic.websiteUrl = "http://www.ubersoft.net/comic/hd/";
   comic.shopUrl = "http://www.cafepress.com/evisceratistore";

   //cehck if the comic.identifier is empty, there are other ways as well like checking its length
   if (comic.identifier != new String()) {
       comic.websiteUrl += comic.identifier;
       comic.requestPage(comic.websiteUrl, comic.Page);
   } else {
       comic.requestPage(comic.websiteUrl + comic.firstIdentifier, comic.User);
   }

}

function pageRetrieved(id, data) {

   //find the most recent comic
   if (id == comic.User) {
       var re = new RegExp("<a href=\"/comic/hd/([^\"]+)\">last");
       var match = re.exec(data);
       if (match != null) {
           comic.lastIdentifier = match[1];
           comic.identifier = comic.lastIdentifier;
           comic.websiteUrl += comic.identifier;
           comic.requestPage(comic.websiteUrl, comic.Page);
       } else {
           comic.error();
       }
   }
   //get the comic image and all other available information
   if (id == comic.Page) {
       //here the title of the strip is spread across two places on the website
       var re = new RegExp("<a href=\"/comic/hd/storyline/[^\"]+\" rel=\"tag\" title=\"\">([^<]+)</a>");
       var match = re.exec(data);
       if (match != null) {
           comic.title = match[1];
       }

       //getting the image and the second part of the title
       re = new RegExp("<img src=\"(http://www\\.ubersoft\\.net/files/comics/hd/[^\"]+)\" alt=\"[^\"]*\" title=\"([^\"]*)");
       match = re.exec(data);
       if (match != null) {
           comic.title += (comic.title.length && match[2].length) ? ": " + match[2] : match[2];
           comic.requestPage(match[1], comic.Image);
       } else {
           comic.error();
           return;
       }

       //getting the previous identifier
       re = new RegExp("<a href=\"/comic/hd/([^\"]+)\">. previous</a>");
       match = re.exec(data);
       if (match != null) {
           comic.previousIdentifier = match[1];
       }

       //getting the next identifier
       re = new RegExp("<a href=\"/comic/hd/([^\"]+)\">next .</a>");
       match = re.exec(data);
       if (match != null) {
           comic.nextIdentifier = match[1];
       }
   }

}

Testing the plugin

To test the plugin you need to install it first:

plasmapkg -t comic -i my_comic.comic

If your comic does not show up in the comic list you have to type

kbuildsyoca4

and then it should be there. That will install the plugin to

~/.kde4/share/apps/plasma/comics/my_comic # maybe ".kde" in your case

Now best is you directly work on

~/.kde4/share/apps/plasma/comics/my_comic/contents/code/main.es

as you do not have to have reinstall the plugin if you change something. If you are finished and changed something on the main.es file simply store the main.es in your original folder and use the zip-command mentioned above to update the package.

To test your plugin type

plasmoidviewer comic

and choose your plugin. That way you will see debug-output. Alternatively you could use the plasmaengineexplorer

plasmaengineexplorer

there choose comic and type in your comic identifier e.g.

garfield:

or

garfield:2000-01-01

All the comic strips that have a next identifier will be cached at

~/.kde4/share/apps/plasma_engine_comic/ # maybe ".kde" in your case

so if you change the applet it might be good to clean the cache before further testing by

cd ~/.kde4/share/apps/plasma_engine_comic/ # maybe ".kde" in your case
rm my_comic*

Debugging the plugin

Often it happens that your plugin won't work the first try and the following debuggin can be painful as there is not that much output unless you use some tricks.

Add print-statements in your main.es file to see what the values of different variables are and where your plugin stops working. Here are some examples:

function init() {

   ...
   var url = "XY" + comic.identifier;
   print("***url: " + url");
   ...

} function pageRetrieved(id, data) {

   if ( id == comic.page ) {
       print("****in comic.page");
       ...
       print("****a");
       ...
       print("****b");
       ...
       print("****id: " + comic.identifier);
   }

}

I add "****" in the print to find the output more easily. Sometimes when I do not find the error at first sight I add a lot print statements like in the example above to find the error (e.g. written something wrong, forgot something etc.).

In case all that does not work and pageRetrieved is still called you could use print(data); so that you can check if the data is correct and if it is what you expected.

Publishing on kde-files.org

First you should deinstall the plugin by

plasmapkg -t comic -r my_comic

and then you need an account on www.kde-files.org. If you have done all that go to the "Plasma Comics" section and contribute your plugin. It will show up in the "Get New Comics..."-Dialog after a while.