Skip to content


Modules for iCab Mobile (Updated 2011/03/26)

Update 2011/03/26
Please also read the blog post “iCab Mobile Modules and Apple” for recent events, affecting the modules feature.

The version 2.1 of iCab Mobile introduces a new “modules” feature. Modules make it possible to add new features in iCab Mobile just by downloading them. They can be used for simple things like increasing the font size so a page is more easy to read on the small iPhone screen, but also more complex tasks can be done, like downloading YouTube videos or to post a web page URL at Twitter (including the login and creating a tiny URL). iCab Mobile 2.1 comes with a few built-in modules, and there are also several modules available for download.

This blog post will explain, how you can write your own modules for iCab Mobile and how you (and maybe other users) can install them in iCab Mobile.

Technical background

Technically, modules are somehow similar to bookmarklets, but with more features and more flexibility. This means the modules are written in JavaScript code and they can do everything that can be done with JavaScript. Unlike bookmarklets, where the complete JavaScript code must be squeezed in one single line so that it can be used as a URL with “javascript” scheme, the modules can be nicely formatted, without any line limitation. Modules have a special header section where the module properties are defined. The properties include an icon that is displayed in the Modules panel of iCab Mobile, but also settings which do allow the user to configure the module in the iCab Mobile module settings panel.

The module structure

The module is a normal text file with JavaScript code. There’s a header section and the code section. Here’s an example, how this looks like:

//startconfig
//id=de.icab.crazy
//icon=iVBORw0KGgoAAAANSUhEUgAAACwAAAAkCAYAAADy19hsAAAWrGlDQ1BJQ0...
//title=Crazy Layout
//description=The module sets random colors for the page elements
//description.de=Das Modul setzt alle Farben der Seite auf Zufallswerte
//var=confirmation;type=confirmation;default=false;
//var=language;type=language;
//endconfig

var hex = "0123456789abcdef";

function iCabMobileGoCrazyForElement(element) {
  if (element.nodeType == 1) {
    if (element.style.display != "none" &&
           element.nodeName.toLowerCase() != 'select') {
      element.style.backgroundColor = "#" +
                   hex.charAt(Math.random()*16) +
                   hex.charAt(Math.random()*16) +
                   hex.charAt(Math.random()*16);
      element.style.color = "#" +
                  hex.charAt(Math.random()*16) +
                  hex.charAt(Math.random()*16) +
                  hex.charAt(Math.random()*16);
      for (var i=0; i<element.childNodes.length; i++) {
        iCabMobileGoCrazyForElement(element.childNodes[i]);
      }
    }
  }
}

var doAction = (confirmation == false);

if (confirmation) {
  var text = "Go crazy?";
  doAction = confirm(text);
}

if (doAction) {
  iCabMobileGoCrazyForElement(window.document.body);
}

The header section defines the properties of the module. The header section starts with the line

//startconfig

and ends with the line

//endconfig

Between these two lines all the properties are defined, each individual property definition occupies exactly one line, so currently you can’t split the definition of a property into multiple lines. Also no empty lines are allowed in the header section. Each property definition has the following format:

//property=value;additional paramaters

The additional parameters are optional and not always needed or required.

There are some properties which are required. If they are missing, iCab Mobile will ignore the module. Other properties are optional and do not need to be present. Here are the properties which are currently supported:

id (required)
This property identifies the module. When updating or reinstalling a module, the value of the “id” will be used to find the old module that has to be replaced by the new one. So when updating a module, you must not change the value of the “id”. Everything else can be modified, even the name of the module. The value of the “id” property should be unique among all existing modules. The best way to find a good “id” value is to use a reverse domain name appended with the module name. If your own web page has the domain “www.your-domain.com” you should set the “id” value to “com.your-domain.moduleName”. All of your own modules will have the same reverse domain prefix and the module name as suffix. If you don’t have your own domain, you can use your name and city as a prefix and maybe some random numbers, anything which makes it unlikely that someone else uses the same id value. The “id” is not visible to the user within iCab Mobile. Its only used to identify the module.
Example: 

//id=de.icab.crazy

or if you don’t have your own domain, you may use something like this:

//id=de.darmstadt.clauss.alexander.crazy
title (required)
The title defines the name of the module and is displayed within the modules settings of iCab mobile. The title property is needed so that the user can enable or disable the modules in the in-app settings and also configure the modules settings.
Example: 

//title=Crazy Colors

You can also define localized versions of the title. Just append the language code (for example “en” for English, “de” for German, “it” for Italian etc.) of any of the languages which are supported by the iPhone OS to the “title” keyword
like this:

//title.de=Verrückte Farben

This way you can easily localize the module in many languages. The key “title” without a language code appended will be used as default language which is used when none of the defined languages does match the current language of the iPhone or iPod Touch. In general the default language should be English. If no default language is defined, then the very first language that is define will be used as default language. But it is highly recommended, that you simply use English as the default language (without language code).

So if the module supports English and German, the title would be defined this way:

//title=Crazy Colors
//title.de=Verrückte Farben
description (optional)
The description is displayed in the settings panel of the module in iCab Mobile. The description should explain what the module is doing. Localizing is done in the same way as described above for the title. Append the language code to the “description” keyword: 

//description=The module sets random colors for the page elements
//description.de=Das Modul setzt alle Farben der Seite auf Zufallswerte
icon (optional, but highly recommended)
The icon is displayed when the user opens the modules panel where the modules can be activated by tapping on their icon. The icon should be an image file in PNG or JPG format. The data of the image file must be encoded with “base64″ and this “base64″ encoded data can be then used as value for the “icon” property. Usually the base64 data is formatted in lines of at most 64 characters length, but for the modules, all line breaks must be removed, so the icons data can be completely included in one line. The size of the module icons (the visible part) should be approx. 41*32. You can use the following empty icon image as a template for your own icons:
 

//icon=iVBORw0KGgoAAAANSUhEUgAAACwAAAAkCAYAAADy19hsAAAWrGlDQ1BJQ0...
var
The “var” property defines JavaScript variables, which are initialized by iCab Mobile. These variables can be used to allow the user to configure the modules, but also to get certain system properties, like the system language. 

Variables do have the following format:

//var=NameOfVar;type=typeOfVar;default=defaultValue;title=labelForSettings;

iCab Mobile will create a standard JavaScript variable declaration and initialization for all of these variable properties and adds these to the JavaScript code of the module. So your JavaScript code of the module can check and use these variables just like any other variables.

The value of the “var” property is the name of the variable.

The “title” property is required, when the variable should be presented to the user in the module settings, so the user can change the value of the variable. The value of the “title” property is used as the label in the settings panel. You can add additional localized versions of the title, just by appending the language code (as described above).

The “default” property can be used to define a certain default value for the variable.

The value of the “type” property is the type of the variable, which can be one of the following:

bool or boolean
The variable can have the values true or false. In the module settings this variable will be represented by a “switch” control. If the user switches it on, the variable will have the value true otherwise the variable will have the value false. The title attribute is required for this type. The title is shown as label for the switch in the module settings.
int or integer
The variable can have a numerical value. In the module settings, this variable is represented with a text field where you can enter digits. The title attribute is required for this type. The title is shown as label for the edit field in the module settings.
string or text
The variable can have a string value. In the module settings, it is represented as a text field. The title attribute is required for this type. The title is shown as label for the edit field in the module settings.
pass or password
The variable can have a string value. In the module settings, it is represented as a text field where the input is hidden. The title attribute is required for this type. The title is shown as label for the edit field in the module settings.
lang or language
The value of this variable is a string that contains the language code of the currently selected system language. This variable is not presented in the settings panel of the module. Therefore no title property is required here.
confirm or confirmation
The variable has a boolean value. It is represented in the module settings by a switch where the user can enable or disable a confirmation box. If enabled, iCab Mobile will ask each time the module is activated, if it should be really executed. This variable does not need a “title” property because it is automatically localized within the module settings panel.
autorun
The variable has a boolean value. It is represented in the module settings by a switch where the user can configure, if the module should be automatically run when the page has finished loading. This variable does not need a “title” property because it is automatically localized within the module settings panel. If there’s no variable of the type “autorun” set, the module can only be opened manually. You can set the default value for the variable to switch on or off the “autorun” feature for the module. But the user will be always able to disable the “autorun” feature in the module settings. When the modul is executed, the variable that is defined with the type “autorun” will have the value “true” if the module was executed automatically (which means when the page has finished loading) and the value “false” if the module was opened manually by the user. So a module is able to do different thing when called automatically and when called manually (for example it can mark elements when called automatically to notify the user about something, and modify the elements when called manually, to do the real work). [This feature will be available in iCab Mobile 3.3, it’s not yet available in version 3.2]
select
The variable of this type can be used to select one item from an array of items. This variable type uses the title property in the same way as the other types to define the label in the module settings. This variable type requires that two other properties are defined as well. The “values” property must be defined to create the array of values the user can choose from, and the “valuetitles” property must be defined to define the array of titles for these values. The “valuetitles” properties is localizable again, so append the language code as shown above for the “title” property. For the “values” and “valuetitles” property, all items must be separated by the “|” character.
An example: 

//var=s;type=select;valuetitles=One|Two|Three;values=1|2|3;title=Number;default=2

In the settings the user would be able to choose between “One”, “Two” and “Three”. If the user selects “One” the variable s would have the value 1, if the user selects “Two” the variable s would have the value 2 etc. The default value would be 2 and the user would see that “Two” is preselected. The whole setting would have the label “Number”.

When the user activates a module, iCab Mobile will process the header sections and creates JavaScript variable declarations for all the variable definitions from the header section. The values for these variables will be determined by the module settings. Technically, iCab will add these variable declarations before the JavaScript code section of the module, so the module can access these variables. These variables and the JavaScript code section will be embedded in a block, so they have their own scope and do not interfere with the JavaScript code and variables which are already present in the web page.

This means, when the module looks like this:

//startconfig
//id=de.icab.module
//icon=iVBORw0KGgoAAAANSUhEUgAAACwAAAAkCAYAAADy19hsAAAWrGlDQ1BJQ0...
//title=Some Module
//var=confirmation;type=confirmation;default=false;
//var=language;type=language;
//var=text;type=string;title=Text;
//endconfig

function DoSomething() {
  // here's the actual code which is doing all the work of the module
}

if (confirmation) {
  doAction = confirm("Really activate the module?");
} else {
  doAction = true;
}

if (doAction) {
  DoSomething();
}

the resulting code that is actually executed in the context of the web page looks like this:

{
  var confirmation = true;
  var language = "en";
  var text = "User Input";

  function DoSomething() {
    // here's the actual code which is doing all the work
  }

  if (confirmation) {
    doAction = confirm("Really activate the module?");
  } else {
    doAction = true;
  }

  if (doAction) {
    DoSomething();
  }
}

Special JavaScript functions

Modules can also call special JavaScript functions, which are defined by iCab Mobile to do certain tasks.

There are the following functions available:

startDownload(url,file)
This function starts a download. The parameters are the URL and a suggestion
for the filename under which the download should be saved.
postRequest(url,content,”callBackFunction”)
This function gets the data from the URL using the HTTP POST command (posting “content” to the server) and then passes the HTTP status code and the data to a function called “callBackFunction” (see getRequest() below for a description of the callback function).
getRequest(url,”callBackFunction”)
This function gets the data from the URL using the HTTP GET command and then passes the HTTP status code and the data to a function called “callBackFunction” (the second parameter is a string with the name of the callback function that must be implemented by the Module to process the data): 

function callBackFunction(status, data) {
  // "status" is an integer value with the HTTP status code (200, 404, etc)
  // "data" is a string with the URL data
}

Installing the modules

Installing the modules is done by simply downloading them from a web site. So all you need to do is to provide a web page which contains a link to your module. The link URL must use the URL scheme “icabmodule” or “javascriptmodule” instead of the usual “http” scheme. This is how iCab Mobile detects that it should download and install a module.

For example, if your module can be accessed with the URL http://your.webspace.com/modules/TheModule.icabmodule
the HTML link you would have to include in your web page would look like this:

<a href="icabmodule://your.webspace.com/modules/TheModule.icabmodule">Download TheModule</a>

or alternatively look like this:

<a href="javascriptmodule://your.webspace.com/modules/TheModule.icabmodule">Download TheModule</a>

If you include these links on a web page which is accessible to other people as well, other iCab Mobile users would be also able to install your module. So you can easily share your modules with other users.

I’ve created two URL schemes for the modules. In case other iPhone developers are interested in this module feature (candidates would be developers of other iPhone browsers), it would be great if all these modules would be compatible. In this case the general URL scheme “javascriptmodule” could be used by all the Apps supporting the modules feature. And the other URL scheme could be used for application specific-modules (so “icabmodule” would be only accepted by iCab Mobile).
Just a reminder: My AppLink Proposal can be also used by other iPhone Apps.

You can also sent the module to me so I can include it into the modules download page, which is accessible through the “Download” module that is built-in in iCab Mobile. This way the module can be immediately found by all iCab Mobile users.

Posted in iCab, iPhone & iPod Touch, Programming.

Tagged with , , , , , .


104 Responses

Stay in touch with the conversation, subscribe to the RSS feed for comments on this post.

  1. James McAdams says

    Coding looks straightforward but I’m incompetent – any chance we could see instapaper or read it later modules? Also, is there any chance of customising the mobilise service – I prefer instapaper to google for formatting. A couple of Twitter clients incorporate this so I imagine it should be straightforward enough…

  2. Alexander Alexander says

    I’ve just written a few new modules for Instapaper. There’s a module available for the Instapaper mobilizer and also a module to add a bookmarks to your Instapaper account.

    Just use the “Download Module” to find the new modules.

  3. James McAdams says

    Brilliant! Thank you!

  4. Rowan Pope says

    This is an absolutely awesome app, I love it. I hope your well on the way to an iPad version, I’ll buy it as soon as it’s out!

  5. Rich says

    Great Idea. I added a similar stripped down feature in my browser after seeing it in iCab. Now that I see the spec, I may implement it like your version to standardize modules for JS developers. Keep up the good work. iCab is one of my favorite iPhone browsers which I get a lot of inspiration from.

  6. Alexander Alexander says

    @Rich
    Just let me know if you have some suggestions about improvements. I’d love to see other modules than my own ;-)

  7. Vladimir says

    Hello,

    I created module for evernote web clipper.
    http://dl.dropbox.com/u/132290/icab/Modules.html
    NB
    Evernote web clipper has a bug with authorization, so you need to do next:
    1. change user agent in icab to firefox
    2. go to https://www.evernote.com/Login.action and login to site
    3. change user agent back

    Every time web clipper will ask you about authorization you need do do this again ;)

  8. Chris says

    Alexander, this is awesome. I just discovered iCab yesterday (through the Apple Blog) and had to buy it right away. Brilliant.

    One little issue I have is with the story headers in Instapaper, after creating a link through the module (for instance, on http://www.focus.de): Instapaper then shows the URL’s as headers instead of the story headline. Not sure if that is an easy fix or not?

    Otherwise, this is an awesome app. I like the tabs and that one is able to switch to fullscreen, and to be able to create own modules to enhance functionality is great.

    Thanks for the good work.

  9. Alexander Alexander says

    @Chris
    The Instapaper module is not responsible for the formatting of the page, it simply
    forwards the page to the Instapaper service in the web. So there’s nothing I can do here.

  10. Pat Emeri says

    Just bought the app after seeing the review on jkontherun.com. Love it. One question. I’m trying to set up my instapaper ID and password but can’t find a way to get that info to save so that it will work. What am I missing?

  11. Alexander Alexander says

    @Pat Emer
    In the “Settings” of iCab Mobile (tap on the “gear” icon in the toolbar) you’ll find the settings for the modules as well. Just go to the settings for the Instapaper module and here you can enter your Instapaper login information.

  12. Alti says

    Hi,
    First of all great product. Was wondering if you are planning some sort of a dropbox module, so that we can have the downloads get moved to our dropbox account (or uploaded to dropbox account). Or a way way can choose which downloads to have uploaded to dropbox.

    I hope this makes sense, I’m not being very articulate in explaining this – and I apologise for that – But I just think that some sort of Dropbox integration will make your Mobile Browse go from being the best right now to being the best ever! :)

  13. Alexander Alexander says

    Dropbox support is already planned. But this can’t be done with a module, this must be directly built-in into iCab Mobile.

  14. Alti says

    Thanks for getting back so quickly Alexander. Can’t wait for the Dropbox feature integration! Any idea when we can expect this?

    Sorry can hardly hold my excitement about this! :)

  15. Alexander Alexander says

    @Alti
    Sorry, but I can’t give you a release date for this feature yet.

  16. Alti says

    That,s alright, I understand. Just knowing that this feature is coming soon is good enough for me. Just don’t keep me holding my breadth for too long! Till then i’ll try to turn some more more people to you wonderful app…

  17. Theikid says

    Any chance to vêt an upload module?

  18. the ikid says

    actually I’m looking for a way to send a .torrent from icab on my ipad to my seedbox… i know a greasemonkey script that works but i’m not good enough to manage to do this on my own :/

  19. Alexander Alexander says

    @The iKid
    A general solution for uploading files can not be implemented at the moment. The iPhone/iPad OS doesn’t support the “file” button in web forms.

    I think it would be possible to get this working for a few web pages which match certain special conditions (for example no modification or processing of forms or forms data with JavaScript is allowed). But this isn’t easy and this can’t be done with modules at the moment because there’s no way to select your file for the upload.

  20. the ikid says

    Hi Alexander, thank you for the reply :) For now Imusing icab to download file and upload them through ftp on the go. The fact that file button doesnt work is a limitation in webkit ?

  21. Alexander Alexander says

    @The iKid
    Yes, WebKit on the iPhone/iPad doesn’t support the “file” button.

  22. Chris says

    Hi,
    First of all a thank you for an outstanding app! My most use ipad app by far.

    I was hoping to use the modules feature to sync bookmarks from my Google account. Please could you let me know if there is or is planned any access to create/manage bookmarks from a module.

  23. Alexander Alexander says

    @Chris
    The modules feature can not be used to sync bookmarks. Modules can only be used to do certain tasks with the current web page. They can not access the bookmarks.

    But I’ve plans to add a bookmarks syncing feature. But this will need a while because there are so many different bookmarks services, so I think I need some generalized way to support these services. Maybe with the help of some “plugins” for each of these services.

  24. Tolin says

    Hi
    Thanks for your great browser.
    Just a question about modules. Could it be possible to develop a module to unrar/unZip the downloaded files? Or it must be implemented inside the browser?
    That would be a great feature

  25. Alexander Alexander says

    @Tolin
    Extracting archives can not be done with modules. Modules are more or less just some
    more comfortable bookmarklets. Which means Modules can only do thing which can be done with JavaScript, and JavaScript does not have full access to the filesystem.
    I’ve already thought about adding an unzip feature, but this makes sense only when there’s a file browser included as well. And I think it makes more sense to use the new OS 3.2 feature (iPad) to share documents between apps. This is already implemented, so you can easily send a download to the “GoodReader” app for example, which is a file browser and which does support unzipping ZIP archives. This does work already on the iPad and for the iPhone you may need to wait for the next OS update.

  26. Rafa says

    Why the company don’t tell us before paying for the app actually there’s a file size restriction in order to download files? I’m really dissapointed about that. Tell people the truth please!

  27. Alexander Alexander says

    @Rafa
    You can configure the limits for the downloads in the iCab Mobile settings within the “Settings” app of the iPhone or iPad.
    For WLAN you can configure that downloads have no limits at all. But for 3G/Edge connections, Apple won’t accept apps without a limit. Even Apple’s own apps do have a limit on 3G/Edge. So I think there’s nothing to complain about. You can even read about these settings in the built-in help of iCab Mobile.

  28. jn says

    What about a module to save and view HTML5 videos later (when offline) — much like the YouTube module, but not YouTube-specific. I was just watching a video on blip.tv, wishing I could do that.

  29. Alexander Alexander says

    @jn

    Please try this module: Video Download Module

    It will replace the YouTube Download module. It looks for YouTube and HTML 5 videos. Please let me know if there are any issues.

  30. Alti says

    Any update on thendropbox integration feature?

  31. Alexander Alexander says

    @Alti
    No, sorry. You’ll notice when it will be available ;-)

  32. Kairy says

    I’m experiencing difficulty getting the instapaper module to work on my iPad. I’ve tried configuring my username and password in the module settings, but every time I go back to this screen iCab has deleted the data. Whenever I try to use the “add to instapaper” I am prompted again to add my username and password in the settings menu. Any ideas?

  33. Jerome says

    Has a module been created for Google Reader subscriptions? It’d br great if there was one that would take a RSS feed from the site and add it to your Google Reader.

  34. Alexander Alexander says

    @Kairy
    This is a small bug in iCab Mobile which will be fixed in the next release. The Module settings are saved correctly if you don’t go back to the modules list from a module settings panel, but instead close the settings directly.

  35. Alexander Alexander says

    @Jerome
    No there’s no Google Reader module yet, but it would be good idea to write one ;-)

  36. Jerome says

    @Alexander: Thanks for the reply. Unfortunately, I’ve had a look through the documentation and writing a module is way beyond my capabilities. Hopefully someone will take up the task. :)

  37. Alexander Alexander says

    @Jerome
    I didn’t mean that you should create such a module. It was meant as a reminder for me ;-)

    Actually I’ve already written such a module and it will be available when the next iCab Mobile release is out. I’ve added some additional calls to the modules API in iCab Mobile which I’m using in the module, so you have to wait for the next release…

  38. Jerome says

    Alexander, that’s great! Looking forward to the next release.

  39. Ng. N. Minh says

    The Video Download Module doesn’t work ( maybe with the new iOS 4 ). Could you possibly give it a check ? Thank you very much.

  40. Alexander Alexander says

    @Ng. N. Minh
    The module still works fine for me. On which web page do you have problems?

  41. Kyle says

    I tried using the Evernote module listed above and it works fine but it keeps on saying closing and constantly flashes this until I close the window. Is anyone else seeing this problem?

  42. Kyle says

    Instapaper module on ios4 does not allow you to put in a username and password in the Module setup screen. Can you check it please?

  43. Alexander Alexander says

    I don’t see any issue with the username and password in the setup screen. I can enter both just fine.

  44. Rafal says

    Could we get some kind of a module that would enable the user to save a PDF that’s already opened in the browser?

    Some sites have dynamic and/or redirecting links which don’t work with the “Download File” option.

    Saving a PDF file which is already loaded (and is somewhere in cache?) should be doable, right?

    Thanks!

  45. Alexander Alexander says

    @Rafal
    A PDF file that is currently displayed can be saved as “Offline Bookmark”. This way you can load it offline without an internet connection. This is not a download, but in most cases this should be all you need.
    But a module which would allow to download the current page is also doable.

  46. Rafal says

    I would need to open the .pdf in another program (i.e. to iAnnotate) so the proper saving seems to be the only easy solution.

    Offline Bookmark is a cool feature but it doesn’t seem to work properly with PDFs, while offline they’re displayed as text files (as if I opened them with Notepad or some other text editor) and not as PDFs.

    Could you tell me if the “offline bookmarks” are saved somewhere on the device? Is there a way to access them with a jailbroken device?

    Would you please create a proper module which would allow downloading the current page/pdf? I’m sure it’s a lot of work, nevertheless I keep my fingers crossed! :)

  47. Alexander Alexander says

    PDF files as offline bookmarks should work fine with the current version. Only in previous versions there were issues with this.

    All files are stored in the Documents folder of iCab Mobile, the private ones in a hidden folder within the Documents folder. So you should be able to find the files on a jailbroken device.

    But as I said, a download via module is possible. When I find the time, I’ll write such a module.

  48. Justin says

    I can seem to find the module to download YouTube.

  49. Alexander Alexander says

    @Justin
    I’m currently working on the module because of the latest HTML 5 stuff on the youtube page.

    But you can download and install the VideoDownload Module directly from here.

  50. Justin says

    thank you,

    will you bring a grab & drag scroll on the bookmark bar in the future?

1 2 3

Continuing the Discussion

  1. Supercharge Your iPad Browsing with iCab linked to this post on May 20, 2010

    […] and Twitter are supported via modules. Modules are similar to Firefox’s extensions, but much simpler. They are more like […]

  2. Supercharge Your iPad Browsing with iCab « Apple News Daily linked to this post on May 20, 2010

    […] and Twitter are supported via modules. Modules are similar to Firefox’s extensions, but much simpler. They are more like bookmarklets […]



Some HTML is OK

or, reply to this post via trackback.