elementFromPoint(x,y) was defined to return the element at the given coordinates within the view port (the visible area) of the web page, or null (if the coordinates are outside of the viewport). The coordinates are measured relative to the origin of the view port. This is how iOS 5 finally works.

Before (iOS 4.x and older), elementFromPoint(x,y) completely ignored the view port. It measured the coordinates relative to the origin of the document. And even elements outside of the visible area could be found. This behavior seems to make much more sense than the new iOS 5 behavior, but according to the official JavaScript specification, it’s not the correct behavior.

The different behavior between iOS 5 and older iOS versions can cause some serious problems. The coordinate systems are no longer compatible, so when the web page or App has to run under old an new iOS versions, it is necessary to find out the correct coordinate system that is used.

In a native iOS App you could simply check the iOS version, and based on its value you can decide which coordinate system you need to use when calling elementFromPoint(x,y). But when writing a web page, this is not so easy: the iOS version is not exposed to the web page (it might be part of the UserAgent information, but because almost all browser do allow to use a fake userAgent information, this information is not reliably at all). Also on the Mac and on other platforms different WebKit releases might be used which do use different coordinate systems for the elementFromPoint(x,y) call as well. Therefore it makes sense to find a way to identify the coordinate system independent of the iOS version, and if necessary correct the coordinates.

At first when we compare the two coordinate systems, we notice that the coordinates are offset by the scroll location. If we scroll the web page so that the top left corner of the page is visible, both coordinate systems are the same. The origin of the view port is identical to the origin of the web page. And the scroll offset is also 0 in both directions. If you scroll down 100 px, the origin (the coordinate (0,0)) of the viewport is located at the coordinate (0,100) of the web page. So the scroll offset is exactly the offset between the two coordinate systems. Therefore, transforming one coordinate system into the other is very easy. We only need to add or subtract the actual scroll offsets.

function documentCoordinateToViewportCoordinate(x,y) {
  var coord = new Object();
  coord.x = x - window.pageXOffset;
  coord.y = y - window.pageYOffset;
  return coord;
}

function viewportCoordinateToDocumentCoordinate(x,y) {
  var coord = new Object();
  coord.x = x + window.pageXOffset;
  coord.y = y + window.pageYOffset;
  return coord;
}

These JavaScript functions take a coordinate of one system and transform them into a coordinate of the other system.

But in order find out if and which of the functions we need to use, we have to find out, in which coordinate system the call elementFromPoint(x,y) expects the coordinates. To do this we use the fact that elementFromPoint() returns null when the coordinates are outside of the view port, when it expects coordinates measured relative to the viewport (as noted above, when the coordinates are relative to the origin of the document, elementFromPoint() will always return an element, even when outside of the visible area, so we can distinguish between the two cases).
Good test coordinates would be (0, window.pageYOffset + window.innerHeight -1) and (window.pageXOffset + window.innerWidth -1, 0), for vertical scrolling and horizontal scrolling. As noted above, when no scrolling is done, both coordinate systems are identical, and we don’t need to take care about anything. But if the page is scrolled, we need to check which system is used. The test coordinates take the actual scroll offset and add the width or height of the visible area (this is the innerWidth and innerHeight of the “window” object) and subtract 1. This makes sure that the coordinate addresses the very last pixel line or column of the visible area measured relative to the document origin. This is always a valid document-based coordinate which lies within the document boundaries (a coordinate outside of the document boundaries would return null even with the elementFromPoint() call for the document-based coordinate system). If the page is scrolled by at least one single pixel, the test coordinates would lie outside of the viewport, when interpreted as relative to the viewport, so elementFromPoint() would return null. When elementFromPoint() would interpret them relative to the document, these coordinates are always valid and would always return an element. And this is how we can easily detect, which coordinate system elementFromPoint() is using.

function elementFromPointIsUsingViewPortCoordinates() {
  if (window.pageYOffset > 0) {     // page scrolled down
    return (window.document.elementFromPoint(0, window.pageYOffset + window.innerHeight -1) == null);
  } else if (window.pageXOffset > 0) {   // page scrolled to the right
    return (window.document.elementFromPoint(window.pageXOffset + window.innerWidth -1, 0) == null);
  }
  return false; // no scrolling, don't care
}

We can combine this to one custom elementFromPoint() function that is using a document-based coordinate system as input and will internally do all the magic for us:

function elementFromDocumentPoint(x,y) {
  if (elementFromPointIsUsingViewPortCoordinates()) {
    var coord = documentCoordinateToViewportCoordinate(x,y);
    return window.document.elementFromPoint(coord.x,coord.y);
  } else {
    return window.document.elementFromPoint(x,y);
  }
}

And the counterpart for viewport-based coordinates:

function elementFromViewportPoint(x,y) {
  if (elementFromPointIsUsingViewPortCoordinates()) {
    return window.document.elementFromPoint(x,y);
  } else {
    var coord = viewportCoordinateToDocumentCoordinate(x,y);
    return window.document.elementFromPoint(coord.x,coord.y);
  }
}

So instead of using elementFromPoint() directly, you simply use elementFromViewportPoint() or elementFromDocumentPoint() instead, depending of the coordinates you have to deal with. It will then work correct in old and new WebKit releases.

Please note: if you use the code of my older blog post “Customize the contextual menu of UIWebView” in your projects, you need to update this as well, because it also uses the elementFromPoint() call. But this should be really easy to do.

In general, when you have to use JavaScript code to do certain tasks on a web page, you need to inject this code into the web page when it is loaded. The UIWebView provides a delegate method “webViewDidFinishLoad:” which is called whenever a web page has finished loading. This is the correct location to inject your JavaScript code into the web page. And to inject JavaScript code into a web page you can use the method “stringByEvaluatingJavaScriptFromString:” of the UIWebView class.

In most cases you can just use the view controller which manages your UIWebView object as delegate for the UIWebView. When defining the view hierarchy and the view controller in Interface Builder, you can set the delegate for the UIWebView directly within Interface Builder, so you even don’t need to write any code for this. But you can also set the delegate in code, for example in the “viewDidLoad” method of the view controller. And in addition, the delegate (the view controller) has to implement the “webViewDidFinishLoad:” method, in order to get notified when the web page has finished loading. Please note that the “loadRequest:” method of UIWebView loads the page asynchronously, so when this method returns you can not assume that anything from the page has already loaded. Which means it is essential that you wait until the method “webViewDidFinishLoad:” is called.

The following example shows how this can be done in a view controller implementation (this example assumes that the JavaScript code is stored in a file “JavaScriptFile.js” within the resources of your App):

- (void)viewDidLoad
{
  // If not done in the InterfaceBuilder, you need to set the delegate for the UIWebView object
  // so that you're notified when the page has loaded (via "webViewDidFinishLoad:")
  [webView setDelegate:self];

  // ...
}

- (void)webViewDidFinishLoad:(UIWebView *)webView
{
  // Loading and injecting your JavaScript code into the webView, so you can actually use it
  // in the context of the web page that was loaded...
  NSString *path = [[NSBundle mainBundle] pathForResource:@"JavaScriptFile" ofType:@"js"];
  NSString *jsCode = [NSString stringWithContentsOfFile:path encoding:NSUTF8StringEncoding error:nil];
  [webView stringByEvaluatingJavaScriptFromString:jsCode];

  // ...
}

This is more or less everything you need to care about when programming JavaScript helper functions and injecting them into the web view objects. You can use the method “stringByEvaluatingJavaScriptFromString:” to call your helper functions afterwards and getting the results from your JavaScript functions as Cocoa string.

But there’s another detail you need to care about which is related to XCode itself. And this seems to be something many users are not aware of and what can cause your App to fail.

When building an App, XCode is doing this is several phases, like compiling the source code files, linking the object files and frameworks and copying all resources into the App bundle. The problem here is that XCode recognizes a JavaScript file as “Source Code” and therefore adds this file into the “Compile Sources” phase. But this is not correct in our case because the JavaScript file can not be compiled and linked to the object code of our App. The JavaScript file will be executed in the context of a web page within the UIWebView, so it’s not part of the “native” executable code of the App. The JavaScript code must be treated as “Resource file” and added as Resource file into the App bundle. Then we can load the file as resource within the App and inject its content to the web view.

XCode lets you inspect and edit the build phases of your project. Usually you don’t need to care about this because XCode is doing everything correct automatically. But not when adding JavaScript files. So you have to make sure that all JavaScript files which are listed in the “Compile Source” phase are moved to the “Copy Bundle Resources” phase. If you forget this, the JavaScript file won’t be copied to the resources of the App and when the App is running, it won’t be able to find and load the JavaScript files. So, always make sure that the JavaScript files are listed in the correct build phase.

The following screenshots will show you, where you find the “build phase” settings in your XCode project. The red circles indicate where you need to click to open lists or tables to find the settings.

This shows the location in XCode 3.x:

And this shows the location in XCode 4.x:

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.

The UIWebView class does not have any methods to set the zoom factor. But this can be done with certain instructions within the HTML code. The META tag can be used to configure the viewport, which includes the initial, the minimum and the maximum zoom factor.

The META tag can look like this:

<meta name="viewport" content="minimum-scale=0.6; maximum-scale=5;  initial-scale=1; user-scalable=yes; width=640">

The following viewport parameters can be used:

• minimum-scale:
  This is the minimum zoom factor that is allowed. The default value is 0.25, the range is from >0 to 10.

• maximum-scale:
  This is the maximum zoom factor that is allowed. The default value is 1.6, the range is from >0 to 10

• initial-scale:
  This is the zoom factor that is used when the web page is loaded before the user zooms in or out. The default value is calculated so that the web page fits in the visible area. But the final range will be also within the range from the minimum to the maximum factor.

• user-scalable
  This parameter can be used to allow or disallow that the user can zoom the web page.

• width:
  This parameter defines the width for the viewport. By default the width is set to 980 px on an iPhone. The possible range for this value is from 200 to 10000. The special value “device-width” represents the width of the device (which is 320 on an iPhone and 768 on an iPad). Please note that the device width is not the same as the width of the user interface. The device width is always represented by the width of the device in portrait orientation (the “natural” orientation of the device). If we want to increase the maximum zoom factor of a web page (the default factor is 1.6), we only need to add a META tag in the HTML code of the page, which defines the maximum zoom factor. If you can change the original HTML code, you can simply add the META tag and you’re done. If your App loads web pages from the internet and you can’t change the original HTML code, you have to write JavaScript code which creates a META tag and adds it to the HTML code of the web page. If you’ve read my other blog posts, you’ll already know how this works.
• height:
  This parameter defines the height for the viewport. Usually this is calculated based on the width.

The JavaScript code could look like this:

File: IncreaseZoomFactor.js:

function increaseMaxZoomFactor() {
  var element = document.createElement('meta');
  element.name = "viewport";
  element.content = "maximum-scale=10";
  var head = document.getElementsByTagName('head')[0];
  head.appendChild(element);
}

Within the webViewDidFinishLoad: delegate method of the UIWebView object you can then inject this JavaScript code into the web page and call the function to increase the maximum zoom factor:

- (void)webViewDidFinishLoad:(UIWebView *)webView
{
  NSString *path = [[NSBundle mainBundle] pathForResource:@"IncreaseZoomFactor" ofType:@"js"];
  NSString *jsCode = [NSString stringWithContentsOfFile:path encoding:NSUTF8StringEncoding error:nil];
  [webView stringByEvaluatingJavaScriptFromString:jsCode];

  [webView stringByEvaluatingJavaScriptFromString:@"increaseMaxZoomFactor()"];
}

When dealing with web pages from the web, you have to be careful because many of these web pages do already use META tags to change the zoom factor or other viewport parameters. If you add the new META tag as described above, you’ll overwrite the maximum-scale parameter and the other parameters remain unchanged. Which means, if the same parameter is defined in multiple META tags, the last one wins. Most of the time this is fine, but in some cases this can have some side effects.

For example if the web page defines some parameters which would result in an initial zoom factor of 4, but because the page does not define the maximum-scale parameter, the default value of 1.6 would also limit the initial zoom factor to 1.6. If you now increase the maximum-scale parameter, the initial zoom factor will be increased as well because it is no longer limited by the maximum zoom factor. If this can be critical for your App, you need to check for the existing parameters and based on their values you may need to define some other parameters as well (for example you may explicitly add the initial-scale parameter with a value of 1.6 to prevent that the maximum zoom factor initially zooms the page much more than it would do without your modification).

Scaling UIImages

Scaling images is important for example when you want to create thumbnail images which are used as an overview for real documents or larger pictures. The standard UIImage class doesn’t provide a method to scale images, but scaling an image isn’t very complicated. You can do it with just 4 lines of code…

UIImage *originalImage = ...;
CGSize destinationSize = ...;

UIGraphicsBeginImageContext(destinationSize);
[originalImage drawInRect:CGRectMake(0,0,destinationSize.width,destinationSize.height)];
UIImage *newImage = UIGraphicsGetImageFromCurrentImageContext();
UIGraphicsEndImageContext();

At first we have to create and start an image context with the size of the resulting image. All drawing operations which take place after the UIGraphicsBeginImageContext() call will be done in the newly created image context. This means, we are no longer drawing on the screen. All we need to do now is to draw the original image in the size of the final image. The drawing takes place in the newly created image context. Afterwards we can use UIGraphicsGetImageFromCurrentImageContext() to get an image from the image context. Finally we need to call UIGraphicsEndImageContext() to make sure that the system will release the image context again, because we don’t need it anymore. And of course the drawing will take place on the screen again after calling this function.

Creating an UIImage from a UIView

If you need an image from the content of a UIView object (like a whole web page that is displayed in a UIWebView object) or even a complex hierarchy of UIView objects so you can save it as PNG or JPEG image or use it as thumbnail image, you can do this also with just a few lines of code…

UIView *view = ...;

CGSize size = [view bounds].size;
UIGraphicsBeginImageContext(size);
[[view layer] renderInContext:UIGraphicsGetCurrentContext()];
UIImage *newImage = UIGraphicsGetImageFromCurrentImageContext();
UIGraphicsEndImageContext();

The code is very similar to the code from above to scale the image. But instead of drawing an image into the new image context, we use the “renderInContext:” method to draw the content of the view (which includes its subviews) into the image context. The resulting image will have the same size as the original UIView.

Retina Display

With the new iPhone 4 and the 4th generation iPod Touch, the iOS does also support high resolution screens. But the larger screen resolution is not used to display more content, instead it is used to display a sharper image with more details. Basically the iOS uses the same coordinate system on all screens with a size of 480×320 points. The only difference of the retinal displays is that there’re additional pixels between these points. Most drawing functions of the iOS automatically use these additional pixels to draw sharper and more detailed content. But there are exceptions when the iOS can not create more details itself. For example for bitmap images (UIImage objects), there’s no way to automatically generate a more detailed image for the retina displays. So iOS 4.0 introduces a new “scale” property for images. This property can be 1.0 (the default value) which is used for standard resolution and 2.0 for the more detailed retina resolution with twice as much details. If the “scale” property has a value of 1.0, one pixel of the image will be drawn on 2*2 (= 4 pixels) on the retina display, if the “scale” property has a value of 2, one image pixel is drawn on one screen pixel.

The above code will work with all iOS releases (including iOS 3.x which is the latest version that can be used on the first generation iPhone and iPod Touch devices), but it will always use the default “scale” property of 1.0 for images. Which means the code can not improve the image quality on the new retina displays. In order to get more detailed images on retina displays, we need to use “UIGraphicsBeginImageContextWithOptions()” instead of “UIGraphicsBeginImageContext()”, so we can define the “scale” property for the new image context as well. But “UIGraphicsBeginImageContextWithOptions()” is only available since iOS 4, so we have to check if we can use this function. If it is not available or if the device does not have a retina display, we still need to use the default scaling of 1.0 …

if ([[UIScreen mainScreen] respondsToSelector:@selector(scale)]) {
     if ([[UIScreen mainScreen] scale] == 2.0) {
        UIGraphicsBeginImageContextWithOptions(size, YES, 2.0);
     } else {
        UIGraphicsBeginImageContext(size);
    }
} else {
    UIGraphicsBeginImageContext(size);
}

Combining everything into a Objective-C Category

Now it’s time to combine all of the above and create a category for the UIImage class. I’m implementing three simple methods to create a new UIImage from a UIView or UIImage object.

• “imageWithImage:scaledToSize:” creates an image from a UIImage and scales it to a given size
• “imageFromView:” creates an image from a UIView
• “imageFromView:” creates an image from a UIView and scales it to a given size.

MyImage.h:

@interface UIImage (MyImage)
+ (UIImage*)imageFromView:(UIView*)view;
+ (UIImage*)imageFromView:(UIView*)view scaledToSize:(CGSize)newSize;
+ (UIImage*)imageWithImage:(UIImage*)image scaledToSize:(CGSize)newSize;
@end

MyImage.m:

#import "MyImage.h"

@implementation UIImage (MyImage)

+ (void)beginImageContextWithSize:(CGSize)size
{
    if ([[UIScreen mainScreen] respondsToSelector:@selector(scale)]) {
        if ([[UIScreen mainScreen] scale] == 2.0) {
            UIGraphicsBeginImageContextWithOptions(size, YES, 2.0);
        } else {
            UIGraphicsBeginImageContext(size);
        }
    } else {
        UIGraphicsBeginImageContext(size);
    }
}

+ (void)endImageContext
{
    UIGraphicsEndImageContext();
}

+ (UIImage*)imageFromView:(UIView*)view
{
    [self beginImageContextWithSize:[view bounds].size];
    BOOL hidden = [view isHidden];
    [view setHidden:NO];
    [[view layer] renderInContext:UIGraphicsGetCurrentContext()];
    UIImage *image = UIGraphicsGetImageFromCurrentImageContext();
    [self endImageContext];
    [view setHidden:hidden];
    return image;
}

+ (UIImage*)imageFromView:(UIView*)view scaledToSize:(CGSize)newSize
{
    UIImage *image = [self imageFromView:view];
    if ([view bounds].size.width != newSize.width ||
            [view bounds].size.height != newSize.height) {
        image = [self imageWithImage:image scaledToSize:newSize];
    }
    return image;
}

+ (UIImage*)imageWithImage:(UIImage*)image scaledToSize:(CGSize)newSize
{
    [self beginImageContextWithSize:newSize];
    [image drawInRect:CGRectMake(0,0,newSize.width,newSize.height)];
    UIImage *newImage = UIGraphicsGetImageFromCurrentImageContext();
    [self endImageContext];
    return newImage;
}
@end

Optimizations

Scaling images can temporarily require lots of additional memory, depending of the size of the images. The original image is first drawn in an image context. This image context must provide a bitmap buffer internally in which the drawing takes place. This buffer needs some memory. Also when the final image is created from this image context, some more memory is required. Only afterwards it is possible to free up the memory again by releasing the image context and maybe the original image.

For retina displays, the bitmap buffers for images where the “scale” property has a value of 2.0 are four times larger as for non-retina displays (scale = 1.0). So a single full screen image requires approximately 2.5 MB of memory. And because multiple bitmap buffers are required while scaling, the memory requirements can be much higher than without retina display.

This is not a big deal for the iPhone 4 which has much more main memory (512 MB) than all other devices. But for the 4th generation iPod Touch, the increased memory usage for the image buffers for the retina display is a problem. The 4th generation iPod Touch only has 256 MB of main memory, so it’s almost always running on its memory limits.

So to reduce the memory usage when creating a small thumbnail image from a UIView (which means you’re only interested in a scaled-down(!) image from a UIView), you should first create an image from the UIView with a “scale” property of 1.0. This will reduce the memory usage for the newly created image from the view. And because you’re about to scale down this image, it doesn’t matter that it doesn’t have all the details it would have with scale=2.0. When you then scale down this image using a “scale” property of 2.0, the final (smaller) image can still can get all the details it needs from the image you’ve created before.

If you have to create many images form large UIViews, you may consider to try to reduce the memory requirements this way (especially for iPod Touch with its limited amount of RAM). If you only need to deal with a few smaller views, you probably don’t need to care about this.

First of all, you really can’t add additional menu items to the default ones of the standard contextual menu. But you can switch off the contextual menu using a certain CSS property. So the solution would be to switch off the default menu and implement your own from scratch. And to implement your own contextual menu, you have to first catch the tab-and-hold gesture, get the coordinates of the finger on the screen, translate these coordinates into the coordinate system of the web page and finally look for the HTML elements at this location. Based on the HTML elements, you can then decide which menu items to include in the contextual menu, and then create and display the contextual menu.

The first step is to switch off the default contextual menu of UIWebView. This is easy because we only need to set the CSS property “-webkit-touch-callout” to “none” for the body element of the web page. We can do this using JavaScript in the UIWebView delegate method “webViewDidFinishLoad:”…

- (void)webViewDidFinishLoad:(UIWebView *)webView
{
   [webView stringByEvaluatingJavaScriptFromString:@"document.body.style.webkitTouchCallout='none';"];
}

Now, the default Contextual menu won’t open anymore.

The next step is to catch the “tap-and-hold” gesture. If your App only needs to run on iOS 3.2, iOS 4.0 or newer, you can simply use the new UIGestureRecognizer API. But if you still want to address the 1st generation iPod Touch and iPhone devices (where you can install at most iOS 3.1) where these UIGestureRecognizer classes are not available, you need to do a little bit more. I’ll show here a solution which will work with iOS 3.0 as well, so it’s compatible to all iPhone, iPad and iPod Touch devices.

A big problem when you need to catch gestures within UIWebView is that UIWebView internally consists of many nested views, and only the inner ones do respond to events and gestures. Which means, if you subclass UIWebView and overwrite the methods “touchesBegan:withEvent:”, “touchesMoved:withEvent:” etc., you’ll notice that these methods won’t be called. The events are delivered directly to these private inner views which are actually doing all the work. And if you overwrite “hitTest:withEvent:”, which is used by the iOS to find the view to which the events will be delivered, you would be able to get the touch events, but then you would have to deliver the events to these inner views yourself so these can still do their work. And because these inner views are private and the relationships between these views are unknown, it can be extremely dangerous to mess with the events here.

A much easier way would be to subclass UIWindow and overwrite the method “sendEvent:” of the UIWindows class. Here you’ll get all events before they are delivered to the views. And we can deliver the tap-and-hold events using the notification manager to the rest of the app. Each object that is interested in this gesture can listen to this notification.

Recognizing the tap-and-hold gesture is not very complicated. What we need to do is to save the screen coordinates of the finger when the finger first touches the screen. At that time we will also start a timer which fires after about a second. As soon as another finger touches the screen, the finger moves or the touch event is canceled, we invalidate the timer because then it can not be a simple tap-and-hold gesture anymore. If the timer fires, we can be sure that a single finger has touched the screen for about a second without moving and then we’ve recognized the “tap-and-hold” gesture. We post the gesture as notification.

This is the implementation of the UIWindow subclass:

MyWindow.h:

@interface MyWindow : UIWindow
{
   CGPoint    tapLocation;
   NSTimer    *contextualMenuTimer;
}
@end

MyWindow.m:

#import "MyWindow.h"

@implementation MyWindow

- (void)tapAndHoldAction:(NSTimer*)timer
{
   contextualMenuTimer = nil;
   NSDictionary *coord = [NSDictionary dictionaryWithObjectsAndKeys:
             [NSNumber numberWithFloat:tapLocation.x],@"x",
             [NSNumber numberWithFloat:tapLocation.y],@"y",nil];
   [[NSNotificationCenter defaultCenter] postNotificationName:@"TapAndHoldNotification" object:coord];
}

- (void)sendEvent:(UIEvent *)event
{
   NSSet *touches = [event touchesForWindow:self];
   [touches retain];

   [super sendEvent:event];    // Call super to make sure the event is processed as usual

   if ([touches count] == 1) { // We're only interested in one-finger events
      UITouch *touch = [touches anyObject];

      switch ([touch phase]) {
         case UITouchPhaseBegan:  // A finger touched the screen
            tapLocation = [touch locationInView:self];
            [contextualMenuTimer invalidate];
            contextualMenuTimer = [NSTimer scheduledTimerWithTimeInterval:0.8
                        target:self selector:@selector(tapAndHoldAction:)
                        userInfo:nil repeats:NO];
            break;

         case UITouchPhaseEnded:
         case UITouchPhaseMoved:
         case UITouchPhaseCancelled:
            [contextualMenuTimer invalidate];
            contextualMenuTimer = nil;
            break;
      }
   } else {                    // Multiple fingers are touching the screen
      [contextualMenuTimer invalidate];
      contextualMenuTimer = nil;
   }
   [touches release];
}
@end

Some remarks for the UITouchPhaseMoved phase: it can be sometimes useful to allow small movements on the screen. You can add some code to check for the distance the finger has moved and if it is within a certain range, you just don’t abort the timer. This helps users which have difficulties to hold the finger still for about a second.

Another important thing you have to do when the App window is created by a NIB file: you have to change the UIWindow class of the window within the NIB file in Interface Builder to the new subclass MyWindow. This way the window is created with our subclass, which is important.

The next step is to listen for the “TapAndHoldNotification” notification within the UIWebView delegate and when this notification is received, we need to check which HTML element was touched.

When initializing the UIWebView delegate, we need to add the delegate as observer for the notification…

   [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(contextualMenuAction:) name:@"TapAndHoldNotification" object:nil];
}

And here’s the method “contextualMenuAction:”…

- (void)contextualMenuAction:(NSNotification*)notification
{
   CGPoint pt;
   NSDictionary *coord = [notification object];
   pt.x = [[coord objectForKey:@"x"] floatValue];
   pt.y = [[coord objectForKey:@"y"] floatValue];

   // convert point from window to view coordinate system
   pt = [webView convertPoint:pt fromView:nil];

   // convert point from view to HTML coordinate system
   CGPoint offset  = [webView scrollOffset];
   CGSize viewSize = [webView frame].size;
   CGSize windowSize = [webView windowSize];

   CGFloat f = windowSize.width / viewSize.width;
   pt.x = pt.x * f + offset.x;
   pt.y = pt.y * f + offset.y;

   [self openContextualMenuAt:pt];
}

The method “scrollOffset” and “windowSize” are implemented as category for the UIWebView class. “scrollOffset” is required to make sure the coordinates are also correct when the web page was scrolled. The “windowSize” returns the visible width and height of the HTML document from the point of view of the HTML document. So based on the windowsSize of the “HTML window” and the view size of the UIWebView, you can calculate the zoom factor, and the zoom factor is necessary to transform and scale the screen coordinates to the correct HTML coordinates.

Here’s the implementation of “scrollOffset” and “windowSize”…

WebViewAdditions.h:

@interface UIWebView(WebViewAdditions)
- (CGSize)windowSize;
- (CGPoint)scrollOffset;
@end

WebViewAdditions.m:

#import "WebViewAdditions.h"

@implementation UIWebView(WebViewAdditions)

- (CGSize)windowSize
{
   CGSize size;
   size.width = [[self stringByEvaluatingJavaScriptFromString:@"window.innerWidth"] integerValue];
   size.height = [[self stringByEvaluatingJavaScriptFromString:@"window.innerHeight"] integerValue];
   return size;
}

- (CGPoint)scrollOffset
{
   CGPoint pt;
   pt.x = [[self stringByEvaluatingJavaScriptFromString:@"window.pageXOffset"] integerValue];
   pt.y = [[self stringByEvaluatingJavaScriptFromString:@"window.pageYOffset"] integerValue];
   return pt;
}
@end

Finally, we need to implement the method “openContextualMenuAt:” for the UIWebView delegate, which first checks for the HTML elements that are at the touch locations and the creates the contextual menu. Checking for the HTML elements at the touch location must be done via JavaScript…

JSTools.js

function MyAppGetHTMLElementsAtPoint(x,y) {
   var tags = ",";
   var e = document.elementFromPoint(x,y);
   while (e) {
      if (e.tagName) {
         tags += e.tagName + ',';
      }
      e = e.parentNode;
   }
   return tags;
}

This JavaScript function simply collects the tag names of all HTML elements at the touch coordinates and returns the tag names as string list. The JavaScript file must be added as “resource” to your XCode project. It can happen that Xcode treats JavaScript file as normal code and tries to compile and link it instead of adding it to the resources. So make sure the JavaScript file is in the “Copy Bundle Resources” section within the XCode project target and not in the “Compile Sources” or “Link Binaries” section.

- (void)openContextualMenuAt:(CGPoint)pt
{
   // Load the JavaScript code from the Resources and inject it into the web page
   NSString *path = [[NSBundle mainBundle] pathForResource:@"JSTools" ofType:@"js"];
   NSString *jsCode = [NSString stringWithContentsOfFile:path encoding:NSUTF8StringEncoding error:nil];
   [webView stringByEvaluatingJavaScriptFromString: jsCode];

   // get the Tags at the touch location
   NSString *tags = [webView stringByEvaluatingJavaScriptFromString:
            [NSString stringWithFormat:@"MyAppGetHTMLElementsAtPoint(%i,%i);",(NSInteger)pt.x,(NSInteger)pt.y]];

   // create the UIActionSheet and populate it with buttons related to the tags
   UIActionSheet *sheet = [[UIActionSheet alloc] initWithTitle:@"Contextual Menu"
                  delegate:self cancelButtonTitle:@"Cancel"
                  destructiveButtonTitle:nil otherButtonTitles:nil];

   // If a link was touched, add link-related buttons
   if ([tags rangeOfString:@",A,"].location != NSNotFound) {
      [sheet addButtonWithTitle:@"Open Link"];
      [sheet addButtonWithTitle:@"Open Link in Tab"];
      [sheet addButtonWithTitle:@"Download Link"];
   }
   // If an image was touched, add image-related buttons
   if ([tags rangeOfString:@",IMG,"].location != NSNotFound) {
      [sheet addButtonWithTitle:@"Save Picture"];
   }
   // Add buttons which should be always available
   [sheet addButtonWithTitle:@"Save Page as Bookmark"];
   [sheet addButtonWithTitle:@"Open Page in Safari"];

   [sheet showInView:webView];
   [sheet release];
}

This method injects the JavaScript code which looks for the HTML elements at the touch location into the web page and calls this function. The return value will be a string with a comma-separated list of tag names. This string will start and end with a comma so we can simply check for occurrences of a substring “,tagName,” if we want to find out if an element with a certain tag name was touched. In our example, we simple add some buttons if an “A” tag was hit and some other buttons if and “IMG” tag was hit. But what you’re doing is up to you. Also the information that is returned from the JavaScript function (in this example “MyAppGetHTMLElementsAtPoint()”) is up to you. In iCab Mobile it returns the HREF and SRC attributes of A and IMG tags, so the URLS can be directly processed.

The example doesn’t include the UIActionSheet delegate method which is called when you tab on one of the buttons in the contextual menu. But I think you should already know how to handle this. Also a few other details might be missing, but I think you should be able now to implement your own custom contextual menu for UIWebView objects with the information from the blog post.

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.

This blog post describes how this can be implemented. I’m implementing this feature as a category for the UIWebView class, so you can use the new search feature for all UIWebView objects in your Apps very easily.

First of all, UIWebView doesn’t allow us to access its content directly, so we have to use JavaScript again. But if you’ve read my other blog posts, you already know this approach.

Our goal is to implement two methods for our new UIWebView category. One method should start the search and highlights the search results. As a result this method should return the number of occurrences of the text we’ve searched. The other method should remove all the highlighted search results again to restore the original layout of the web page.

What we need to do is to write the main code in JavaScript and a wrapper code in Objective C which is simply calling the JavaScript code.

We start with the JavaScript code that is doing the real work. As I’ve already described in the blog post WebKit on the iPhone, the JavaScript code will be saved as resource file in the XCode project. This way it can be loaded from within the Objective C code from the application bundle very easily, and we don’t mix the code of multiple programming languages (JavaScript and Objective C) in the same files.

The following code is the the JavaScript implementation; below I’ll explain what it is doing and how it works:

SearchWebView.js:

// We're using a global variable to store the number of occurrences
var MyApp_SearchResultCount = 0;

// helper function, recursively searches in elements and their child nodes
function MyApp_HighlightAllOccurencesOfStringForElement(element,keyword) {
  if (element) {
    if (element.nodeType == 3) {        // Text node
      while (true) {
        var value = element.nodeValue;  // Search for keyword in text node
        var idx = value.toLowerCase().indexOf(keyword);

        if (idx < 0) break;             // not found, abort

        var span = document.createElement("span");
        var text = document.createTextNode(value.substr(idx,keyword.length));
        span.appendChild(text);
        span.setAttribute("class","MyAppHighlight");
        span.style.backgroundColor="yellow";
        span.style.color="black";
        text = document.createTextNode(value.substr(idx+keyword.length));
        element.deleteData(idx, value.length - idx);
        var next = element.nextSibling;
        element.parentNode.insertBefore(span, next);
        element.parentNode.insertBefore(text, next);
        element = text;
        MyApp_SearchResultCount++;	// update the counter
      }
    } else if (element.nodeType == 1) { // Element node
      if (element.style.display != "none" && element.nodeName.toLowerCase() != 'select') {
        for (var i=element.childNodes.length-1; i>=0; i--) {
          MyApp_HighlightAllOccurencesOfStringForElement(element.childNodes[i],keyword);
        }
      }
    }
  }
}

// the main entry point to start the search
function MyApp_HighlightAllOccurencesOfString(keyword) {
  MyApp_RemoveAllHighlights();
  MyApp_HighlightAllOccurencesOfStringForElement(document.body, keyword.toLowerCase());
}

// helper function, recursively removes the highlights in elements and their childs
function MyApp_RemoveAllHighlightsForElement(element) {
  if (element) {
    if (element.nodeType == 1) {
      if (element.getAttribute("class") == "MyAppHighlight") {
        var text = element.removeChild(element.firstChild);
        element.parentNode.insertBefore(text,element);
        element.parentNode.removeChild(element);
        return true;
      } else {
        var normalize = false;
        for (var i=element.childNodes.length-1; i>=0; i--) {
          if (MyApp_RemoveAllHighlightsForElement(element.childNodes[i])) {
            normalize = true;
          }
        }
        if (normalize) {
          element.normalize();
        }
      }
    }
  }
  return false;
}

// the main entry point to remove the highlights
function MyApp_RemoveAllHighlights() {
  MyApp_SearchResultCount = 0;
  MyApp_RemoveAllHighlightsForElement(document.body);
}

The basic principle of searching the text and removing the highlighted search results is the same: We’re working at DOM level (Document Object Model), which means the HTML document is represented as a tree structure where each HTML element, text, comment etc. is represented as a node. All the nodes are linked together with parent and child connections. The root element of each HTML document is the element that is created by the HTML tag. This element has usually two children: The HEAD element and the BODY element. Only the content of the BODY element is visible and displayed on screen, so we only need to process this part of the document tree.

What we need to do is to start with the body element and traverse all of its child nodes. From within the child nodes we need to go to their child nodes as well, and so on until we reach a leaf nodes, which has no child elements. Text nodes are always leaf nodes and text nodes are the nodes which might contain the text we’re looking for.

Traversing the whole HTML tree searching for all text nodes can be done by a recursive algorithm called Depth-First-Search (DFS). The DFS algorithm will traverse the tree structure starting from a root element (in our case the BODY element) to the first leaf node in a branch of the tree (for example going to the first child of the root first, from there again going to the first child, etc until a leaf node is reached). Then the algorithm goes back (backtracking) to the last node where not all child nodes were traversed yet and continues with the next unvisited child nodes etc. This way all nodes of the whole tree are traversed and we are able to find all the text nodes in which we are looking for the text we are earching.

The functions “MyApp_HighlightAllOccurencesOfStringForElement(element,keyword)” and “MyApp_RemoveAllHighlightsForElement(element)” are both implementations of this DFS algorithm. These functions are called from MyApp_HighlightAllOccurencesOfString(keyword)” and “MyApp_RemoveAllHighlights()” which are doing the necessary initialization and provide the DFS functions with the proper root element (the BODY element). The initialization for a new search is to make sure than no highlighted text from a previous search is present, so we simple call the function to remove all text highlights.

When searching for a text, we check if the currently inspected node is a text node or if it is an element node. If it is an element node it can have child nodes, and these must be inspected as well. If it is a text node, we have to find out if the text of this node contains the text we’re searching. If yes, we insert the text highlight, otherwise we are finished with this node. Also if the node is neither a text node nor an element node, there aren’t any child nodes which are interesting for us, so we are finished with this node as well.

When the text of a text node contains the searched text, we have to split the text into three parts. Part one will contain the text up to the searched text, part two contains the searched text itself and part three contains the rest of the text. A new element will be created (a SPAN element) and the second part (the searched text) will become a child node of this new element. Now we can assign StyleSheet rules to the newly created SPAN element to create the highlight effect (setting the background color to yellow, setting the text color to black, you can even increase the font size, if you want to). Now the new element is linked with part one and three so it becomes a part of the tree strucuture of the HTML tree. And because the searched text might be found multiple times in the original text node, we continue to search for the searched text in the third part of the original text node. If we find another occurrence of the searched text, we split this third part again in three parts, otherwise we are finished. When we create a SPAN element for the highlight effect, we also assign a special value (here “MyAppHighlight”) for the class attribute. This is important to be able to find these elements later again when we want to remove the highlight effects using the function “MyApp_RemoveAllHighlights()”. For this task we traverse the tree as well, but now we’re looking for elements whose class attribute has this special value. To restore the original state of the HTML document, we have to remove the elements we’ve inserted before (the ones with the special value of the class attribute) and we need to concatenate the text node we’ve split. JavaScript can help us to concatenate the text nodes again, because it provides the “normalize()” function which can do this for us.

In JavaScript we can find out the type of a node with the “nodeType” property. A value of 1 means that the node is a normal element node (like the “body” node, a “span” node etc.). A value of 3 means that the node is a text node. In this case the property nodeValue contains the text of the node. Other values for nodeType represent comment nodes (in HTML these are written as “<!– Comment –>”), attribute nodes (for HTML attributes like for example the “HREF” attribute for the “A” tag), document nodes and some more. In our case only the values 1 (element node) and 3 (text node) are important.

In the above implementation, we count the number of found occurrences in a global variable.

Note: You’ll notice that the JavaScript function names and variables and also the value for the class attribute I’m using in the above code are very lengthy and they do also have a prefix like “MyApp_”. The reason for this is to avoid any conflicts with existing function and variable names of the web page in which we inject our JavaScript code. If you’re generating the HTML code yourself that is displayed in the UIWebView object, you can choose shorter and simpler names. But if you have to deal with HTML and JavaScript code of any web pages (like in a web browser like iCab Mobile), you should use longer names and also add the name of your app as Prefix to all function and variable names to avoid any conflicts.

The Cocoa/Objective C part of the implementation is very simple. We only need to declare the interface and write a simple wrapper which loads and calls the JavaScript code that is actually doing all the hard work. The interface is also simple, we only need two methods: one to start the search and which highlights the found text and one which removes all the highlights again.

SearchWebView.h:

@interface UIWebView (SearchWebView)

- (NSInteger)highlightAllOccurencesOfString:(NSString*)str;
- (void)removeAllHighlights;

@end

The typical use case would be to provide a search field where the user can enter some text. This text would be passed to the method “highlightAllOccurencesOfString:”. And when the user shakes the device, the App could call the method “removeAllHighlights” to remove all the highlighted search results again.

The implementation would look like this:

SearchWebView.m:

@implementation UIWebView (SearchWebView)

- (NSInteger)highlightAllOccurencesOfString:(NSString*)str
{
    NSString *path = [[NSBundle mainBundle] pathForResource:@"SearchWebView" ofType:@"js"];
    NSString *jsCode = [NSString stringWithContentsOfFile:path encoding:NSUTF8StringEncoding error:nil];
    [self stringByEvaluatingJavaScriptFromString:jsCode];

    NSString *startSearch = [NSString stringWithFormat:@"MyApp_HighlightAllOccurencesOfString('%@')",str];
    [self stringByEvaluatingJavaScriptFromString:startSearch];

    NSString *result = [self stringByEvaluatingJavaScriptFromString:@"MyApp_SearchResultCount"];
    return [result integerValue];
}

- (void)removeAllHighlights
{
    [self stringByEvaluatingJavaScriptFromString:@"MyApp_RemoveAllHighlights()"];
}

@end

The first thing we’re doing in the method “highlightAllOccurencesOfString:” is to load the JavaScript file we’ve written above from the application bundle and inject it into the web page that is currently displayed in UIWebView. Because we’re implementing this as a category for UIWebView, we can use “self” to call the method “stringByEvaluatingJavaScriptFromString:” of the UIWebView instances.

After we’ve injected the JavaScript code we simply call the JavaScript function we’ve defined above to do the search.

And finally we access the variable we’ve defined in the JavaScript code, which represents the number of occurrences of the string that were found, and we return its integer value as the result of the method.

In the method “removeAllHighlights” we only need to call the corresponding JavaScript function we’ve defined in the JavaScript code from above. Loading the external JavaScript file and injecting it into the Web page is not necessary here. If we’ve started a search before, the code is already injected and we don’t need to do this again. And if we haven’t started a search before, we just don’t need the JavaScript code because there are no highlights which have to be removed.

As you can see, the Objective C code for the UIWebView category is just a simple wrapper code for the JavaScript code. Now, when you have a UIWebView object in your App, you can simply search for text in its content by calling “highlightAllOccurencesOfString:”, like in this example where we’re searching for the text “keyword”:

  // webView is an instance of UIWebView
  [webView highlightAllOccurencesOfString:@"keyword"];

Additional notes: In case your App has to deal with web pages which can have frames, you have to add some additional code that looks for frames. You have to traverse all the documents of all the frames to find all the text nodes in all frames. The code from above isn’t doing this to keep it as simple as possible.

When developing Apps for the iPhone and iPod Touch, it’s likely that you’re using UITableView objects to display the content of your App. UITableView is one of the most important Views of the iPhone OS and used for all kinds of lists and data that can be provided as list. In most cases you would store your data in an NSArray or NSMutableArray object and each row of the table represents an item of this array. In case your app allows the user to reorder the table entries, you would have to implement the following delegate method of the UITableView class:

- (void)tableView:(UITableView *)tableView
         moveRowAtIndexPath:(NSIndexPath *)fromIndexPath
                toIndexPath:(NSIndexPath *)toIndexPath

This delegate method is called whenever the user has enabled the “edit” mode of the table and has moved a table entry to another location. Within this method, you have to reorder the items of your own data storage (the array) so that the new representation of the table matches the order of the items within your array again. But if you look at the methods of the NSMutableArray class, you won’t find a method to do this directly. There’s no method to move an object of the array from one index to another. But because this is a task which we need very often (almost all iPhone Apps do have tables and in many cases it makes sense that the users of our App should be able to reorder the table entries), we will add a new method to the NSMutableArray class which is doing this, so we don’t have to implement the same code over and over again.

Subclassing NSMutableArray to add the new method would be possible, but is not the way I would choose here. NSMutableArray is an abstract class and a subclass would not inherit the data storage of the parent class. This means when subclassing, we would have to create and maintain our own data storage and would also have to implement all of the basic methods to set and get array items. Many of the basic data storage classes of the Cocoa Frameworks are abstract classes, so be aware when you plan to subclass these classes. Remember that you have to provide your own data storage if you do so.

But Objective-C provides other ways to add methods to an existing class, so subclassing is not necessary. We can define a category for the new method. A category can be used to add new methods to existing classes without subclassing them. This has the benefit that these new methods are even available for objects which are created by code which we can’t control, like objects created and returned by the system frameworks. But the downside is that a category can not add any additional member variables or additional data storage to the class. The reason is simple, the memory that is occupied by an object of the base class must remain the same. The other frameworks and code which doesn’t know about the new methods are still allocating only the memory for the base class when they create a new object. So a category can only add new behavior (methods), but no new data (member variables).

For our task, a category is just what we need: we don’t need additional variables or data storage, we just need to implement a new behavior (method) to move an array object from one index to another index. We name this new method “moveObjectFromIndex:toIndex:”

The implementation of the category would look like this:

MoveArray.h:

@interface NSMutableArray (MoveArray)

- (void)moveObjectFromIndex:(NSUInteger)from toIndex:(NSUInteger)to;

@end

MoveArray.m:

#import "MoveArray.h"

@implementation NSMutableArray (MoveArray)

- (void)moveObjectFromIndex:(NSUInteger)from toIndex:(NSUInteger)to
{
    if (to != from) {
        id obj = [self objectAtIndex:from];
        [obj retain];
        [self removeObjectAtIndex:from];
        if (to >= [self count]) {
            [self addObject:obj];
        } else {
            [self insertObject:obj atIndex:to];
        }
        [obj release];
    }
}
@end

The code is very simple: we first remove the object from its original location and insert it at the new location or add it to the end of the array when the new location is beyond the array bounds. As you can see, though we do not subclass NSMutableArray, we can still use the “self” keyword just like we would have done this in a subclass. Also note when defining a category there’s no block where you can define member variables (within “{…}” like you can do this when subclassing), but instead you can only give the category a name (in this case “(MoveArray)”). This is because you can’t change the memory allocation for the class (see above).

Now, whenever we need to move an array object from one index to another (in a NSMutableArray object), we can simply call

[array moveObjectFromIndex:from toIndex:to];

As you can see, though we haven’t sub-classed NSMutableArray, the new method is called exactly in the same way as any other methods of the NSMutableArray class. This makes categories a very powerful and flexible feature.

For our initial UITableView example, implementing the UITableView delegate method “tableView:moveRowAtIndexPath:toIndexPath:” would be very simple now. In most cases we could just do the following:

- (void)tableView:(UITableView *)table
               moveRowAtIndexPath:(NSIndexPath *)sourceIndexPath
                      toIndexPath:(NSIndexPath *)destinationIndexPath
{
    [array moveObjectFromIndex:[sourceIndexPath row]
                       toIndex:[destinationIndexPath row]];
}

So how are iCab Mobile and other apps able to populate a UINavigationBar object with any UI elements in other than the three available spots?

First of all, not everything which looks like a UINavigationBar is a UINavigationBar. Up to iCab Mobile 1.7 the toolbar at the top of the screen is not a UINavigationBar object, it’s a UIImageView object with an image that looks like a UINavigationBar would look like. But since iCab Mobile 2.0 it will be a UINavigationBar. iCab Mobile 2.0 will allow to customize the colors of the toolbars, and unlike images, the UINavigationBar object can have any color.

But even for UIImageView objects, you can’t add any subviews in Interface Builder. So the main question is the same: how to add any available UI elements in any location as subview of these objects (it doesn’t matter if these objects are UIImageView or UINavigationBar objects)?

The answer is simple: you have to do this programatically. UIImageView and UINavigationBar are both subclasses of UIView. And UIView objects can have subviews. You only need to call the method addSubview: to add a subview. When using UINavigationBar as the root for our toolbar, we only have to make sure that it is not managed by a UINavigationController. But because we need to create all the objects programmatically, this isn’t a problem at all.

One place to create the toolbar can be the viewDidLoad method of the UIViewController which serves as the controller for the view that holds the toolbar. The following code is an example how this would look like. All the code fragments should go into the viewDidLoad method, I’ve split the code into fragments only because it’s easier to explain what I’m doing this way.

- (void)viewDidLoad
{
  [super viewDidLoad];

  CGFloat width = self.view.frame.size.width;

Here we first get the width of the view of our UIViewController. It is used to calculate the widths of all of the toolbar elements.

  UINavigationBar *navBar = [[UINavigationBar alloc] initWithFrame:
                                           CGRectMake(0,0,width,52)];
  navBar.autoresizingMask = UIViewAutoresizingFlexibleWidth;
  [self.view addSubview:navBar];
  [navBar release];

This fragment creates the UINavigationBar element and we add it as subview to the view object of our UIViewController. If the application should support the autorotation feature, we have to make sure that the width is flexible and set the autoresizing mask accordingly.

  UILabel *label = [[UILabel alloc] initWithFrame:
                                   CGRectMake(10,2,width-20,14)];
  label.autoresizingMask = UIViewAutoresizingFlexibleWidth;
  label.text = @"some text for the title...";
  label.backgroundColor = [UIColor clearColor];
  label.font = [UIFont systemFontOfSize:12];
  label.textAlignment = UITextAlignmentCenter;
  [navBar addSubview:label];
  [label release];

Then we create the title line of our toolbar. We use a UILabel element. The width must be flexible as well when the autorotation feature is supported. The label is added as a subview of the UINavigationBar object so that there is a small margin at the top, left and right side. It is important to set the background color to “clearColor” to make the background completely transparent. The default background color would be white.

  UITextField *textField = [[UITextField alloc] initWithFrame:
                                CGRectMake(10,19,width-80,26)];
  textField.autoresizingMask = UIViewAutoresizingFlexibleWidth;
  textField.borderStyle = UITextBorderStyleRoundedRect;
  textField.font = [UIFont systemFontOfSize:17];
  [navBar addSubview:textField];
  [textField release];

This fragment will add a text field to enter some text into the toolbar. This is similar to what we’ve done to add the label.

  UIButton *button = [UIButton buttonWithType:UIButtonTypeRoundedRect];
  [button setFrame:CGRectMake(width-60,19,50,26)];
  [button setTitle:@"Go" forState:UIControlStateNormal];
  button.autoresizingMask = UIViewAutoresizingFlexibleLeftMargin;
  [navBar addSubview:button];
}

And finally we’ve added a button to the toolbar. Nothing special here. This time the autoresizing mask is set to have a flexible left margin, because the button should always have the same width. It only should be placed on the right side of the toolbar, so the right margin must be fixed, while the left must be flexible.

This is more or less all you need to do to add UI elements in UINavigationBar objects. Of course you also need to set the delegates for some of the UI elements in order to process clicks on the button or text field editing.

This is how the toolbar from above will look like:

But there is a problem: the screen area of the small iPhone screen is limited and only a limited number of buttons will fit on the screen. In portrait mode (like in the screenshot from above), about 6-7 buttons will fit on the screen, which is usually more than enough for most tasks. But in landscape mode the number of buttons can be an issue. Because of the reduced height of the screen in landscape mode, less buttons will fit on the screen. Under iPhone OS 2.x the top most buttons might be no longer accessible because they are located outside of the screen. Since iPhone OS 3.0, Apple has solved this issue by converting the buttons into a scrollable list, if the available space isn’t enough for all buttons.

Here’s how this looks like under iPhone OS 2.x:

Here’s how this looks linke under iPhone OS 3.x:

If you write an app which requires at least OS 3.0, you can just ignore this problem. But if your app should still support OS 2.x (especially iPod Touch users are slow in upgrading, because the OS 3.x update is not free for iPod Touch users), you have to take care about this problem.

Reducing the number of buttons in landscape mode is usually not an option, and moving half of the buttons into a second UIActionSheet object which will open when you click a button labeled “More options…” can be an easy solution, but it makes navigation through all the options less comfortable to the user.

A simple solution for this problem would be to open the UIActionSheet in portrait mode orientation under OS 2.x while the app itself remains in landscape mode. This way the user would always get the full list of buttons, no special reduced button set for different orientations would be needed, and also no need to introduce multi UIActionSheet objects which are linked together with some buttons.

This can look like this in iPhone OS 2.x (Note: in the background you can see that the app is still in landscape mode):

How can this be done? When you open a UIActionSheet, you can do the following:

  UIActionSheet *sheet = [[UIActionSheet alloc] initWithTitle:@"Some text..."
                           delegate:self
                  cancelButtonTitle:@"Cancel"
             destructiveButtonTitle:@"Delete"
                  otherButtonTitles:@"Button 1",@"Button 2",nil];

  if ([[[UIDevice currentDevice] systemVersion] floatValue] >= 3.0 ||
      UIDeviceOrientationIsPortrait([[UIDevice currentDevice] orientation])) {
    [sheet showInView:self.view];
  } else {
    [sheet showInView:self.view.window];
  }
  [sheet release];

This code fragment will first create the UIActionSheet object (as usual). Then we check if we’re running under OS 3.x or newer, or if the current orientation is the portrait mode. If this is the case we just show the UIActionSheet within the view of the current view controller (this is what we would have done normally). But when running under OS 2.x and the device is currently in landscape mode, we do not show the UIActionSheet in the current view, but instead it is shown in the window object (which is also a subclass of UIView). Unlike the normal “UIView” objects where the coordinate system will be automatically transformed according to the current device orientation so that the top left corner will have the coordinate (0,0), the coordinate system of the window object (the root object of the view hierarchy) won’t be transformed. It will always remain the same and is based on the standard portrait orientation. So when we open the UIActionSheet here, it will be shown as if the device would be in portrait mode.

This way we can use UIActionSheets with more than 3-4 buttons in landscape mode safely under OS 3.x and also under OS 2.x without risking that some buttons are no longer accessible.

Here you can download an archive of an example project which demonstrates this technique: ActionSheetTest.zip (12 KB)

Let the example app run under OS 2.x and tap on the two buttons of the main view to find out how the UIActionSheet will look like in landscape and portrait mode with and without the technique described above. Also compare this when running the app under OS 3.x.

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.

But implementing filters seems to be impossible. When you look at the public API of the UIWebView class, you won’t see anything which would allow to find out which resources the UIWebView object is loading, and even worse, nothing is available which can be used to force the UIWebView not to load these resources when you want to filter them out.

But of course there is a solution, otherwise this blog post wouldn’t make much sense .

To implement filters we don’t have to look at UIWebView. As I mentioned above, nothing in the UIWebView API would allow to implement filtering.

To find a hook where we can intercept all the HTTP requests which are done by UIWebView we have to know a little bit about the URL loading system of Cocoa because UIWebView is using the URL loading system to get all the data from the web. One part of the URL loading system is the NSURLCache class, and this is our hook we’re looking for. Though the iPhone OS doesn’t cache any data on “disk” at the moment (this can be different in later iPhone OS release) and therefore the cache that is managed by the NSURLCache class is usually empty, UIWebView nevertheless checks if the requested resources are in the cache. So all we need to do is to subclass NSURLCache and overwrite the method

- (NSCachedURLResponse*)cachedResponseForRequest:(NSURLRequest*)request

This method is called for all resources the UIWebView is requesting. So all we need to do is to check if the URL of the request matches one of the filters. If it does, we create a fake response with no content, otherwise we just call the super class.  This is basically all we need to do.

Here’re some more details:

1. Subclassing NSURLCache:
In the Header file there’s almost nothing to do:

FilteredWebCache.h:

@interface FilteredWebCache : NSURLCache
{
}
@end

Now the main code for the subclass:

FilteredWebCache.m:

#import "FilteredWebCache.h"
#import "FilterManager.h"

@implementation FilteredWebCache

- (NSCachedURLResponse*)cachedResponseForRequest:(NSURLRequest*)request
{
    NSURL *url = [request URL];
    BOOL blockURL = [[FilterMgr sharedFilterMgr] shouldBlockURL:url];
    if (blockURL) {
        NSURLResponse *response =
              [[NSURLResponse alloc] initWithURL:url
                                        MIMEType:@"text/plain"
                           expectedContentLength:1
                                textEncodingName:nil];

        NSCachedURLResponse *cachedResponse =
              [[NSCachedURLResponse alloc] initWithResponse:response
                             data:[NSData dataWithBytes:" " length:1]];

        [super storeCachedResponse:cachedResponse forRequest:request];

        [cachedResponse release];
        [response release];
    }
    return [super cachedResponseForRequest:request];
}
@end

The code first checks if the URL should be blocked (the FilterManager class is doing all these checks, this class isn’t shown here). If yes, it creates a new response object with no content and stores this in the cache. One could assume that it should be possible to just return the fake response object and we don’t need to store it in the cache. But if we do this, the app would crash very soon because our fake response object is over-released by the iPhone OS. I don’t know why exactly this happens, this might be a bug in the iPhone OS (and also in MacOSX 10.5.x where the same thing happens. This works fine in 10.4.x and all older MacOSX releases) or caused by some undocumented internal dependencies between the different classes of the URL loading system. So we just store our fake response in the Cache. This makes sure that all response objects we return are really stored in the Cache and this is what the iPhone OS expects and then it won’t crash.

Update: It seems that it is also necessary that the “fake” response is initialized with a NSData object which has a size larger than zero.

2. Creating a new Cache:
We also need to create a new cache and tell the iPhone OS that it has to use this new cache instead of the default one so we really get called when the URL loading system checks the cache for a resource. This should be done before any of the UIWebView objects are starting to load web pages, very early within the launching process of the app.

NSString *path = ...// the path to the cache file
NSUInteger discCapacity = 10*1024*1024;
NSUInteger memoryCapacity = 512*1024;

FilteredWebCache *cache =
      [[FilteredWebCache alloc] initWithMemoryCapacity: memoryCapacity
                             diskCapacity: discCapacity diskPath:path];
[NSURLCache setSharedURLCache:cache];
[cache release];

We have to provide a path where the cache file is stored. The cache file is automatically created by the NSURLCache objects, so we don’t need to create the file, we only have to define where the file should be saved (this must be somewhere in the “sandbox” of our application, for example in the “tmp” folder or in the “Documents” folder).

This is all the magic to implement URL-based filters for UIWebView on the iPhone. You see, it’s not that complicated.

Note: If the filters can change while your app is running, you may need to remove the fake responses from the cache again. The NSURLCache class provides a method for this, so this isn’t a problem. If your filters are static, then you don’t need to care about this.