Saturday, March 26, 2011

Advanced mediaservice and plugins. Part II: mediaservice

"Welcome the task that makes you go beyond yourself." (Frank Mcgee) [1]

...and also welcome back to this second part of Advanced mediaservice and plugins. In the first part, I introduced the the interface each plugin must implement and also showed how to write a provider plugin for the mediaservice. In this part I will show a little bit of what has been done so far and talk about further plans.
But first something I forgot to mention in the previous post.
Since we know now how to build the skeleton of our little plugin called MyProvider we still cannot tell what it should do. For that matter the mediaservice comes with some libraries that helps you query your provider more easily.

  • The file stdutils.js has some functions that makes it easy to do requests and build urls.
  • mediaapi.js contains the whole API for media and mediacollections. An error API was added for better error handling.

  • xmldom.js, xmlsax.js and xmlw3cdom.js are libraries that are able to parse xml documents. Since (right now) all of the plugins receive xml documents from their providers, these libraries are the ones parsing them. For more documentation about the xml libraries see [3].
If we pick up our example MyProvider again, the requesting and receiving information would look like this:


MyProvider.prototype.searchMedia = function(queryParams)
{
  // get the paramters from the service
  var text = queryParams['text'];
  var maxResults = queryParams['max-results'];
  var page = queryParams['page'];
  
  // build the url, result will be:
  //http://www.myprovider.com/search?text=...&per-page=...&page=..
  var url = buildUrl("http://www.myprovider.com/search",
    {
       "text" : text,
       "per-page" : maxResults,
       "page" : page
    });

  // we want to save the response
  var result = "";
  // make the request
  doRequest(engine, url, 
    function(job, data)
    {
       result += data.valueOf();
    },
    function(job)
   {
      // showing the result in the terminal
      print(result);
      // parse result here with the xml libraries
   }
  );
}
The two functions buildUrl() and doRequest() are included in the stdutils.js library. 

The code of the mediacenter is in [4]. Feel free to check out what we've been done so far. The code on the mediaservice is in dataengines/javascript/service/ and the plugins find themselves in dataengines/addons/.


Further plans
Right now, there hasn't been much activity in plasma-mediacenter-land and I hope that we continue more intensely on this project in the future.

However, a particular idea for this years Google summer of Code has been posted, which includes porting graphical elements to QML [2] and I am looking forward to see someone implementing it. A good way to make the mediaservice "useful" is to integrate it in that idea. I, myself was a little impatient to see something like that, so I implemented a little QML-plasmoid that connects to the mediaservice and queries a plugin (in that case it was flickr). Here is a little screenshot:


Thats all from here. Thank you for reading.

cheers
---
[1] http://www.quoteland.com/author/Frank-Mcgee-Quotes/6420/
[2] http://community.kde.org/GSoC/2011/Ideas#Project:_Plasma_media_center_first_release
[3] http://xmljs.sourceforge.net/
[4] http://projects.kde.org/projects/playground/multimedia/plasma-mediacenter

Thursday, March 24, 2011

Advanced mediaservice and plugins. Part I: plugins

Hello fellow blog readers!
It's been awhile the last time I wrote something. My last post was about my results of my google summer of code project Media and plugins, however since a couple of weeks, I continued on this project and would like to share my progress.
In this first part I would like give a little introduction on how to write a little provider plugin, in the second part I will talk about the achievements so far and further plans.

The Tutorial

Important here is, that a plugin must implement an interface, which has these four signatures:


searchMedia(text, max-results, page, media)

Makes a community search for media given a text. max-results, page and media are optional parameters. By default, max-results is 25, page is 1 and media depends on the media provider. E.g. in flickr, media has a default value of photos. In this case flickr is able to search for videos and photos. On the other hand, picasa does not have this ability.


searchCollection(text)

Makes a community search for media collections given a text. Some providers do not provide the functionality to search for collections. In that case this function can be left blank.


getUploadedUserMedia(user, max-results, page)

Receives all uploaded media from a user. max-results and page are optional parameters. Again, by default max-results has the value  25 and page the value 1.

getUploadedUserCollection(user,max-results, page)

Receives all uploaded collections of media from a user. Also here max-results and page are optional parameters with the above mentioned default values.

With that information about the interface signature we are now able to write our own plugin, which looks like this:

// the constructor
function MyProvider()
{
   this.name = "myProvider";
}
MyProvider.prototype.searchMedia(queryParams){
   print("Searching for media " + queryParams['text']);
}

MyProvider.prototype.searchCollection(queryParams){
   print("Searching for collections " + queryParams['text']);
}

MyProvider.prototype.getUploadedUserMedia(queryParams){
 print("Getting uploaded media from user " + queryParams['user']);
}
 
MyProvider.prototype.getUploadedUserCollection(queryParams){
   print("Getting uploaded collections from user " + queryParams['user']);
}

Note that in JavaScript we use prototypes to access information across function scopes.

The parameter in each function queryParams is an array, because we receive  the parameters from the mediaservice and we access them with e.g. queryParams['text'] if we want to get the text parameter.
The 'text' and 'user' parameters are mandatory in each function (if  provided). Without them every function will not able to perform any operation.

At the end of each plugin, we have to "tell" the plasmaEngine, that this code above is a plugin. We do that with

registerAddon(MyProvider);
And that's about it. Thank you for reading. The second part is on its way. 

Stay tuned...