September 15th, 2009
Using yml:include to create an automatically updating YAP small view
One of the biggest issues that many people have with the small view of a YAP open application is that the view is cached on Yahoo! servers and can only be updated with manual intervention from either the application owner or the application user. In the past, application owners had a few options for updating this small view. The most common were:
- When the user visited the canvas view of the application the owner would have a setSmallView call set up to refresh the small view of the user (process described here: http://www.nakedtechnologist.com/?p=181. The problem with this is that it requires the user to go to the canvas view. Many users would just view their small view on My Yahoo! so the content of the app was either generic or stale.
- The owner would set up a cron job to update the small view of their app users on regular intervals (process described here: http://www.nakedtechnologist.com/?p=220). The issue with this one is that the content will only be updated at regular times and will be stale for a user in between those times.
- The owner would implement a yml:a tag to call a server-side script to update the small view of the user when the user clicked on the link (process described here: http://www.nakedtechnologist.com/?p=204). This relied on user interaction to function and in many cases links on the small view would need to be added just for this requirement.
Many developers, myself included, opted for a mix of all of the options above. This worked fairly well to mimic a dynamic small view, but having three solutions for a single problem was unwieldy.
Enter the yml:include tag
The purpose of this tag is to dynamically load content onto a page. This tag can be used in both the canvas and small views, but the real benefit to its use is the small view.
I would recommend looking over the documentation for yml:include as there is quite a lot of detail that a developer would find useful: http://developer.yahoo.com/yap/guide/include.html
The features that are most important to note here are:
- insert – if a node id is specified in the insert parameter, the content of the include request will load into that node.
- delay – the amount of time to delay the loading of the content (in milliseconds)
These parameters will help in setting up a dynamic small view for the user. Using these, I’ll go through two examples on how to use yml:include. The first will cover a simple single load case and the second will display how to build a continually updating small view set to update on a specific delay.
Simple Use Case – Single Dynamic Load
This first example will display a simple use case for yml:include. We will use the setSmallView call to insert an include tag into the small view of the current user.
The PHP layer to this is just to insert that yml:include tag the first time, and is only needed once. This will replace the cached small view of the user with the include tag. For my applications, I ran this in a cron job to update the small view for all users at once. Doing so replaced my need to constantly update the small view of my users on a daily basis.
The full details for setting up this example can be found here: http://www.nakedtechnologist.com/?p=181. This piece is the PHP layer that just sets the small view of the user with a yml:include tag and the div node that the content will be inserted into.
$html = '<yml:include params="training_sdk.php" insert="loadHere"></yml:include><div id="loadHere">REPLACE</div>';
if (!$yahoo_user->setSmallView($html)){
echo "NO SMALL VIEW";
}
When the dropzone (my.yahoo) and application load, an AJAX GET request will be made to training_sdk.php. This file will return the content of the small view and then be inserted into the div with the id of “loadHere” (as denoted by the insert parameter). This allows us to generate whatever content we want within training_sdk.php and the small view will reflect that change as soon as the user loads the application.
Extended Use Case – Updating the Small View Every x seconds on a delay
Now we’re going to look into an extended use case for yml:include. This version will extend upon the basic example to refresh the small view automatically every 5000 milliseconds (every 5 seconds). We will start off with the same code that we insert into the small view to include the yml:include tag. From that point we take a look at the file that we capture the content of the small view from, training_sdk.php.
<yml:include params="training_sdk.php" insert="loadHere" delay="5000"></yml:include> <?= time(); ?>
What we’re doing here is inserting another yml:include tag onto the page. Just like the first tag we are calling the same file, training_sdk.php, and inserting it into the same DOM node. The difference here is that we are delaying the load of this request by 5 seconds with the delay parameter. Following that all we do is display the current UNIX timestamp. What’s going to happen when this content is inserted into the small view is that the new yml:include will count down 5 seconds and then make an AJAX call to the same file and insert another UNIX timestamp and yml:include tag (which is delayed 5 seconds). So there we have it, we now have a small view that will update itself automatically every 5 seconds.
There’s only one catch here. There is a limit on the number of times you can call yml:include within a span of time. If too many consecutive yml:include calls are made, you will see the following error message:
error-243: maxIncludes limit hit for appid XXX
If you see this message, you have made too many yml:include calls within the particular dropzone. Currently the front page will allow unlimited yml:include calls and http://my.yahoo.com will allow 10 calls per session. My Yahoo! is looking into this at the moment so keep checking back to see if there have been changes with this tag. If you see this error, increase the delay on your yml:includes and that should solve the issue.
- Jonathan LeBlanc
