Region Attributes

spry:choose

Description

The "spry:choose" construct provides the functional equivalent to a case statement, or an if/else if/else construct. To create an "spry:choose" structure, add an "spry:choose" attribute to an element. Next, add one or more child elements with "spry:when" attributes on them. The value of an "spry:when" attribute should be a JavaScript expression that returns a zero or non-zero value.. To make a default case, just in case all of the JS expressions for each spry:when attribute returns zero/false, add an element with an "spry:default" attribute. The "spry:default" attribute doesn't require a value, but XHTML states that all attributes must have a value, so we use the convention of setting the value of the attribute equal to its name.

The region processing engine will evaluate the "spry:when" attribute of each node in the order they are listed under their parent element. The "spry:default" element is always evaluated last, and only if no "spry:when" expression returned a non-zero value.

spry:choose constructs must be within a spry:region or spry:detailregion.

Format

spry:choose
   spry:when="javascript expression"
   spry:default="sprydefault"

Example

<div spry:region="dsPhotos">
		<div spry:choose="spry:choose">
			<div spry:when="'{@path}' == 'surf.gif'">{@path}</div>
			<div spry:when="'{@path}' == 'undefined'">Path was not defined.</div>
			<div spry:default="spry:default">Unexpected value for path!</div>
		</div>
	</div>

spry:content

Description

spry:Content does a Inner HTML replacement of the existing content with the content specified in the attribute. This attribute is used for javascript degradation reasons. The existing content is displayed in non-scripting environments and the spry:content data is used when javascript is enabled.

spry:content supports a variety of content. The attribute accepts text, Spry data references or functions.

Format

spry:content="sprydata"

Example

<div spry:content="This is dynamic content">This is static content</div>
<div spry:content="dsData::description"><!--#include file="description.htm" -->  </div>
   
<div spry:region="dsData">This is static <span spry:content="{category]">content </span> </div>

spry:default

 

Description

spry:default is used with spry:choose and spry:when to set up an if/then construct for displaying content. spry:default is used when all spry:when constructs return false.

spry:default will always be processed last. The placement of spry:default within spry:choose doesn't matter.

spry:default doesn't require a value, but XHTML demands that all attributes have values, so value can be used.

spry:default must be within a spry:region or spry:detailregion.

Format

spry:default="any value "

Value

No specific value is required but some value must be used to follow the rules of XHTML.

Example

<div spry:choose="spry:choose">
	<div spry:when="'{@path}' == 'surf.gif'">{@path}</div>
	<div spry:when="'{@path}' == 'undefined'">Path was not defined.</div>
	<div spry:default="spry:default">Unexpected value for path!</div>

</div>

spry:detailregion

Description

This function defines an element as a spry detail region. A spry:detailregion works just like a Spry region but is also regenerated automatically when a listed data set is updated. A spry:detailregion sets up a listener to the listed data sets. All data references must be within a spry:detailregion or a spry:region. A spry:detailregion can be defined on any HTML element that allows Inner HTML writing.

Those tags that cannot accept a spry:detailregion are: COL, COLGROUP, FRAMESET, HTML, IFRAME, STYLE, TABLE, TBODY, TFOOT, THEAD, TITLE, TR.
Note: IE 7 has a bug that causes <select> tags that contain a spry:detailregion or spry:region to render incorrectly. It is not recommended that <select> tags be used as regions.

Although the elements listed above cannot be a dynamic region container, they can exist inside a dynamic region container.

Format

spry:detailregion="data set name"

Value

datasetname

Example

<div spry:detailregion="dataset">
<div spry:detailregion="dataset dataset2 dataset3">

spry:errorstate

Description

spry:errorstate sets up a default mapping of the "error" state to the name specified in the value of the attribute.

spry:errorstate must be used on the element that has the spry:region or spry:detailregion attribute on it.

Format

spry:errorstate="stateName"

Value

spry:errorstate takes a name as a value.

Example

<div spry:region="ds" spry:errorstate="genericErrorMsg">
  <div spry:state="genericErrorMsg">An error has occurred!</div>
  <div spry:state="404ErrorMsg">The file was not found!</div>
</div>

In the example above, if the "error" state of the region fires, the "genericErrorMsg" state markup will be used.

spry:even

Description

spry:even is a behavior that sets a CSS class name to the element when Spry is writing data while the value of currentRow is even. This is commonly used to set alternating row colors or tables or other repeating elements.

If multiple data sets are specified in the region, it will use the first listed. If you want to use other datasets, they need to be specified in the value: spry:even="ds2 classname"

spry:even must be within a spry:region or spry:detailregion.

Format

spry:even="classname"

Value

spry:even takes a CSS class name as a value.

Optional: data set name if the region uses multiple data sets.

Example

<style>
.evenClass{ background-color:{#FFFFFF}
</style>

<tr spry:repeat="ds1" spry:even="evenClass">

This will change the background color of the table row when the currentRow number is even while looping over the <tr>.

spry:expiredstate

Description

spry:expiredstate sets up a default mapping of the "expired" state to the name specified in the value of the attribute.

spry:expiredstate must be used on the element that has the spry:region or spry:detailregion attribute on it.

Format

spry:expiredstate="stateName"

Value

spry:expiredstate takes the name of a state as a value.

Example

<div spry:region="ds"spry:expiredstate="genericSessionExpMsg">
  <div spry:state="genericSessionExpMsg">Your session has expired.</div>
  <div spry:state="serverUnavailableMsg">The server is currently unavailable!</div>
</div>

In the example above, if the "expired" state of the region fires, the "genericSessionExpMsg" state markup will be used.

spry:hover

Description

spry:hover is a behavior that sets a CSS class name when the mouse is over the element that contains the attribute. The class is removed when the mouse moves off of the element.

spry:hover must be within a spry:region or spry:detailregion.

Format

spry:hover="classname"

Value

spry:hover takes a CSS class name as a value.

Example

<style>
.hoverClass{ background-color:{#FFF000}
</style> <tr spry:hover="hoverClass">

This will change the background color of the table row when the mouse moves over it.

spry:if

Description

The "spry:if" attribute is used to display a page element based on the results of a condition. The value of spry:if is a JavaScript expression *or* the name of a JavaScript function that returns zero or non-zero values. A non-zero value returned by the JavaScript expression or function will result in the element being written to the final output.  A zero result will cause the element not to be written to the page.

spry:if attributes must be within a spry:region or spry:detailregion.

It should be noted that the JavaScript expressions within spry:if attributes are evaluated with the JavaScript eval() function, which means that any valid JavaScript, including function calls can be used, but the ultimate result must be a zero, non-zero, true, or false answer. Also, since JavaScript expressions contain characters that are special within HTML/XHTML markup, the developer should entity encode any '<', '>' and '&' characters. For example, the following expression within this spry:if attribute:

<div spry:if="x >= y && y <= z">...</div>

should be entity encode like this:

<div spry:if="x >= y && y <=z">...</div>

The use of the JavaScript function name form of the spry:if attribute is useful when your page is running in an environment where the use of the eval() function is not allowed or discouraged. To specify a function to be called when the spry:if attribute is to be evaluated, you simply set the value of the spry:if attribute to the name of the function with a "function::" prefix. For example:

spry:if="function::myFunction"

Where myFunction is a global function that is defined with the following signature:

function myFunction(region, lookupFunction)
{
  // Code that returns a zero/non-zero/true/false result goes here.
}

Your function will be called each time the spry:if attribute is evaluated, and it will be passed 2 arguments. The first argument is the name of the region that is currently being re-generated. The second argument is a function that can be used to lookup the values of data references. The lookup function is very flexible in terms of the format of the data reference it is given. For example, given a region that is bound to a data set called "ds1", the following calls to the lookup function are equivalent:

var name = lookupFunction("@name");

var name = lookupFunction("{@name}");

var name = lookupFunction("ds1::@name");

var name = lookupFunction("{ds1::@name}");

var name = lookupFunction("ds1", "@name");

Format

spry:if="<javascript expression> "

- OR -

spry:if="function::<function name>"

Example

<!-- Examples of spry:if with JavaScript expressions. -->



<ol class="spry:repeat">
 <li spry:if="'{@path}'.search(/^s/) != -1;">{@path}</li>
</ol>

<select spry:repeatchildren="dsGalleries" id="gallerySelect" onchange="dsGalleries.setCurrentRowNumber(this.selectedIndex);">
<option spry:if="{ds_RowNumber} == {ds_CurrentRowNumber}" selected="selected">{sitename}</option>
<option spry:if="{ds_RowNumber} != {ds_CurrentRowNumber}">{sitename}</option>
</select> <!-- Examples of spry:if with function calls --> <script type="text/javascript"> function PathBeginsWithS(region, lookupFunc) { return lookupFunc("{@path}").search(/^s/) != -1; } function IsCurrentRow(region, lookupFunc) { return lookupFunc("{ds_RowNumber}") == lookupFunc("{ds_CurrentRowNumber}"); } function IsNotCurrentRow(region, lookupFunc) { return lookupFunc("{ds_RowNumber}") != lookupFunc("{ds_CurrentRowNumber}"); } </script> ... <ol class="spry:repeat"> <li spry:if="function::PathBeginsWithS">{@path}</li>
</ol>

<select spry:repeatchildren="dsGalleries" id="gallerySelect" onchange="dsGalleries.setCurrentRowNumber(this.selectedIndex);">
<option spry:if="function::IsCurrentRow" selected="selected">{sitename}</option>
<option spry:if="function::IsNotCurrentRow">{sitename}</option>
</select>

spry:loadingstate

Description

spry:loadingstate sets up a default mapping of the "loading" state to the name specified in the value of the attribute.

spry:loadingstate must be used on the element that has the spry:region or spry:detailregion attribute on it.

Format

spry:loadingstate="stateName"

Value

spry:loadingstate takes the name of a state as a value.

Example

<div spry:region="ds"spry:loadingstate="genericLoadingMsg">
  <div spry:state="genericLoadingMsg">All data sets loading ...</div>
  <div spry:state="dsLoadingMsg">The ds data set is loading ...</div>
</div>

In the example above, if the "loading" state of the region fires, the "genericLoadingMsg" state markup will be used.

spry:odd

Description

spry:even is a behavior that sets a CSS class name to the element when Spry is writing data while the value of currentRow is odd. This is commonly used to set alternating row colors or tables or other repeating elements.

If multiple data sets are specified in the region, it will use the first listed. If you want to use other datasets, they need to be specified in the value: spry:odd="ds2 classname"

spry:odd must be within a spry:region or spry:detailregion.

Format

spry:odd="classname"

Value

spry:odd takes a CSS class name as a value.

Optional: data set name if the region uses multiple data sets.

Example

<style>
.evenClass{ background-color:{#FFFFFF}
</style>

<tr spry:repeat="ds1" spry:odd="evenClass">

This will change the background color of the table row when the currentRow number is odd while looping over the <tr>.

spry:readystate

Description

spry:readystate sets up a default mapping of the "ready" state to the name specified in the value of the attribute.

spry:readystate must be used on the element that has the spry:region or spry:detailregion attribute on it.

Format

spry:readystate="stateName"

Value

spry:readystate takes the name of a state as a value.

Example

<div spry:region="ds"spry:readystate="listLayout">
  <ul spry:state="listLayout"><li spry:repeat="ds">{name}</li></ul>
  <div spry:state="divLayout" spry:repeatchildren="ds">{name} </div>
</div>

In the example above, if the "ready" state of the region fires, the "listLayout" state markup will be used.

spry:region

Description

This function defines an element as a spry region. A Spry region contains data references to be processed by the Spry engine (and any other markup). All data references must be within a spry:region or spry:detailregion. A spry region can only be used on any HTML element that allows Inner HTML writing.

Those tags that cannot accept a spry:region are: COL, COLGROUP, FRAMESET, HTML, IFRAME, STYLE, TABLE, TBODY, TFOOT, THEAD, TITLE, TR
Note: IE 7 has a bug that causes <select> tags that contain a spry:detailregion or spry:region to render incorrectly. It is not recommended that <select> tags be used as regions.

Although the elements listed above cannot be a dynamic region container, they can exist inside a dynamic region container.

Format

spry:region="data set name(s)"

Values

datasetname(s)

Example

<div spry:region="dataset">
<div spry:region="dataset dataset2 dataset3">

spry:repeat

Description

spry:repeat repeats the tag and children that contains the spry:repeat attribute, looping through the data references for each record of the dataset.

Format

spry:repeat="data set name"

Value

datasetname

Example

<ol>
<li spry:repeat="dataset">{dataset::names}</li>
</ol>
This example will repeat the data reference AND the <li> over every record in the data set. This will create a normal ordered list of names.

spry:repeatchildren

Description

spry:repeatchildren repeats the tags within the tag that contains the spry:repeat attribute, updating data references for each record of the dataset, but does not repeat the tag that contains the attribute.

Format

spry:repeatchildren="data set name"

Value

data set name

Example

<ol spry:repeatchildren="dataset">
<li>{dataset::name}</li>
</ol>
This creates a standard ordered list of 'name's from the dataset. spry:repeatchildren can be used when more a more flexible layout is needed or when the container tag shouldn't be repeated.

spry:select

Description

spry:select is a behavior that sets a CSS class name to the element when the mouse is over the element that contains the attribute. The class persists on the element until the next click on another spry:select element. This is commonly used to highlight repeating elements.

spry:select must be within a spry:region or spry:detailregion.

Format

spry:select="classname"

Value

spry:select takes a CSS class name as a value.

Example

<style>
.selectClass{ background-color:{#FFFFFF}
</style>

<tr spry:select="selectClass">

This will change the background color of the table row when the user clicks on the row and will persist until the user clicks on another row. Then that row will have the class applied.

spry:selectgroup

Description

spry:selectgroup works in conjunction with spry:select to allow for multiple selects within a group of elements. This is used to ensure that multiple distinct selectable groups do not interfer with each other.

spry:selectgroup must be within a spry:region or spry:detailregion and must be used with a spry:select attribute.

Format

spry:selectgroup="unique id"

Value

spry:select takes unique value to distinguish it from other groups. A number or string can be used.

Example

<tr>
<td><ul spry:repeatchildren="dsEmployees">
<li spry:select="selected" spry:selectgroup="l1">{firstname} {lastname}</li>
</ul></td>
<td><ul spry:repeatchildren="dsEmployees">
<li spry:select="selected" spry:selectgroup="l2">{firstname} {lastname}</li>
</ul></td>
</tr>

This code ensures that the items in the respective lists can be selected independently.

spry:setrow

Description

spry:setrow is use to update the current row number of the data set. This in turn causes detailregions to update. This attribute can be used in the same way as the setCurrentRow function:
onclick="ds1.setCurrentRow('{ds_RowID}');

It is common to use a data reference to set the currentRow. If only one data set is defined for the region, and a data reference is used for the value, Spry will use that data set value. If multiple data sets are defined for the region, Spry will use the first data set listed in the region attribute, unless another data set is specified in the attribute.

spry:setrow defaults to onClick.

spry:setrow must be within a spry:region or spry:detailregion.

Format

spry:setrow="number"

Value

spry:setrow takes a number. This can either be hard coded or populated with a data reference.

Example

Single data set
<tr>
<td><ul spry:repeatchildren="dsEmployees">
<li spry:setrow="{ds_RowID}">{firstname} {lastname}</li>
</ul></td>
</tr>

Multiple data sets

<tr>
<td><ul spry:repeatchildren="dsFirst dsEmployees">
<li spry:setrow="dsEmployees {ds_RowID}">{firstname} {lastname}</li>
</ul></td>
</tr>

spry:setrownumber

Description

spry:setrownumber is used to update the current row number of the data set. This attribute can be used in the same way as the setCurrentRowNumber function:
onclick="ds1.setCurrentRowNumber('{ds_RowID}');

RowID is a unique, non-changing number of a specific row in the data set. RowNumber refers to the number of the row being processed. For example, in a looping construct repeating <tr>, the 3rd row written out is RowNumber 2 (zero based counting system), but the RowID of the data in RowNumber 2 may be anything.

It is common to use a data reference to set the currentRowNumber. If only one data set is defined for the region, and a data reference is used for the vaule, Spry will use that data set value. If multiple data sets are defined for the region, Spry will use the first data set listed in the region attribute, unless another data set is specified in the attribute.

spry:setrownumber defaults to onClick.

spry:setrownumber must be within a spry:region or spry:detailregion.

Format

spry:setrownumber="number"

Value

spry:setrownumber takes a number. This can either be hardcoded or populated with a data reference.

Example

Single data set
<tr>
<td><ul spry:repeatchildren="dsEmployees">
<li spry:setrownumer="{ds_RowID}">{firstname} {lastname}</li>
</ul></td>
</tr>

Multiple data sets

<tr>
<td><ul spry:repeatchildren="dsFirst dsEmployees">
<li spry:setrownumber="dsEmployees {ds_RowID}">{firstname} {lastname}</li>
</ul></td>
</tr>

spry:sort

Description

The spry:sort attribute is used to sort the specified column. It's equivalent to ds1.sort("column","toggle)

By default, spry:sort will toggle the sort order. Ascending and Descending can be set as options.

Columns can be set for secondary or tertiary sorting.

If multiple data sets are defined for the region that contains the sort, Spry will use the first data set listed, unless the desired data set is specified in the attribute.

spry:sort must be within a spry:region or spry:detailregion.

Format

spry:sort="sortcolumn"

Value

sortcolumn

Optional

dataset name - the name of the data set if it is not the first listed in the spry:region or detailregion.

sort order - toggle, ascending or descending. Toggle is none is specified.

Example


Single Sorting
<div spry:region="ds1">
<table>
<tr>
<th spry:sort="lastname">Lastname</th>
<th spry:sort="firstname">Firstname</th>
</tr>
<tr spry:repeat="ds1">
<td>{lastname}</td>
<td>{firstname}</td>
</tr>
</table>
</div>

Secondary sort, Multiple Data sets
<div spry:region="ds1">
<table>
<tr>
<th spry:sort="ds2 lastname,firstname">Lastname</th>
<th spry:sort="ds2 firstname,lastname ascending">Firstname</th>
</tr>
<tr spry:repeat="ds1">
<td>{lastname}</td>
<td>{firstname}</td>
</tr>
</table>
</div>

spry:state

Description

The spry:state attribute is used to control which content displays while Spry is processing the data. Spry can show different content while the data is loading, when it's ready and if there is an error.

While Spry is processing the data, elements with the "loading" state will show.
When Spry is finished processing, the "ready" state elements will show and the "loading" elements will disappear.
If there is some error in processing the data, only the "error" state elements will show.

spry:state must be within a spry:region or spry:detailregion.

Format

spry:state="statename"

Value

There are 3 built in Spry states:

Example

<div spry:region="dsEmployees">
<div spry:state="loading">Loading employee data ...</div>
<div spry:state="error">Failed to load employee data!</div>
  <ul spry:state="ready">
     <li spry:repeat="dsEmployees">{firstname} {lastname}</li>
  </ul>
</div>

spry:test

Description

spry:test is used when you want to limit or filter what gets written out in a spry:repeat loop. Adding a spry:test attribute to an element that contains a spry:repeat or spry:repeatchildren will control which records get written out.

spry:test is different than spry:if because spry:test is only used with a spry:repeat(children). spry:if can be used anywhere within a region.

The value of the spry:test attribute can be either a JavaScript expression, or the name of a global JavaScript function that is prefixed with "function::". In both cases, the result of the expression or the function must be a zero or non/zero (true/false) value. If true is returned, markup will be generated for the current row being processed in the spry:repeat. If false, no markup is generated for that row. For more information on what is allowed within a JavaScript expression and the use of function names prefixed with "function::", see the description for spry:if.

Format

spry:test="<javascript expression> "

- OR -

spry:test="function::<javascript function name>"

Example

<!-- Example using a JavaScript expression within a spry:test attribute. -->



<ul>
  <li spry:repeat="dsPhotos" spry:test="'{@path}'.search(/^s/) != -1;">{@path}</li>
</ul>



<!-- Example using a JavaScript function name within a spry:test attribute. -->



<script type="text/javascript">

function PathBeginsWithS(region, lookupFunc)
{
  return lookupFunc("{@path}").search(/^s/) != -1;
}

</script>

...

<ul>
  <li spry:repeat="dsPhotos" spry:test="function::PathBeginsWithS">{@path}</li>
</ul>
This will only output records where the @path column contains the letter 's'.

spry:when

Description

spry:when is used with spry:choose and spry:default to set up an if/then construct for displaying content. spry:when constructs are evaluated in the order in which they appear in the code.

The value of the spry:when attribute can be either a JavaScript expression, or the name of a global JavaScript function that is prefixed with "function::". In both cases, the result of the expression or the function must be a zero or non/zero (true/false) value. If true is returned, the element that contains the spry:when attribute will be written out. If false, that element is skipped. For more information on what is allowed within a JavaScript expression and the use of function names prefixed with "function::", see the description for spry:if.

spry:when must be within a spry:region or spry:detailregion.

Format

spry:when="<javascript expression>"

- OR -

spry:when="function::<javascript function name>"

Value

A javascript expression that returns a zero or non-zero value, or the name of a global JavaScript function, prefixed with "function::", that returns a zero or non-zero value. See the description of spry:if for more information on the use of function names as values for spry:when.

Example

<div spry:choose="spry:choose">
	<div spry:when="'{@path}' == 'surf.gif'">{@path}</div>
	<div spry:when="'{@path}' == 'undefined'">Path was not defined.</div>
	<div spry:default="spry:default">Unexpected value for path!</div>

</div>

Region Utility Functions

Spry.Data.Region.addObserver

Description

Adds an observer to the specified region.

Format

Spry.Data.Region.addObserver(regionID, observer)

Arguments

regionID - the ID of the spry:region that is being observed.

observer - the function to run on the specified event.

Returns

N/A

Example

<script>
...
var observer = { onPostUpdate: function(notifier, data) { var acc = new Spry.Widget.Accordion("Acc1"); } };
Spry.Data.Region.addObserver("Acc1", observer); ... <script> ... <div id="Acc1" class="Accordion" spry:region="dsEmployees" tabindex="0">
<div class="AccordionPanel" spry:repeat="dsEmployees">
<div class="AccordionPanelTab">
<h3>{username}</h3>
</div>
<div class="AccordionPanelContent">
<div>{firstname} {lastname}</div>
</div>
</div>
<div>

Spry.Data.Region.notifyObservers

Description

Notifies the Observers of an event.

Format

Spry.Data.Region.notifyObserver(methodName, regionID, data)

Arguments

methodName -

regionID - the ID of the spry:region that is being observed.

data - any data that needs to be passed to the method

Returns

N/A

Example

Spry.Data.Region.removeObservers

Description

Removes an observer from the specified region.

Format

Spry.Data.Region.removeObserver(regionID, observer)

Arguments

regionID - the ID of the spry:region that is being observed.

observer - the function for the observer.

Returns

N/A

Example

var observer = { onPostUpdate: function(notifier, data) { var acc = new Spry.Widget.Accordion("Acc1"); } };
Spry.Data.Region.removeObserver("Acc1", observer);

Spry.Data.initRegions

Description

Creates a Spry.Data.Region object for each element in the specified node sub-tree that has a spry:region or spry:detailregion attribute on it. It then calls the updateContent() method of each region object to trigger the loading of all data sets bound to the regions and the re-generation of the markup in each region.

If a sub-tree node is not specified, initRegions() defaults to using the document's body element.

initRegions() is called automatically when the document's onload handler fires.

Format

Spry.Data.initRegions(node)

Arguments

node - DOM Element Object. The root node of the sub-tree to search for regions.

Returns

N/A

Example

// The code below was taken directly out of SpryData.js:

Spry.Utils.addLoadListener(function() { setTimeout(function() { Spry.Data.initRegions(); }, 0); });

Spry.Data.updateRegion

Description

Forces the specified region to load the data sets it is bound to, if necessary, and re-generate its markup.

Format

Spry.Data.updateRegion(regionName);

Arguments

regionName - String. The name of the region (region element id attribute) to update.

Returns

N/A

Example

<div id="productListing" spry:region="ds1">

...

</div>

...

<input type="button" value="Refresh Region" onclick="Spry.Data.updateRegion('productListing');" /> 

Spry.Data.getRegion

Description

Gets the Spry.Data.Region object associated with the given region.

Format

Spry.Data.getRegion(regionName)

Arguments

regionName - String. The name of the region (element id attribute).

Returns

Object. The Spry.Data.Region object associated with the region name.

Example

<script type="text/javascript">

function ForceRegionUpdate()
{
  // Get the region object.

  var rgn = Spry.Data.getRegion('productListing');

  // If we have a valid region object, force it to update.

  if (rgn)
    rgn.updateContent();
}

</script>

...

<div id="productListing" spry:region="ds1">

...

</div>

...

<input type="button" value="Clear" onclick=ForceRegionUpdate();"" /> 

Spry.Data.updateAllRegions

Description

Calls updateContent() on all regions on the page.

Format

Spry.Data.updateAllRegions()

Arguments

N/A

Returns

N/A

Example

<div id="productListing" spry:region="ds1">

...

</div>

...

<input type="button" value="Refresh All Regions" onclick=Spry.Data.updateAllRegions();"" /> 

Region Methods

Region

Description

The Spry.Data.Region class is responsible for managing the markup in a spry:region or spry:detailregion. It re-generates the markup in the region in response to notifications from the data sets that are bound to the spry:region it is associated with, and dispatches region notifications to any observers.

The Spry.Data.Region class is not meant to be instantiated directly by developers. It is instantiated programatically by the Spry.Data.initRegions() function which is triggered when the document's onload event is fired.

File

SpryData.js

Inheritance

N/A

clearContent

Description

Removes *all* child nodes (content) inside the region element.

Format

clearContent()

Arguments

N/A

Returns

N/A

Example

<script type="text/javascript">

function ClearProductListing()
{
  // Get the region object.

  var rgn = Spry.Data.getRegion('productListing');

  // If we have a valid region object, clear its content.

  if (rgn)
    rgn.clearContent();
}

</script>

...

<div id="productListing" spry:region="ds1">

...

</div>

...

<input type="button" value="Clear" onclick=ClearProductListing();"" /> 

getMappedState

Description

This function returns the name associated with the given state name. If there is no name associated with the state name, the state name itself is returned.

When a region re-generates its markup for a given state (ready, loading, or error), it uses getMappedState() to determine what markup to use for the transformation.

Developers can associate a name with a given state programatically by using the setMappedState() function, or by placing a spry:readystate, spry:loadingstate, and spry:errorstate attribute on the region element.

Format

getMappedState(stateName)

Arguments

stateName - String. The name of the state to look up.

Returns

String. Returns the name associated with the given state name.

Example

var rgn = Spry.Data.getRegion('productListing');

if (rgn)
{
  var name = rgn.getMappedState("ready");

  if (name == "tableLayout")
  {
    // Do something.
  }
}

getState

Description

This function returns the name of the region's current state.

Format

getState()

Arguments

N/A

Returns

String. The current state of the region.

Example

var rgn = Spry.Data.getRegion('productListing');

if (rgn)
{
  var name = rgn.getState();

  if (name == "ready")
  {
    // Do something.
  }
}

mapState

Description

Associates a new state name with a particular state. This is useful if you would like a region to use markup associated with a specific state name when it re-generates for the ready, loading or error states.

A developer can also set up a default mapping for a given state by using the spry:readystate, spry:loadingstate, or spry:errorstate attributes on the region element.

Format

mapState(stateName, newStateName)

Arguments

stateName - String. The original state name.

newStateName - String. The new state name.

Returns

N/A

Example

<script type="text/javascript">
function RenderAsList()
{
  // Get the region object.

  var rgn = Spry.Data.getRegion('productListing');

  // If we have a valid region object, map its ready state to listLayout.

  if (rgn)
  {
    rgn.mapState('ready', 'listLayout');
    rgn.updateContent();
  }
}

function RenderEmptyState()
{
  // Get the region object.

  var rgn = Spry.Data.getRegion('productListing');

  // If we have a valid region object, map its ready state to empty.

  if (rgn)
  {
    rgn.mapState('ready', 'empty');
    rgn.updateContent();
  }
}

</script>

...

<!--
Our region starts off rendering nothing because the ready state
is initially mapped to the "empty" state, which doesn't exist
underneath the "productListing" region.

Since the list underneath the "productListing" region is marked
with a spry:state attribute, it will only be shown if the region
is told to render the "listLayout" state.
-->

<div id="productListing" spry:region="ds1" spry:readystate="empty">

  <ul spry:state="listLayout">
    <li spry:repeat="ds1">{name}</li>
  </ul>

</div>

...

<input type="button" value="Show" onclick=RenderAsList();"" />
<input type="button" value="Hide" onclick=RenderEmptyState();"" />W

setState

Description

This function forces the region to re-generate its markup using the markup that is associated with stateName.

Format

setState(stateName, suppressNotfications)

Arguments

stateName - String. The name of the state to use when re-generating the region markup.

suppressNotifications - Boolean. This argument is optional. If true, the region re-generates the region markup, but does not fire off any notifications during that process. If false or not specified, the region fires off notifications.

Returns

N/A

Example

<script type="text/javascript">
function RenderAsList()
{
  // Get the region object.

  var rgn = Spry.Data.getRegion('productListing');

  // If we have a valid region object, map its ready state to listLayout.

  if (rgn)
    rgn.setState('listLayout');
}

function RenderEmptyState()
{
  // Get the region object.

  var rgn = Spry.Data.getRegion('productListing');

  // If we have a valid region object, map its ready state to empty.

  if (rgn)
    rgn.setState('empty');
}

</script>

...

<!--
Our region starts off rendering nothing because there is no
content associated with the loading or ready state.

Since the list underneath the "productListing" region is marked
with a spry:state attribute, it will only be shown if the region
is told to render the "listLayout" state.
-->

<div id="productListing" spry:region="ds1">

  <ul spry:state="listLayout">
    <li spry:repeat="ds1">{name}</li>
  </ul>

</div>

...

<input type="button" value="Show" onclick=RenderAsList();"" />
<input type="button" value="Hide" onclick=RenderEmptyState();"" />W

updateContent

Description

This function forces the region to re-generate its content. It will trigger any data set the region is bound to, to load its data if it has not already been loaded. If all data sets are loaded, this function calls setState() with the 'ready' state.

This function is called programatically after the onload event has fired and all regions have been initialized. It can be called by developers at any time to force the region to re-generate itself.

Format

updateContent()

Arguments

N/A

Returns

N/A

Example

<script type="text/javascript">
function Show()
{
  // Get the region object.

  var rgn = Spry.Data.getRegion('productListing');

  // If we have a valid region object, force it to re-generate the region markup.

  if (rgn)
    rgn.updateRegion();
}

function Clear()
{
  // Get the region object.

  var rgn = Spry.Data.getRegion('productListing');

  // If we have a valid region object, clear any content underneath it.

  if (rgn)
    rgn.clearContent();
}

</script>

...

<div id="productListing" spry:region="ds1">

  <ul>
    <li spry:repeat="ds1">{name}</li>
  </ul>

</div>

...

<input type="button" value="Show" onclick=Show();"" />
<input type="button" value="Hide" onclick=Clear();"" />

Copyright © 2007. Adobe Systems Incorporated.
All rights reserved.