====== Ripple Descriptor XML Format ======
A Ripple descriptor file is loaded automatically when it is linked to another document. It describes how information from that document is retrieved by Document.getData(), when you call it from your ActionScript code. It also provides static parameters that will become associated with any document that links to the it.

Multiple descriptors may be linked to a single document. In case of conflict, the value from the first descriptor is used in preference to later ones.

== Example descriptor ==
<code xml>
    <?xml version="1.0" encoding="utf-8"?>
    <ripple-descriptor>

        <param id="template" value="default" />

        <content-node id="title" xpath="//h1/text()" />

        <content-node id="content" xpath="//*[@id = 'content']" />
	
        <content-object id="menu" xpath="//div[@class = 'link']">
            <prop name="url" xpath="./a/@href" type="url" />
            <prop name="label" xpath="./a/text()" />
        </content-object>
	
    </ripple-descriptor>
</code>

For more information about XPath, check out the XPath classes at [[http://www.xfactorstudio.com/ActionScript/AS2/XPath/|www.xfactorstudio.com]], and look at the tutorials from [[http://www.w3schools.com/xpath/|w3schools]].

===== Tags =====

==== <ripple-descriptor> ====

The root node is always ''<ripple-descriptor>''.

== Attributes ==

None.

== Child elements ==
  * 0 or more ''[[#<param>]]'' elements
  * 0 or more ''[[#<content-node>]]'' elements
  * 0 or more ''[[#<content-object>]]'' elements

==== <param> ====

Represents a static parameter, to be associated with documents that use this descriptor. In this example, the param is "template", which could be used in Flash to determine which template to use to display the document.

== Attributes ==
  * id - String id that is used to access the parameter from ActionScript
  * value - String value that is returned in ActionScript when the parameter is retrieved

== Child elements ==
None.

== Usage ==
In ActionScript, using the [[#example_descriptor|above descriptor]]:
<code actionscript>
   var template = document.getParam("template");
   trace(template); // "default"
</code>

==== <content-node> ====

Represents data that can be queried directly from the document. When you request this data in ActionScript, the xpath query is run on the document and the result is returned.

== Attributes ==
  * id - String id that is used to access the data from ActionScript
  * xpath - An xpath query.
  * type - normal|url. "normal" is default. If type="url", the value will be treated as a url and, if it is not absolute, it will be converted automatically, relative to the containing document.

== child elements ==
None.

== Usage ==
<code actionscript>
   var title = document.getData("title");
</code>
Based on the using the [[#example_descriptor|descriptor above]], this code would find the ''<h1>'' tag in the document, and return the contents.

==== <content-object> ====

Represents a complex object. When you access this from ActionScript, first the xpath is run to get a list of all the matching nodes, and an empty ActionScript object is created for each one. Properties are then added to these objects, as defined by the child ''<prop>'' elements.

== child elements ==
  * 1 or more  ''[[#<prop>]]'' elements

== Attributes ==
  * id - String id that is used to access the data from ActionScript
  * xpath - An xpath query.

== Usage ==
Suppose you had a document, containing this fragment of HTML, and were using the [[#example_descriptor|XML descriptor above]]:
<code xml>
   ....
   <div class="link"><a href="http://www.peterjoel.com">peter</a></div>
   <div class="link"><a href="http://www.flashant.org">aral</a></div>
   <div class="link"><a href="http://www.jessewarden.com">jesse</a></div>
   ....
</code>
Then you might access this information like this:
<code actionscript>
   var links = document.getData("links");
   trace(links[0].label); // "peter"
   trace(links[1].url.hostname); // "www.flashant.org"
   trace(links[2].url.href); // "http://www.jessewarden.com"
</code>

==== <prop> ====
Defines a property of an object, that has been created from a ''<content-object>'' element.

The Xpath statement should be defined relative to the node that would be matched by the xpath in the corresponding ''<content-object>'' element. This is best achieved by starting the xpath with ''"./"''.

== child elements ==
None.

== Attributes ==
  * name - String name of the property to create
  * xpath - An xpath query.

== Usage ==
See ''[[#<content-object>]]''