Check out the protocol reference here.

I use /user and /post protocol handlers in Tweaky to display my tweets and compose a tweet, respectively (e.g., click twitter://user?screen_name=aral to view my timeline in Twitter for Mac).

Note: all arguments to the protocol handlers must be URL encoded and doing that is not as straightforward as it should be with Cocoa. Simon Woodside has a little snippet that does the trick:

NSString * encodedString = (NSString *)CFURLCreateStringByAddingPercentEscapes(
   NULL,
   (CFStringRef)unencodedString,
   NULL,
   (CFStringRef)@"!*'();:@&=+$,/?%#[]",
   kCFStringEncodingUTF8 );

Enjoy!

Today I had to use a private API while spiking a feature for an iPhone app I'm working on and I ran into a couple of gotchas along the way. There doesn't seem to be a simple step-by-step guide for using private iPhone APIs in XCode, so here's goes:

1. First off, you're going to need the header files for the private frameworks. To dump them, use the Framework Dump Kit from Erica Sadun's site. Download the DumpFrameworks Perl script anywhere and put the class-dump binary somewhere on your path (I put it in /usr/local/bin/)
2. Run DumpFrameworks (navigate to the folder you downloaded it to in Terminal and type ./DumpFrameworks). This will create the headers in ~/Headers.
3. In your XCode project, right-click the Frameworks folder in the Groups & Files panel and select Add → Existing Frameworks. Navigate to the header file(s) you want to add and select them. You should see the headers added to your project.
4. Go to Project → Edit Project Settings, click on the Build tab, and scroll down to the Linking section. For the Other Linker Flags property, enter -force_flat_namespace and -undefined suppress (thank you, Ken Ferry). If you forget this, you will get a linker error telling you that the symbols for the private classes you're using could not be found.
5. Open up the header files you imported into your project and remove the superfluous import statements that the header dumper put there. Usually this is just an unnecessary #import "NSObject.h" but there may be others also. If you get errors, look for the SomeHeader.h: No such file or directory messages and remove the import statements corresponding to those errors from the private header files.
6. Finally, import the private header files, use the classes in your application, build and run!

Of course, whether or not you should use the iPhone private API is another matter (undocumented calls may break at any time, Apple may reject your app, etc.) If you do want to play around with them, however, I hope the above instructions help you to get started without too much pain.

Sucking from the pipe...

Yahoo! Pipes, the excellent visual data mashup creator, has an unfortunate blockage problem. Specifically, it can pull in data from numerous sources, but the flow stops at the end of the pipe, waiting to be sucked out and consumed instead of automatically flowing out to its final destination.

When you create a Yahoo! Pipe, you can choose to consume sources such as RSS feeds, CSVs, or even regular web pages. You can then sort, filter, and generally mash up this data to create your own output feed.

Unfortunately, this is where the flow in Yahoo! Pipes stops. The output feed you create is made available in various formats, including RSS, JSON, and PHP. All formats that you need to pull in to consume.

... versus letting the pipe flow.

What Yahoo! Pipes could do is go one step further and use HTTP and the concept of web hooks to push the data out to custom endpoints. In other words, it could keep the data flowing.

In other words, once I have consumed my various data sources, mashed them up, and created an output feed, I should be able to push that to an HTTP endpoint on my web application. As the data changes (based on the frequency that Yahoo! updates the pipe), my application gets a notification and the latest data is pushed to it, removing the need for me to implement polling in my application and thus greatly simplifying things at the application level.

If you'd like to learn more about web hooks, Jeff Lindsay, recently gave a talk introducing web hooks at the <head> web conference in a presentation titled Web Hooks and the Programmable World of Tomorrow (<head> 2008 attendees can watch the video of Jeff's talk here).

I had blogged about this just a few days ago when I ran into the issue.

Thanks, guys! :)

Googling around, I couldn't find any announcements from Yahoo! about this. I don't know if there's a notification feed somewhere that I'm missing -- if so, I'd appreciate it if someone could point me in the right direction. Otherwise, in case any other developres are using the Yahoo! GeoPlanet JSON API and are affected by this, here's a summary of the change from the post I just made on the yws-geo forum:

I just realized that you removed the 'place' array from the JSON object returned from places.q() calls (e.g., of form http://where.yahooapis.com/v1/places.q('city
name');count=0?format=json) and that the returned places object now has the
place indices as strings.

This requires code to be changed from, for example, result['places']['place'] to result['places'] and also requires that numeric indexed loops be changed to use string indices.

It's quite baffling that a change like this (which, really, isn't even necessary) was made and not communicated. Even more so considering that the API is versioned properly (you access it from /v1/), so a change like this should really have gone into (/v2/).

I would love to hear from someone on the Yahoo! GeoPlanet team about the rationale behind this change and where we can find out about similar changes in the future.

I love the Yahoo! GeoPlanet API -- it is awesome and very simple to work with -- but please, guys, pay a bit more attention to backwards compatibility, communicate better, and don't break existing apps! :)

Due to the manageable number of entries, we're going to forego the first round of public voting (although you are welcome to leave comments on the entries) and allow our outstanding panel of judges to pick the winners from the Web, API, and Mobile categories in a single round of voting.

We received 8 9 10 entries in the web category, 3 4 in the mobile category, and we now have 8 new SWX APIs thanks to the contest, ranging from a generic XML to SWX parser called SWXml to APIs for popular services such as WordPress, Backpack, Technorati, Kuler, and Verisign/Paypal Payments Pro.

I want to take this opportunity to thank all the contestants for their hard work. Here's wishing all of you the best of luck!

The winners will be announced on December 24th, 2007.

Also, a big thank you to our sponsors: Adobe UK, Lynda.com, Burak Kalayci (ASV), Friends of ED, and yours truly (Nabaztag bunnies and iPod Touches).

View the SWX Contest entries.

Update: I messed up and forgot to add Julio Rodriguez's entry to the Web category this morning. I've now updated the page with his entry and informed the judges. Thanks for getting in touch with me Julio and apologies for the initial omission.

Update: John Hattan's entries in the Web and Mobile categories also somehow ended up in the black hole of my email. Sorry, John, I've added them to the contest page and informed the judges now.

In my predictions for 2008, I talked about how we will be seeing more RIAs in 2008 -- both from Adobe and third parties -- how Silverlight is not going to have a widespread impact (although is definitely something to keep an eye on for 2009/10 and the competition is going to give Adobe a welcome push in the right direction), how mobile Flash is going to move away from Flash Lite to full-scale Flash playback on devices and how we're going to see Flash on the iPhone, how sometimes-connected applications and web/desktop hybrid applications are going to gain importance with AIR, Google Gears, etc., and how real-time 3D in Flash is going to change the aesthetics of the web.

If you've been reading my blog for a while, you might remember that last phrase. It's the same thing I uttered back in 2005 before the release of Flash 8. Back then, .Net magazine pasted my prediction on its cover and I was talking about alpha-channel video, not 3D. I think we can agree that alpha channel video in Flash has altered the aesthetics of the web in the intervening period and I am convinced that 2008 is the year that Flash is going to do the same thing with 3D thanks to Papervision3D.

Specifically, the combination of alpha-channel video, bitmap effects and filters, and real-time 3D is going to create a new benchmark in production values for online experiences. We're already seeing trailblazers like Carlos Ulloa, Ralph Hauwert, and John Grden are pushing the boundaries in this area and, in 2008, we are going to see more mainstream adoption of these techniques.

(I just read a somewhat myopic article in 3D World magazine titled "The look of 3D in 2008" that didn't even touch upon web 3D in any of its predictions! Could it be that web 3D is going to blindsight the traditional 3D community?)

To these predictions, I add two new ones that are closer to my heart: Firstly, Flash developers are going to get a lovely toy-box of APIs to work with and, secondly, we're going to witness a conference that's also going to be a technological tour-de-force to very visibly and publicly define how far we've come in Web '08. The latter has me more excited than I've been in a _very_ long time. And that's all I'm going to say about that for the moment.

The web just keeps getting more and more exciting... here's to a most wonderful 2008!

* Just as an aside, can we please drop the version numbers? We know in software that the moment an application gets its version number it's out of date. So why do we want to apply the same paradigm to describing the web? It's far more accurate, imho, to analyze the characteristics that defined the web in a given year. Hence, Web '08, not Web 3.0).

Here's quick update on the session I'm presenting at FlashBrighton's Big Day Out (the event's now sold out) this Saturday. The talk is titled Beyond the Buttons:

Learning new programming languages, development tools, and technologies is a fun (and essential) part of what we do but they are not ends in and of themselves. IDEs like Flash and Flex Builder, languages like ActionScript 3, and technologies like AIR are merely tools, like the painter's brushes, easels, and paints, the animator's lightbox, and the photographer's camera. In this session, Aral looks beyond the tools to what you can make with them. You will not learn any new techniques or programming tricks but instead stock up on ideas and inspiration to spark your own creative endeavors.

Looking forward to seeing some of you this weekend!

Using mock data

In the SWX Service Explorer, methods that have mock data will have a "Use mock data" button enabled.

Clicking the button will fill the arguments with the mock data, as the following screenshot demonstrates.

Creating static mock data

The first way to create mock data is to include it in the JavaDoc-style comments in your service classes. Place mock data at the end of the comment and surround it in square brackets.

/**
   * Do a direct credit card payment.
   *
   * @param (str) A unique order id [12345-12345]
   * @param (str) Credit card number [5105105105105100]
   * @param (str) Card type (Visa, American Express, Mastercard, etc.) [Mastercard]
   * @param (str) 3 or 4 character Credit Security Code [123]
   * @param (number, 4 digits MMYY) Expiry date [1209]
   * @param (number) Amount to charge [2.50]

This is a quick and easy way of adding mock data to a method. The recommended practice here, when possible, is to place enough mock data in a method to allow the user to make a successful call via the SWX Service Explorer. This is in keeping with the SWX philosophy of making things Just Work and Show, Don't Tell.

Generating mock data

The new mock data feature does not limit you to static mock data. You can also generate dynamic mock data with a little bit of PHP.

To generate mock data for a method called doDirectPayment(), for example, you can include a private method called _doDirectPaymentMock() in your service class. This method gets called (and passed an array of any static mock data for the method, which you can either add to or ignore) by the service explorer. It expects an array of mock data (one for each argument) to be returned as per the following example.

function _doDirectPaymentMock($mockData)
{
    // Generate a random order number
    $orderNum = '"'.date('ymd-H').rand(1000,9999).'"';
    $mockData[0] = $orderNum;
 
    return $mockData;
}

In the above example, the order number needs to be unique so it's generated by code but all the other default values are statically obtained from the comments.

Update: In the latest version of the SWX Service Explorer in SVN, the dynamic mock data now updates every time you press the Use mock data button.

Default values for optional arguments

I've also modified how default parameters are handled in the SWX Service Explorer. Previously, they were handled Really Badly (tm). i.e., they were basically ignored. Now, if your method has a default value defined, it is displayed in the SWX Service Explorer by default. This is true even if you define the default value as a constant (in PHP4, you must stick to the CONSTANT_NAMING_CONVENTIONS for constant resolution to work correctly.)

(Note that in PHP5, you must place all optional arguments at the end of your method signature. This is a best practice to follow in any case.)

The following screenshot shows how default values for arguments are handled in the new service explorer:

Currently, the changes outlined in this post are only available from the trunk of the SWX Subversion repository. I'd appreciate it if you guys can test it out. After further testing, it will be included in the next SWX PHP release.

I was looking for a distraction from the PayPal integration stuff I'm working on today for my Super Secret New Project (tm) when I ran across Ted Patrick's Cards API post from yesterday and decided to quickly implement a SWX API for it.

Ted has created a very simple REST API for a deck of cards. It currently has one method which returns a shuffled deck (or decks) of cards.

The SWX API for it was a cinch to write. Here's the PHP code for it:

<?php 
 
require_once("../BaseService.php");
 
class Cards extends BaseService
{
    function shuffle($numDecks = 1, $numJokers = 0)
    {
        $url = "http://onflex.org/api/games/cards/shuffle/1/$numDecks/$numJokers";
 
        $result = $this->_call($url);
 
        $shuffledDeck = explode('|', $result);
        $timeStamp = array_shift($shuffledDeck);
 
        return (array('timeStamp' => $timeStamp, 'deck' => $shuffledDeck));
    }
}
?>

I wasn't sure if the timestamp was in there just to stop caching or whether it would be useful so I left it in :)

You can play with it online using the SWX Service Explorer on the Public SWX Gateway.

The demo SWF you see at the top of the post calls the service using the following code:

import org.swxformat.SWX;
 
var swx:SWX = new SWX();
swx.gateway = "http://swxformat.org/php/swx.php";
swx.encoding = "GET";
swx.debug = true;
 
var callDetails:Object =
{
    serviceClass: "Cards",
    method: "shuffle",
    result: [this, resultHandler]
}
 
// ... other stuff (UI, etc.)
 
swx.call(callDetails);

And, since the data is returned in a native SWF array, the result handler simply iterates over the array to display the cards:

function resultHandler(event:Object)
{
    var deck:Array = event.result.deck;
 
    for (var i:Number = 0; i < 52; i++)
    {
        var cardInit:Object = {_x: x += 50, _y: y, _width: 50, _height: 75};
        if (i%12 == 0)
        {
            cardInit._y = y += 75;
            cardInit._x = x = 0;
        }
        _root.attachMovie(deck[i], "card"+i, i, cardInit);
    }
}

Don't forget, like all the other SWX APIs, you can call this API from Flash 6+ (including FlashLite 2.0 and 2.1) using ActionScript 1 or 2 (not 3 yet).

Download the demo (zipped; 2.6MB).

The demo includes the SWX ActionScript Library which comes with other SWX sample apps that you can play with.