#    -*- mode: org -*-

* Introduction

Think of a content rich site as a site with many trails through it. In each 
trail, there is content. You can greatly improve the usability of a busy pages 
by providing efficient keyboard navigation to move through these trails. 
This can be a more effective approach than providing section headings alone as 
it allows for grouping related content, filtering out content that is not 
relevant to what the user is immediately interested in, and controlling the 
granularity of each item in a given trail. The content navigation rule (CNR) 
system in AxsNav allows you to easily define these trails. 

The CNR system is designed to handle cases where not all of the content is 
present. If a trail that you have defined happens to have no items, then for 
that instance, the CNR system will discard that trail. Therefore, when you 
write CNRs, you should do it for the case where all of the content is present.

To make it easier for users to discover the keyboard navigation commands for 
the page, the CNR system can automatically generate a help string with all 
the possible commands. This help generation mechanism takes the user's current 
position into account - it will only report actions that can be done from the 
present state. Here is some sample code for generating and speaking the help 
string:
: var helpStr = "The following shortcut keys are available: " +
:               axsNavObj.localHelpString() +
:               axsNavObj.globalHelpString();
: axsJAXObj.speakTextViaNode(helpStr);

* Data Types 
** KEY
Any character that is letter, number, or punctuation found on the keyboard 
OR a string that is "LEFT", "DOWN", "UP", "RIGHT", "ENTER", "PGUP", 
"PGDOWN". Note that the case of the letter will matter - if you only assign 
"a" to do something, pressing "A" will not cause that to happen.

** STRING
An arbitrary string of text

** ACTION
A string that specifies what action should take place when the AxsNav 
system navigates to something. If no acceptable action is specified, the 
default action will take place.
**** "CALL:functionName"
Will call the specified function with what the AxsNav system navigated to 
as the argument. For example:
      : <item action="CALL:foo"> //some/xpath/expression/here </item>
      will cause AxsNav to make the call
      : foo(currentItemObject)
      when AxsNav moves through the items defined by that item element.
	  
** INTEGER
An integer 

** TRIGGER
A string that specifies what trigger should cause the AxsNav system to 
click on a target. 
**** "listTail"
Trigger is activated if the user is at the end of the list and tries to go 
forward.
**** "listHead"
Trigger is activated if the user is at the start of the list and tries to 
go backward.	 
**** "listEntry"
Trigger is activated if the user switches to this list.

* CNR Elements
	   
** cnr
    This is the root level element of the CNR file. The cnr element can 
contain lists and targets.
**** next
Value is a space delimited list of KEYs. Pressing any of these keys will 
cause the AxsNav to switch to the next list. After the last list, this will 
loop to the first list.
**** prev
Value is a space delimited list of KEYs. Pressing any of these keys will 
cause the AxsNav to switch to the previous list. After the first list, this 
will loop to the last list.

** list
    This is a child element of the cnr element. A list is a trail that the 
user can go through on the page. Lists can contain items and targets.
**** title
Value is a STRING. When the user switches to this list, this is what will 
be spoken by the AT.
**** hotkey
Value is a space delimited list of KEYs. Pressing any of these keys will 
cause AxsNav to switch to this list and immediately read the next item of 
this list.
**** onEmpty
Value is a STRING. If this list is empty and the user tries to access it 
with a hotkey, the onEmpty string will be spoken by the AT. Note that 
AxsNav automatically discards empty lists so if there are not hotkeys 
assigned to the list, it is not necessary to have an onEmpty message.
**** next
Value is a space delimited list of KEYs. Pressing any of these keys will 
cause the AxsNav to go to the next item in this list. After the last item, 
this will always loop to the first item.
**** prev
Value is a space delimited list of KEYs. Pressing any of these keys will 
cause the AxsNav to go to the previous item in this list. After the first 
item, this will always loop to the last item.
**** fwd
Value is a space delimited list of KEYs. Pressing any of these keys will 
cause the AxsNav to go to the next item in this list. After the last item, 
if there is a target element with a trigger of "listTail" for this list, 
that target will be acted upon. Otherwise, this is the same as the next 
attribute.
**** back
Value is a space delimited list of KEYs. Pressing any of these keys will 
cause the AxsNav to go to the next item in this list. After the last item, 
if there is a target element with a trigger of "listHead" for this list, 
that target will be acted upon. Otherwise, this is the same as the prev 
attribute.

** item
    This is a child element of the list element. The item element is an 
xpath expression that returns a set of nodes which belong in the list. If a 
list has more than one item element, the set of nodes that will be in the 
list is the union of all the sets of nodes returned by the xpaths of all 
the item elements.
**** index
Value is an INTEGER. Specifies the first node in the set of nodes returned 
by the xpath which should be added to the set of nodes for the item. The 
default is 0 (starts from the first node).
**** count
Value is an INTEGER. Specifies the total number of nodes to add to the set 
of nodes for the item. The default is to add all of the nodes starting from 
the 'index'.
**** action
Value is an ACTION. Does the action specified when a node in the set of 
nodes for the item is navigated to by the AxsNav system. If no action is 
specified, the default action is to magnify the item if AxsNav is given a 
magnifier, go to the element associated with the item, speak the element.
	   
** target
    This is a child element of the cnr and list elements. The target 
element is an xpath expression that returns the node that should be 
clicked. Note that targets in a list can be relative to the items in that 
list. Thus having:
       : <item>
       :  //p[@class='g']
       : </item>
       : <target title='Open result' hotkey='ENTER'>
       :   ./span[@class='w']
       : </target>
	   means that if the user is currently on
       : getNodesWithXPath("//p[@class='g']")[2]
	   then the element that will be clicked when the user presses Enter is
	   : getNodesWithXPath("//p[@class='g']/span[@class='w']")[2]
**** title
Value is a STRING. This is used for generating the help string.
**** hotkey
Value is a space delimited list of KEYs. Pressing any of these keys will 
cause AxsNav to click on the target if the target is active. Targets that 
are children of the cnr element are active all the time. Targets that are 
children of the list element are only active when that list item is the 
current list.
**** trigger
Value is a TRIGGER.
**** onEmpty
Value is a STRING. If there is no target and the user tries to access it, 
the onEmpty string will be spoken by the AT. 
	   
	   
	   
#+TITLE:     AxsJAX Content Navigation Rules (CNR) Reference
#+AUTHOR:    T.V. Raman, Charles L. Chen
#+EMAIL:     raman@google.com, clchen@google.com
#+LANGUAGE:  en
#+OPTIONS:   H:3 num:t toc:t \n:nil @:t ::t |:t ^:t f:t *:t TeX:t LaTeX:nil skip:t p:nil