# vim: ts=2 sw=2 et ft=org
#+STYLE: <LINK href="stylesheet.css" rel="stylesheet" type="text/css" />
#+TITLE: Nitrogen 2.x Documentation
#+AUTHOR: Rusty Klophaus (@rustyio)
#+OPTIONS:   H:2 num:1 toc:1 \n:nil @:t ::t |:t ^:t -:t f:t *:t <:t
#+EMAIL: 

#+TEXT: [[file:./index.org][Getting Started]] | *API* | [[file:./elements.org][Elements]] | [[file:./actions.org][Actions]] | [[file:./validators.org][Validators]] | [[file:./handlers.org][Handlers]] | [[file:./config.org][Configuration Options]] | [[file:../about.org][About]]
#+HTML: <div class=headline>Nitrogen Paths</div>

* 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.

* 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.

   1. If the selector has multiple parts separated by commas, then the
      selector is split, and each part is combined.

   2. If the selector is "page", then a reference to the DOM document
      is returned.

   3. 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'.

   4. 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.

   5. 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.

   6. 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'.

   7. 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.

   8. 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.

   9. Finally, if no elements were found, then Nitrogen resorts to
      matching =jQuery(path)=.

* 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".

* 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.
