Ripple has two parts to its codebase, the AS classes and some JS code that is included on every page. It's primary purpose is to help you structure Flash content in such a way that search engines can index it effectively, and deep-link to specific content.

Ripple works by externalising all data as XHTML. It could also be any other type of XML, but you have to be able to add <link> tags and be able to run JS. (you could get the best of both using a server-side solution and returning XML when it is requested by flash, but I have not been implementing it that way myself).

Each XHTML page contains a little piece of Javascript, which redirects the user to a main page, containing your flash movie. In the redirection, the JS passes the page's own URL in the query. This is passed to Flash, and the movie knows to load that data. In this way, you can link to any page by linking directly to the XHTML data. When google finds the page, it will not run the JS, but users will. (in a server-side solution, you would detect if the user agent is google and serve a different page accordingly)

Ripple does not attempt to render XHTML or treat it in any special way. It's just data. But XHTML does not always reflect the best structure for your data, and it can be awkward to query. Ripple handles this for you using a descriptor file. A descriptor is a tiny XML file that lists XPath statements, which will tell the Ripple AS classes how to access your data. A descriptor is linked to each XHTML page using a <link> tag. In your own Actionscript code, you do not have to worry about this descriptor, and you don't have to deal with the xpath - that all happens behind the scenes. In your code, you just ask for the data you need by id.

The main AS2 class is DocManager. DocManager handles the loading of all data into your movie. To make the most of Ripple, you need to structure your movie so that ALL data is loaded through this object. The initial page is loaded automatically when the DocManager instance is created.

DocManager has a few events that you use to control your application. These are “load” and “startLoad”. “load” is triggered when a document has loaded, and is ready for display. “startLoad” is triggered when a document starts loading, so you can start a transition effect or show a progress bar.

DocManager also keeps a history (with back() and forward() - see History class), which lets you move through previous pages, and a reference to the current Document intstance.

Document represents a fully loaded xml document. You can access its XML data directly, via its “data” property, though that is usually unnecessary, if you are using descriptors. The important methods of Document are getParam(id) and getData(id). Document.getParam will return a static parameter value from the desciptor file. This could be something such as which template to use to display the document, or some other data that applies to a class of document, rather than to the specific one you loaded. Document.getData returns data from the document itself. This value will be the result of using the associated xpath from the descriptor to query the XML data. The descriptor format allows for fairly complex constructions, and you can use it to create complex objects from you data. (such as an array of objects with predefined properties.)

If you retrieve html text for use in a text field, Ripple will adust all href links in the string, so that they load a document through DocManager, instead of just loading a webpage. In this way, you can add a text link to any item of text and it will automatically load to that page, if it is within the application. This gives you a very quick way to add links between your pages at a later date.

One of the nice results of Ripple is, if your user doesn't have JS, they still see a perfectly good html site. You can add css or whatever, to make this into a decent fallback.

• First you will need to check out the project from
  

https://mirror1.cvsdude.com/trac/osflash/ripple/browser/trunk/src

• Ripple requires xfactorstudio's XPath classes. It hasn't been tested on the latest version, but I can't see any obvious reasons why Neeld's newer classes would cause a problem
• Have a look at an example

In your AS code, you create an instance of the DocManager via its static create() method. It's a singleton. Then add listeners for when a page is loaded or starts loading.

Each data page, should be well-formed XML, so that it can be parsed in Flash. At this point, I am assuming that its most useful to use XHTML so I'm assuming that's what you will use. In the <head> tag, you will need to link in the JS code:

<script src=“ripple/js/ripple.js” type=“text/javascript”></script>
<script>
this script could be in a .js file too, if it is the same on all pages
(which is likely the case).
flashPage.html can be anything, but points to the html which contains
your main flash movie
ripple = new RippleManager(“flashPage.html”);
ripple.initPage();
</script>

You also need to add a descriptor:

<head>
<link href=“mydescriptor.xml” rel=“descriptor” media=“ripple” />
</head>

The descriptor XML looks like this:

<?xml version=“1.0” encoding=“utf-8”?>
<ripple-descriptor>
<!– this is static. Access params with Document.getParam(id)
<param id=“template” value=“main” />
<!– This describes how to get the “title” from your document. Access it with Document.getData(id)
–>
<content-node id=“title” xpath=”h1/text()” />
</ripple-descriptor>'' There are more supported nodes. See the full Descriptor XML format. ==== How you can help ==== * The javascript code is relatively untested, and will likely break in some browser configurations. It would be great to produce a support matrix, and to get it working in the most browsers. * The JS Flash detection is flakey, to say the least. Could do with making this more robust. * Ripple is currently dependent on the javascript code. The idea of this is so that you can deploy it anywhere, with minimum of fuss. However, it is straightforward to implement the same functionality with server-side code only, so it would be great if people could think about having a go at getting something working in some various serverside languages. PHP might be a good start. * Some decent examples. I am working on a photo album example, which should make a good start. Expect that soon.