Spry Element Selector Utility

Selecting Page Elements
Supported Selectors
Selector Functions

The Spry Element Selector is a utility that allow developers to use CSS Selectors to select elements on the page and apply functionality to them. This allows Spry pages to be built and run with unobtrusive javascript.

We have some samples of it in action here:

This document describes how to use the Selector utility. An overview of CSS Selectors can be found at http://www.w3.org/TR/REC-CSS2/selector.html and http://css.maxdesign.com.au/selectutorial/

Selecting Page Elements

The Spry Element Selector allows you to pick one or more page elements using a CSS selector. This can be used to select a single element or multiple elements. The utility supports most CSS 3 selectors.

Using the sample below, we can build sample selectors. See some examples in the Selector Examples.

<div id='container' class='mainBlock'>
<p class='bodyText'>This is body text.</p>
<span class='highlight'>This is the first span.</span>
<span class='highlight'>This is the second span.</span>
<p id='closer'>This is closer text.</p>
</div>

Spry uses '$$' to denote the selector. The format is:

Spry.$$("the CSS selector").utilfunction;

Using this notation, we can set a class 'newClass' on all tags that have a 'bodyText' class by using:

Spry.$$(".bodyText").addClassName("newClass");

or, we can set the 'newClass' on all the <span> tags with:

Spry.$$("span").addClassName("newClass");

Supported Selectors

The list of selectors that Spry supports is:

Pattern	Meaning
E	an element of type E
E.className	an E element with a specified classname
E#id	an E element with ID equal to "id".
E F	an F element descendant of an E element
*	any element
E:first-child	an E element, first child of its parent
E[foo]	an E element with a "foo" attribute. Note: When using E[class], this will fail on Internet Explorer, since it adds a class attribute to every element, even those with out a class in the markup. This is a browser issue and not a Spry issue.
E > F	an F element child of an E element
E[foo~="bar"]	an E element whose "foo" attribute value is a list of space-separated values, one of which is exactly equal to "bar"
E[hreflang\|="en"]	an E element whose "hreflang" attribute has a hyphen-separated list of values beginning (from the left) with "en"
E[foo="bar"]	an E element whose "foo" attribute value is exactly equal to "bar"
E + F	an F element immediately preceded by an E element
E[foo$="bar"]	an E element whose "foo" attribute value ends exactly with the string "bar"
E:last-child	an E element, last child of its parent
E:nth-last-of-type(n)	an E element, the n-th sibling of its type, counting from the last one
E:nth-of-type(n)	an E element, the n-th sibling of its type
E[foo^="bar"]	an E element whose "foo" attribute value begins exactly with the string "bar"
E:nth-last-child(n)	an E element, the n-th child of its parent, counting from the last one
E:empty	an E element that has no children (including text nodes)
E:nth-child(n)	an E element, the n-th child of its parent
E:only-of-type	an E element, only sibling of its type
E:not(s)	an E element that does not match simple selector s
E:only-child	an E element, only child of its parent
E:last-of-type	an E element, last sibling of its type
E:first-of-type	an E element, first sibling of its type
E[foo*="bar"]	an E element whose "foo" attribute value contains the substring "bar"
E ~ F	an F element preceded by an E element
E:checked	an E element that is checked (radio buttons or checkboxes)
E:disabled	an E element that is set at disabled (form elements)
E:enabled	an E element that is enabled (form elements that are not explicitly disabled.)

This selectors are not supported:

E:lang(fr)

Pattern	Meaning
E:link E:visited	an E element being the source anchor of a hyperlink of which the target is not yet visited (:link) or already visited (:visited)
E:active E:hover E:focus	an E element during certain user actions
E::first-line	the first formatted line of an E element
E::first-letter	the first formatted letter of an E element
E::before	generated content before an E element
E::after	generated content after an E element
E:target
E:lang(fr)
E::selection

These selectors can be combined to achieve a more flexible or specific selection.

Note: According to the spec, spaces are generally not allowed within the selector except where part of the actual selector, so:

Spry.$$("DIV P").addClassName("redText"); Correct
Spry.$$("p[class~=dev").setAttribute("align", "left"); Correct.

Spry.$$("p[class ~= dev").setAttribute("align", "left"); Not correct.

Spry.$$("div input.theform:disabled).addClassName("red");

Selector Functions

There is a set of common methods that can be used with the Element Selector util, plus an option for a custom function.

addClassName

This will append the specified class name to all the matching elements.

Spry.$$("element selector").addClassName("className");

addEventListener

This will add a listener for each matching element for the specified event.

Spry.$$("element selector").addEventListener(eventType, handler, capture);

forEach

This will run the specified function for each matching element. The 'forEach' function allows for any javascript to be run within it.

Spry.$$("element selector").forEach(myFunction);

removeAttribute

This will remove the specified attribute from all matching elements.

Spry.$$("element selector").removeAttribute("attribute");

removeEventListener

This will remove the listener on each matching element.

Spry.$$("element selector").removeEventListener(eventType, handler, capture);

removeClassName

This will remove the specified class name from all the matching elements.

Spry.$$("element selector").removeClassName("className");

setAttribute

This will add the specified attribute with the specified value to all matching elements.

Spry.$$("element selector").setAttribute("attribute","value");

setProperty

This will set a property on an object.

Spry.$$("element selector").setProperty("property","value");

setStyle

This will set the specified styles to the element.

Spry.$$("element selector").setStyle("width:30px;color:#FF00FF;");

Note: This function uses Spry.Utils.setAttribute to set namespaced attributes (spry:region, etc). This will fail on Safari 2.0 and earlier. This is a bug in Safari, but appears to have been fixed in version 3.0.
This function should work fine for regular, non-namespaced attributes.

toggleClassName

This will look for the specified class name. If it does not exist on the element, it will add it. If it is already there, it will remove it.

Using the Element Selector

The real power of the Element Selector is when you want to manipulate multiple parts of the page at a time. Use the Element Selector to find all the elements and then use the built in functions to update the elements.

In a custom function

Link the Element Selector to your page.

<script src="includes/SpryDOMUtils.js" lang="javascript" type="text/javascript">

Write a function block.

<script src="includes/SpryDOMUtils.js" lang="javascript" type="text/javascript">
<script lang="javascript" type="text/javascript">
function myFunction(){

}
</script>

Add the Element Selection function. In this case, we will add a class to all <p>s that are within a <table>.

<script src="includes/SpryDOMUtils.js" lang="javascript" type="text/javascript">
<script lang="javascript" type="text/javascript">
function myFunction(){
   Spry.$$("table p").addClassName("myClass");
}
</script>

Then you just need something to kick off the function.
```
<a href="#" onclick="myFunction();">Click Me</a>
```

Running the Element Selector on page load

Many time, you will want to run some functions when the page loads. We can use the Element Selector to run functions when the page loads. In this example, we will activate the constructor scripts for 2 Accordions on the page. We will move the functions to an external javascript file, so that our script is unobtrusive.

Link the Element Selector to your page.

<script src="includes/SpryDOMUtils.js" lang="javascript" type="text/javascript">
...
<body>

<div id="Accordion1" class="Accordion">
...
</div>
<div id="Accordion2" class="Accordion">
...
</div>
...

Create a new blank page and save it as .myFunctions.js'.
In this new page, write a function block.
```
function myFunction(){

}
```
Add the Element Selection function. In this case, will activate the widget constructors.
```
function myFunction(){
  Spry.$$(".Accordion").forEach(function(n) { window[n.id] = new Spry.Widget.Accordion(n); });
}
```
To explain, this function looks for all the tags with the "Accordion" class, which if using basic Accordion code, should be on the widget container tag for all the accordions. We use the 'forEach' function to apply the specified function to all the instances of the selector. 'window[n.id]' grabs the ID of the selected element ('Accordion1 and Accordion2') and uses that value as the widget name.
If you want to use a behavior for that widget, to open or close the panel, just use the ID of the widget for the name: onclick="Accordion2.open();"
Next we need to set up a listener that will fire off the script after the page is loaded. This is important because the markup needs to exist before we run the constructor scripts. This is why they generally come after the markup in a normal Spry page.
```
function myFunction(){
  Spry.$$(".Accordion").forEach(function(n) { window[n.id] = new Spry.Widget.Accordion(n); });
}
Spry.Utils.addLoadListener(myFunction);
```

Lastly, link the 'myFunctions.js' file to your Spry page.

<script src="includes/SpryDOMUtils.js" lang="javascript" type="text/javascript">
<script src="myFunctions.js" lang="javascript" type="text/javascript">