Nitrogen 2.x Documentation

Nitrogen Paths

1 Overview

Nitrogen 2.x allows you to reference element paths using jQuery selectors. These selectors can be used in three contexts:

As the target (first parameter) of wf:wire/2, wf:update/2, wf:insert_top/2, wf:insert_bottom/2, etc.
As the trigger (first parameter) or target (second parameter) of wf:wire/3.
As the trigger or target of an #event{} action.

Path matching in Nitrogen is complicated because it must provide a simple, straight-forward interface while still accounting for potential name-collisions due to the nested nature of Nitrogen elements.

For example, you should be able to create two elements with the same ID, but in different areas of the element hierarchy, and be able to reference those elements in predictable ways.

2 How Are Paths Matched?

The objs(Path, Anchor) function is used to match selectors on the client. This is defined in nitrogen.js, and returns a jQuery object containing all of the elements that match the selector provided under Path, potentially in close proximity to the selector provided under Anchor. If Anchor is not provided, then the anchor set by Nitrogen.$anchor(Anchor, Target) is used.

Nitrogen.$anchor/2 is automatically called by Nitrogen before each action is rendered. The Anchor value is set to the uniquely generated temp ID for the element to which the action applies, it will look something like .wfid_temp23422.

Unless you are doing some wacky stuff, your application should not need to worry about calling objs() or Nitrogen.$anchor() directly, but it helps to know what is happening behind the scenes in case you need to debug.

If you are trying to wire an action or update a command, and the statement seems to affect the wrong elements, it may help to drop down into a Javascript console and run objs(YourPath) to see what is actually getting matched.

Steps To Match a Path

Here are the steps that the objs() function takes when matching a path.

If the selector has multiple parts separated by commas, then the selector is split, and each part is combined.
If the selector is "page", then a reference to the DOM document is returned.
The string "\#\#" is replaced with ".wfid_". This allows you to specify Nitrogen elementIDs in a string selector. For example "\#\#myelementid > .someclass" will be rewritten to ".wfid_myelementid > .someclass". This is done because Nitrogen uses classes to tag your elements with their ID, so an element with ID of 'myelementid' will be tagged with a class called '.wfid_myelementid'.
If the string "me" is found surrounded by non-word characters, it is replaced with the anchor that was set. This allows you to write paths such as "me > .image" which will apply to all elements with class ".image" under the current element.
If the path is a one word string and it is the name of an HTML element such as "table", "div", "h1", etc., then try matching as a Nitrogen element ID first, and if that doesn't work, then try matching as an HTML element.
If a string is found containing only words separated by periods (for example, "element1.element2"), then it is assumed to be a nested series of elements, and is converted to ".wfid_element1 .wfid_element2". This will match all Nitrogen elements named 'element2' underneath any Nitrogen elements named 'element1'.
If the path begins with "body", then match using a call to jQuery(path). This will match any elements in the context of the entire document.
Otherwise, Nitrogen will try to match elements as closely as possible starting at the current anchor. First, try to match the path under the current anchor using jQuery(anchor).find(path). If results were found, then stop and return. Otherwise, call jQuery(anchor).parents() to get a list of parents, and then for each parent, call jQuery(parent).find(path). If results were found, then stop and return.
Finally, if no elements were found, then Nitrogen resorts to matching jQuery(path).

3 Nitrogen Specific Selectors

Selector: me

A keyword to specify the context of the current anchor. In other words, if you wire an event to an element, then 'me' will point to that element.

Selecter: ##element

A shortcut for referring to a Nitrogen element when you specify a string path. Because of the way Nitrogen uses class names to tag elements, this is the same as specifying ".wfid_element".

4 jQuery Selectors

Selectors and descriptions below are pulled directly from the [[http://api.jquery.com/category/selectors/][jQuery Selectors Documentation].

Selector: *

Selects all elements.

Selector: :animated

Select all elements that are in the progress of an animation at the time the selector is run.

Selector: Attribute Contains Prefix [name|=value]

Selects elements that have the specified attribute with a value either equal to a given string or starting with that string followed by a hyphen (-).

Selector: Attribute Contains [name*=value]

Selects elements that have the specified attribute with a value containing the a given substring.

Selector: Attribute Contains Word [name~=value]

Selects elements that have the specified attribute with a value containing a given word, delimited by spaces.

Selector: Attribute Ends With [name$=value]

Selects elements that have the specified attribute with a value ending exactly with a given string.

Selector: Attribute Equals Selector [name=value]

Selects elements that have the specified attribute with a value exactly equal to a certain value.

Selector: Attribute Not Equal Selector [name!=value]

Select elements that either don't have the specified attribute, or do have the specified attribute but not with a certain value.

Selector: Attribute Starts With Selector [name^=value]

Selects elements that have the specified attribute with a value beginning exactly with a given string.

Selector: :button Selector

Selects all button elements and elements of type button.

Selector: :checkbox Selector

Selects all elements of type checkbox.

Selector: :checked Selector

Matches all elements that are checked.

Selector: Child Selector ("parent > child")

Selects all direct child elements specified by "child" of elements specified by "parent".

Selector: Class Selector (".class")

Selects all elements with the given class.

Selector: :contains() Selector

Select all elements that contain the specified text.

Selector: Descendant Selector ("ancestor descendant")

Selects all elements that are descendants of a given ancestor.

Selector: :disabled Selector

Selects all elements that are disabled.

Selector: Element Selector ("element")

Selects all elements with the given tag name.

Selector: :empty Selector

Select all elements that have no children (including text nodes).

Selector: :enabled Selector

Selects all elements that are enabled.

Selector: :eq() Selector

Select the element at index n within the matched set.

Selector: :even Selector

Selects even elements, zero-indexed. See also odd.

Selector: :file Selector

Selects all elements of type file.

Selector: :first-child Selector

Selects all elements that are the first child of their parent.

Selector: :first Selector

Selects the first matched element.

Selector: :gt() Selector

Select all elements at an index greater than index within the matched set.

Selector: Has Attribute Selector [name]

Selects elements that have the specified attribute, with any value.

Selector: :has() Selector

Selects elements which contain at least one element that matches the specified selector.

Selector: :header Selector

Selects all elements that are headers, like h1, h2, h3 and so on.

Selector: :hidden Selector

Selects all elements that are hidden.

Selector: ID Selector ("#id")

Selects a single element with the given id attribute.

Selector: :image Selector

Selects all elements of type image.

Selector: :input Selector

Selects all input, textarea, select and button elements.

Selector: :last-child Selector

Selects all elements that are the last child of their parent.

Selector: :last Selector

Selects the last matched element.

Selector: :lt() Selector

Select all elements at an index less than index within the matched set.

Selector: Multiple Attribute Selector [name=value][name2=value2]

Matches elements that match all of the specified attribute filters.

Selector: Multiple Selector ("selector1, selector2, selectorN")

Selects the combined results of all the specified selectors.

Selector: Next Adjacent Selector ("prev + next")

Selects all next elements matching "next" that are immediately preceded by a sibling "prev".

Selector: Next Siblings Selector ("prev ~ siblings")

Selects all sibling elements that follow after the "prev" element, have the same parent, and match the filtering "siblings" selector.

Selector: :not() Selector

Selects all elements that do not match the given selector.

Selector: :nth-child Selector

Selects all elements that are the nth-child of their parent.

Selector: :odd Selector

Selects odd elements, zero-indexed. See also even.

Selector: :only-child Selector

Selects all elements that are the only child of their parent.

Selector: :parent Selector

Select all elements that are the parent of another element, including text nodes.

Selector: :password Selector

Selects all elements of type password.

Selector: :radio Selector

Selects all elements of type radio.

Selector: :reset Selector

Selects all elements of type reset.

Selector: :selected Selector

Selects all elements that are selected.

Selector: :submit Selector

Selects all elements of type submit.

Selector: :text Selector

Selects all elements of type text.

Selector: :visible Selector

Selects all elements that are visible.