View source for Accessibility/Awesome Fetch API

=Awesome Fetch API=

==Summary==

A bulk data fetching API is designed to
* to search the data through a web page
* to retrieve portions of a web page in a single call

which allows to
* decrease number of calls the AT has to poke into a server
* create buffer-less screen readers
* create lazy and lightweight server implementations

A typical scenarios are
* Navigation: AT fetches next/prev heading while the user moves through a web page
* Read a range: AT reads a paragraph by lines

==Terms and concepts==

Terms:
* Search filters which allows to narrow the data that AT is interested in, for example, find all accessible having a heading role
* Result specifiers which allows to specify what kind of data should be fetched, for example, AT is interested to retrieve accessible names and boundaries
* AOM points (accessible object model aka DOM) which are used to identify and compare ranges in a document. Inspired by DOM point concept.

Also it operates with AT concepts, which are:
* <code>role</code> - a primary characteristic of object like <code>button</code>
* <code>states</code> - boolean characteristics of object like <code>focused</code> or <code>selected</code>
* <code>attributes</code> - a named property having a scalar value (not boolean), for example <code>level:1</code>
* <code>relations</code> - a named property pointing to other object such as <code>label_for</code>
* <code>boundaries</code> - an object boundary in form of a rect
* <code>text</code> - text

==Proposal==

===Search===

====Search filters====

Filter is a boolean expression consisting of conditions combined by boolean operators like: <code>cond1 && cond2 || cond3</code>, where <code>condN</code> is a boolean function which returns true for each accessible object complying a function's criteria.

Suggested boolean functions:
* <code>is(trait)</code> - returns true if an accessible object has a given trait which may be role or state. For example <code>is(listitem) && is(selected)</code> indicates all selected list items.

* <code>has(property[, value])</code> - return true for an accessible object having a property of a value if provided, for example, <code>has(level, 5)</code> stands for all objects having level attribute with value of 5.

A value of <code>has</code> method is not necessary a scalar value. If a property points to an object, then a boolean function can be used as a value. For example, <code>has(controls, is(listbox))</code> will return an object which controls a listbox object.

====Search/Query API====

Search/query is a way to find points or a range complying a search criteria.

<code>
query(AOMPoint anchor, String direction, String searchTerm, AOMPoint start, AOMPoint end)
</code>

to return a a first AOM point complying a search term.

<code>
queryAll(AOMPoint anchor, String direction, String searchTerm, AOMPoint start, AOMPoint end)
</code>

to return a list of all entries complying a search term.

===Data fetching===

====Result specifiers====

Results specifiers are used to scope fetched data. The format is <code>property:value,[value,...]</code>. For example <code>role;states;attributes:level,xml-roles</code> will return role, states, level and xml-roles attribute.

====Data format====

The fetching data is supposed to be in JSON format. For example,
<pre>
[{
  role: "heading",
  states: [
    "invisible", "offscreen"
  ],
  attributes: {
    xml-roles: [ "super-button", "lower-button" ]
  },
  boundaries: [ x, y, width, height ],
  text: [
  ]
},
{
  role: "heading",
  states: [
    "visible", "onscreen"
  ],
  attributes: {
    level: 1
  },
  boundaries: [ x, y, width, height ]
}]
</pre>

====API====

So used to fetch all 

<code>
fetch(in AOMPoint start, in AOMPoint end, out String serializedRange)
</code>

returns a string of data of the above format.