Drat! You made a bunch of simple layers and now you realize they’re boring.
They’re static, predictable and well… boring. You feel empty inside.

Fret not! There’s actions and asynchronous calls to lighten up your world!

Imagine the awesomeness of building a layar that augments “Add to wishlist” buttons next to the pictures in a fashion magazine. When clicking the button the intended piece of garment gets added to someone’s Christmas wishlist and the button get replaced by a “Remove from wishlist”.

Note: It would even be cooler if you’d get a dollar every time someone actually purchases an item from their wishlist.

Well, it can be done using actions and asynchronous calls and this little tutorial shows you how

Intended audience: Beginning Layar developers that have already made some/a simple, static layer.

Asynchronous call flow

What we’re going to do is:

1. Add an action to the augment (or “POI” or “hotspot”) that triggers when clicked.
2. Perform an asynchronous call to the server to retrieve the new button
3. Replace the “Add to wishlist” button with “Remove from wishlist”

“onClick” actions

Reading the documentation you might think you always need this little BIW (that little info box at the bottom of the screen) when using actions but that is NOT the case. You can simply attach actions that trigger when clicked. You just need a little “trick” for it.

Have exactly one action in the actions array and set showBiwOnClick to false and voilá! The action will be triggered when the augment is clicked.

The actions array for your POI should look like this:

... "actions": [{ "uri": "http://www.myLayarHost.com/myLayer/?action=update&addToWishlist=shinyBottleThingyOnPage12", "label": "site", "contentType": "application/vnd.layar.async" }], ...

And to disable the BIW also add/change the following to your hotspot:

 "showBiwOnClick":false

Asynchronous calls

For those of you that are familiar with AJAX (A JavaScript technique) the concept will sound very familiar.

An asynchronous call is a call to the server to fetch new information and is performed while the Layer keeps functioning. Until the call is finished and the new response is returned nothing will structurally change within the layer.

Your actions array will need to have a URL that addresses your server and that contains the information your script(s) need to be able to return the new or updated information. In our case that is a GET parameter addedItem=shinyBottleThingyOnPage12

Another thing your URL will need is an action parameter. In our case that is action=update. This is a reserved parameter.

The action parameter will both reach your server and be used by the client to determine what to do with the incoming new information.

action = refresh

When action equals “refresh” the client will drop all augments and (re)create only those that were received. You will want to avoid this if you develop somewhat more interactive/elaborate layers.

action = update

In case action equals “update“, the new information is superimposed on the old information. This is particularly cool if you develop interactive layers.

The key to this superimposing is the ID of an augment.

• If a hotspot (or POI or augment) is received with an ID that already exists, the differences (if any) will be applied to the already existing augment. This is particularly cool when used in combination with animations. You can make things animate to their new position for example
• If a hotspot (or POI or augment) is received with an ID that doesn’t exist yet, it will be created.
• If an already existing POI is not available anymore in the latest response the client will assume nothing has changed.

To explicitly delete a POI after an update you need to add it’s id to the optional “deletedHotspots” array. That way the POI gets removed from the scene and it will trigger the onDelete animations (if set), allowing you to make your button die with style.

In the next post I’ll post a working example for you to cut and paste and a little video.