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