But the modules feature is not gone. I’ve simply included all modules which could be downloaded before from my server directly in iCab Mobile, so all the modules are automatically available without downloading them before. So for most users nothing serious has changed.

The only problem is with the modules (written by users) which I don’t know of. Users can no longer write and share their own modules themselves. If you know of such a module or if you still want to write a module, please contact me. I can add these modules to the next updates of iCab Mobile and this way the modules can be still shared with all iCab Mobile users.

I really can’t say that I like Apple’s decision, and technically it doesn’t make much sense.  ”Modules” for iCab Mobile are simply a more comfortable variation of bookmarklets, and these are still allowed by Apple (and I assume Apple can not forbid that the user will save and use bookmarklets). Maybe if I would have called the modules “smart bookmarks” and would have made installing them much more complicated, Apple would have never asked to remove the ability to download them from the internet. The great user experience of installing modules has probably created a suspicion that these modules are more than just a piece of JavaScript code. From a pure technical point of view, if Apple does not allow to download modules (JavaScript code), Apple would also have to disallow to load web pages in general, because these do also contain JavaScript code.

I think the current solution in shipping all modules together with iCab Mobile should be fine for all users and should not cause much trouble. Hopefully one day Apple will rethink their decision and will allow module downloads and also some other stuff again.

When you load a web page from the internet through UIWebView, you can provide a delegate which is called for each web page that is loaded. And in the method “webView:shouldStartLoadWithRequest:navigationType:” of the delegate, you’ll even get an NSURLRequest object you can look at, but unfortunately you can not modify this object. So there’s no way to change the default “User-Agent” information that is sent to the server, nor can you modify any other data.

When you’re loading data from the internet outside of UIWebView, you would probably use the NSURLConnection class. In this case you would create an NSURLRequest object (or the mutable counterpart NSMutableURLRequest) with all the HTTP headers for the request yourself (using the method “setValue:forHTTPHeaderField:”). You have full control over all of the HTTP headers you want to send to the server, including the “User-Agent” information.

When we assume that the UIWebView object will internally also use NSURLRequest or NSMutableURLRequest to create a HTTP request before this request is passed to the networking classes like NSURLConnection, we need a way to subclass or overwrite the method “setValue:forHTTPHeaderField:” of the NSMutableURLRequest class. Then we would be able to check for each HTTP header that is set for a NSMutableURLRequest, if this is the “User-Agent” header and if it is, we can modify it.

The only problem is that we can’t overwrite or subclass the NSMutableURLRequest class and force UIWebView to use our subclass instead of the original class. But iPhone Apps are written in Objective C and this programming language does allow exchanging and modifying classes, methods, variables etc. at runtime any time. So we can tell the Objective C runtime system that each time the method “setValue:forHTTPHeaderField:” of the “NSMutableURLRequest” class is called, our own method is called instead. This way it doesn’t matter that UIWebView will never call our method directly. Exchanging methods is called “Method Swizzling” and you can learn more about it on the CocoaDev page.

The method swizzling is very powerful, but it can be also very dangerous if you don’t know what you’re doing. So be very careful.

Now to the sources. I’ve implemented the method swizzling as a category of NSObject, so you can use it for all classes very easy (but as I said above, be careful, don’t use it if there are other options).

MethodSwizzling.h:

@interface NSObject (Swizzle)

+ (BOOL)swizzleMethod:(SEL)origSelector withMethod:(SEL)newSelector;

@end

MethodSwizzling.m:

#import "MethodSwizzling.h"

@implementation NSObject (Swizzle)

+ (BOOL)swizzleMethod:(SEL)origSelector withMethod:(SEL)newSelector
{
    Method origMethod = class_getInstanceMethod(self, origSelector);
    Method newMethod = class_getInstanceMethod(self, newSelector);

    if (origMethod && newMethod) {
        if (class_addMethod(self, origSelector, method_getImplementation(newMethod), method_getTypeEncoding(newMethod))) {
            class_replaceMethod(self, newSelector, method_getImplementation(origMethod), method_getTypeEncoding(origMethod));
        } else {
            method_exchangeImplementations(origMethod, newMethod);
        }
        return YES;
    }
    return NO;
}

@end

You can call “swizzleMethod:” for an object, passing in the selectors of the original and the new replacement methods. If the “swizzleMethod:” method returns with the result YES, each call of the original method will then call the replacement method and each call of the replacement method will call the original method. So within your replacement method you can still call the original method.

Here’s the implementation of the new replacement method for the NSMutableURLRequest class:

MyMutableURLRequest.h:

@interface NSMutableURLRequest (MyMutableURLRequest)

+ (void)setupUserAgentOverwrite;

@end

MyMutableURLRequest.m:

#import "MyMutableURLRequest.h"
#import "MethodSwizzling.h"

@implementation NSMutableURLRequest (MyMutableURLRequest)

- (void)newSetValue:(NSString *)value forHTTPHeaderField:(NSString *)field;
{
    if ([field isEqualToString:@"User-Agent"]) {
        value = @"The new User-Agent string";
    }
    [self newSetValue:value forHTTPHeaderField:field];
}

+ (void)setupUserAgentOverwrite
{
    [self swizzleMethod:@selector(setValue:forHTTPHeaderField:)
            withMethod:@selector(newSetValue:forHTTPHeaderField:)];
}

@end

This new method is implemented as a category, we don’t need to subclass. The replacement method for “setValue:forHTTPHeaderField:” is called “newSetValue:forHTTPHeaderField:” and it is simply checking if the “field” variable is equal to “User-Agent”. If it is, the value is modified. Afterwards the original method is called.
Please note: because the method swizzling exchanges the original and replacement methods, we have to call “newSetValue:forHTTPHeaderField:” to call the original method “setValue:forHTTPHeaderField:”. This looks confusing, but this is the way you can give control back to the original method.

The method “setupUserAgentOverwrite” has to be called once after the App is launched (for example in the Application delegate in the “applicationDidFinishLaunching:” method, or even in “main()”).

   [NSMutableURLRequest setupUserAgentOverwrite];

This should be done before any UIWebView objects are created to make sure that the “User-Agent” is modified for all requests.

You can also use this approach when you need to modify other HTTP headers.

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.

The main purpose of AppLink is to make it possible for (internet-aware) iPhone Apps to call each other to open certain URLs. For example by default, all apps are able to let the iPhone OS open a URL, and the iPhone OS will launch Safari or Mail to open these URLs. Unfortunately the iPhone OS will never call other apps (like an alternate Web Browser) for the standard URL schemes, so you can’t change the default browser or the default Mail app.  If Apps support non-standard URL schemes then the iPhone OS is able to call these Apps from within other Apps, but the problem is, that the other Apps don’t know about these non-standard URL schemes. So calling these apps is difficult.

AppLink will try to solve these issues. But there are limits here as well. AppLink-aware Apps can detect each other, so they can call each other to open URLs. But for calling other Apps which are not AppLink-aware, nothing has changed. So the goal should be that as many (internet-aware) Apps as possible do support AppLink to get the best user experience.

The current implementation of AppLink assumes that a Web Browser (like iCab Mobile), an RSS reader and a Mail App are the most important Apps for accessing the internet, the center of your internet activities. Technically this is because the standard URL schemes of the internet are “http”/”https” (Web Browser), “feed”/”feeds” (RSS reader) and “mailto” (Mail App) and these are all already supported by the iPhone OS and its default Apps (Safari and Mail).

An example:

There’s an AppLink-aware Web Browser (like iCab Mobile) and an AppLink-aware Facebook App installed on the iPhone. The Facebook App can open links in an external browser and the user can decide if this browser is iCab Mobile or Safari or maybe another browser. And if the user is currently surfing in the web using iCab Mobile and opens a link to a new interesting facebook profile, iCab Mobile would automatically show or enable a special button. If the user taps on this button, the native facebook app is called with the current facebook URL, so the user can directly add and manage the new facebook profile within the facebook app where he also manages all the other facebook profiles and contacts. The user doesn’t have to quit and lauch apps manually, the user doesn’t need to copy and paste URLs etc. All this can be done by AppLink automatically.

Wikipedia Apps, Twitter Apps and many other Apps can be called the same way if they support AppLink. The AppLink-aware browser will know that a Wikipedia App is interested in wikipedia.org URLs and the a Twitter app is interested in “twitter.com” URLs, so it can automatically offer to open such URLs in these native Apps.

But also very simple tasks like opening the FAQ page of an App in a web browser or sending an email to the developer of an App  can be done using AppLink (many Apps in the AppStore do have something like this build in, though only calling Safari or Mail). The AppLink solution will call the AppLink-aware browser or AppLink-aware Mail App if available. If these are not available on the device, the default Apps (Safari and Apple Mail) are called. And calling the AppLink-aware App instead of the default one is most likely what the user wants, otherwise he wouldn’t have installed the alternate apps.

The curent beta version of  ”iCab Mobile” does already support AppLink with all its features. Though there are currently no other AppLink-aware Apps available, the AppLink features can be already used with some of the build-in apps like the native YouTube app. When opening a YouTube video page a new button will appear next to the URL field. Pressing this button will offer to open the video in the native YouTube app. And what can be done for YouTube URLs would also work for other URLs (like Facebook, Twitter, Wikipedia etc.). Here’re some screenshots, how this can look like:

You can download the AppLink class here: AppLink.zip (32 KB)

There’s also a small web site about AppLink: http://www.icab.de/dev/AppLink.html

Please spread the word about this AppLink proposal. Hopefully many iPhone App developers will find this useful and will support AppLink in their Apps.

I’m also looking for feedback, suggestions and critics. So please tell me if you like the idea, if you have suggestions, if you need help etc. Please use the email address “alexander@icab.de” or write a comment here. Developers who want to add AppLink support in their Apps and need a counterpart App to test with (like for example iCab Mobile), please contact me as well. Maybe I can provide you with a beta version of iCab Mobile (but there’re limits in the number of beta versions I can give away).

But with a “bookmarklet” (a special bookmark which is based on JavaScript code) you can do this as well. Here’s how the bookmark URL for the bookmarklet should look like:

    javascript:location.href='web'+location.href.substring(4);

Because you can’t create Bookmarks from scratch in Safari on the iPhone, you should just create a bookmark of a random page and change its URL to the above line and the title to “Open in iCab Mobile”.

If you open this bookmarklet from within the Safari bookmarks, the currently displayed web page is passed to iCab Mobile and opened there.

The bookmarklet simply changes the URL scheme from “http” to “web” and from “https” to “webs”. And because iCab Mobile supports the “web” and “webs” schemes as a replacement for “http” and “https”, the iPhone OS will pass these modified URLs to iCab Mobile.

• a copy of iCab 4
• the Automator Script from David Hall
• a binary copy of the WebKit nightly builds

Now copy the iCab 4 application, the WebKit application and the Automator Script iCabWK into the Applications folder of your Mac. Make sure that neither iCab nor WebKit are running and double-click the Automator Script iCabWK. This will launch iCab so that it will use the WebKit framework that is located within the WebKit application.

To check if iCab is really using the WebKit nigthly build, you can download the WebKitDetect script from the WebKit nightly web page and open it in iCab. It will tell you which version of WebKit is currently used. But please make sure that you’ve configured the Identity setting of iCab (in the “View” menu) to the default value “Best compatibility“. The latter is important because changing the identity setting will change the value of the browsers “UserAgent” information, and the WebKit detection script is using the UserAgent information to determine the WebKit version that is used.

If you want to use the WebKit nightly within iCab, please always start iCab by double-clicking the iCabWK Automator Script. If you double-click iCab directly, or launch it indirectly by opening a HTML file or an URL, iCab will use the WebKit that is built-in into the system.