| readme.html | What you are reading right now |
| axs.js | The library which makes it all happen |
| changelog.html | List all the new fixes and features by version and date |
| keychart.html | Shows available key combinations in different browsers |
| Keycap | Uses keyreg, keychart, focus, gdoc, id, r and ae methods. |
| Get Elements By Class Name | Uses gecn, log, id and ae methods. |
| Flash XOXO | Uses flash_xoxo, id and ae methods. |
| High Contrast Detect | Uses hc, r, id, and focus methods. |
| Flash Detect | Uses fd and log methods. |
| MSAA Detect | Uses md and log methods. |
spot object. In this case spot is defined as the DOM node with an ID of moreFlashStuff. The last example is to change only the first HTML item to flash. This one we do simply with axs.flash_xoxo({c:"first",p:1}) which searches for a definition list of class first which happens to be the first HTML widget on the page. Setting p to 1 says to replace the parent of the xoxo list with the flash object embed.
obj - The DOM object you want focus moved totv - [optional] Integer tab value to assign
//Get object we want to focus on
var bob=axs.id("myDivID");
//Give bob a tabindex of 5 and move focus to it
axs.focus(bob,5);
key - The key combination which will invoke your function or method "[control]+[alt]+[shift]+char"function - The function or object method to invoke when the combination is pressedpackage - [optional] A package of optional parameterspackage.des - [optional] A human readable description of what will happen when your method is invokedpackage.args - [optional] A package of arguments to be passed to your method or function when invokedpackage.node - [optional] A DOM node for which the key combination should be active. Default is entire document.package.bub - [optional] A boolean as to whether to bubble events or not. Defaults to false.package.obj - [optional] An object to return to the registered handler method in the This parameter, instead of the node the handler was registered to.A key combination is a string representation of what keys you want the user to press to invoke your function concatenated with + inbetween. So "7+shift" would register the & key while "control+alt+g" would register hitting the control+alt+G keys at the same time. The combinations can be in any order, must be in lower case and handles all the letters, number and special keys: backspace, enter, esc, pageup, pagedown, end, home, left, up, right, down, insert, space, delete, f1-f12 and tab. If you want to register a + then just use a ++ i.e. "shift+control++" would register hitting shift, control and plus together. Note that this is the same as registering "shift+control+=" since a plus is the same as equals with a shift key.
Along with the key string you pass in a function (static or anonymous) or method to be invoked when the key combination is pressed and a description. The description is included in generating a keychart which lets the user know what all the registered shortcuts are and what they do (see axs.keychart). If you are attaching a generalized function to multiple objects then you should only provide your description once so a single entry is made in the keychart.
You can also pass in a package of arguments that will be returned to your method when the key combination is pressed. This can be useful to register a generic function on multiple objects but pass distinct package in each case so the general function knows which registration triggered it.
A very valuable feature is to pass in a DOM node to attach the registration to. In this way the action won't be taken unless they are focused on the object you provided (or its contents) allowing you to have contextual behavior. If you take advantage of the node parameteraxs.keyreg supports the this construct which is passed to your handler. When your handler is triggered, this refers to the object you registered the key combination for. Note that even if focus is on an object within a registered container, you will be returned the container, not the focused object. This could be handy for, say, a list of email messages in a table. You could register the table row for a certain keycombo and even if the user is focused on different cells in the row your function will be passed the table row in this. If your registration is not attached to a specific object then this will refer to the document object. You can override the object returned in this by providing one of your own by specifying the optional obj parameter.
You can also override the default behavior which is to trap and stop the keyboard event (bubbling) from leaving the axs.keyreg function. If you register the same key combination multiple times on the same object, you may need to turn bubbling on so the first handler doesn't consume the event leaving the other handlers inert. That said, event handler execution order is indeterminate on some browsers. It would be better to register a single method to a single object for a particular key combination and have that method execute multiple actions in the order you desire.
There are a few limitations.To make this a bit easier, we made a key availability table showing the keys that are not used under Internet Explorer 6 on Windows XP running Jaws 8 with no extras installed along with notes for Firefox and IE7.
axs.keyreg("alt+shift+w",dowork,{des:"Get paid"})
function dowork(){
alert("I am widow of the late Dr. Nambodi Buty and need help transferring $1,000,000 to your account.");
}
//Register the key combination control+alt+L to invoke the method "doWork" with the description "Load new content".
//When invoking doWork, pass it an array which contains a string, allow bubbling to continue and
//invoke the method against the DOM object identified by the ID of "box1"
axs.keyreg("control+alt+l",appstuff.dowork,{node:axs.id("box1"),args:["c1.html"],bub:true,des:"Load new content"});
//Notice that dowork will be passed "c1.html" in the file parameter which it uses to ajax in some new content from a web server.
//Notice also that the "this" construct works just fine so we can just pass the object along as a parameter to gdoc
var appstuff={};
function dowork(file){
//Ajax in some new content stored in file and call dowork_cb when done and
//pass it the what object to update with the new content
axs.gdoc(file,{cb:dowork_cb,p:{obj:this}});
}
//Notice that we can now pull the object to update out of the package P and stuff it with the
//response text from the ajax call.
function dowork_cb(re,p){
//Check to see if the ajax completed correctly
if(re.status==200){
//Stuff the object given us in p with the content returned by the ajax request
axs.r(p.obj,re.responseText+s);
//Move focus to the h6 header in the new content inside the object
axs.focus(p.obj.getElementsByTagName("h6")[0]);
}
}
None
This method dynamically creates a link and a table at the very top of the page which are hidden via css in a way that is accessible to screen readers. If a user tabs they will land on a link that says "Click this link to show or hide the keyboard shortcut table". If the user tabs again the link disappears again and for mouse users there are no visible side effects. If they click or hit return on the link the keymap table is visibly revealed showing all known keystroke registrations and descriptions of what they do.
The messaging text, table and column headers are all stored in the axs.l10n array and can be overridden for localization. In particular, axs.l10n.keycap_help can be set to a string of HTML which is appended after the table to provide additional specific help. If you register additional key combinations or change your help string you should call axs.keychart() again which will re-render the table. The code includes adding control+alt+H which also triggers the visible display of the keychart. This key combination and description are also in the axs.l10n construct in case they need changed for a particular implementation. The DOM node for the hidden link is given an ID of axs_kl so you may apply CSS to it. Likewise the div containing the table itself has an ID of axs_kt. The CSS used to hide and show objects is in axs.l10n.css_keyhide and axs.l10n.css_keyshow vars respectively. Mac users (Safari in particular) use a slight variation of the css which is stored in axs.l10n.css_keyhidem. The regular axs.l10n.css_keyhide css is replaced by axs.l10n.css_keyhidem when on a mac and axs.keychart() is invoked. The boolean result of the Mac browser test are stored in axs.onmac
//Not much to it axs.keychart();
url - the you want to make an http transaction with.attributes - numerous attributes we would like to pass to the ajax function.attributes.cb - function or method we want called when the transaction is done.attributes.meth - [optional] method to use on the ajax request such as GET, POST or PUT. Defaults to GET.attributes.head - [optional] content-type header to add to the transaction. Defaults to "text/xml".attributes.data - [optional] put data here for POST or PUT. Required if doing a POST or PUT.attributes.p - [optional] package of vars to return to callback.
//Ajax in new content from the URL c1.html and call the method test.go_cb when done
//When calling go_cb pass it a package of data which includes an array element id set to "box1"
axs.gdoc("c1.html",{cb:go_cb,p:{id:"box1"}});
//Ajax is complete so use the results
function go_cb(re,p){
//If request completed successfully and we were passed an ID, stuff the results into that ID
if(re.status==200){
//replace the content of the object specified in the package.id with the text which came back from the Ajax request
axs.r(axs.id(p.id),re.responseText);
}else{
axs.log("Uh Oh, got error"+re.status);
}
}
-----------------------------
//A more complex example
//Post a snippet of XML to the webservice URL called getupdate.do and call all_done when done
var s="<?xml version="1.0" encoding="UTF-8"?><p>John Smith</p>";
axs.gdoc("getupdate.do",{cb:all_done,meth:"post",data:s,});
//Ajax is complete so use the results
function all_done(re,p){
//If request completed successfully notify the user
if(re.status==200){
alert("Update completed");
}else{
alert("Update failed");
}
}
theID - a string matching the ID of some DOM object.
//Get the object specified by someID and store it in myObject
var myObject=axs.id("someID");
theID - a string matching the ID of some DOM object.
//Get the object specified by someID and set its style to display:none
axs.ids("someID").display="none";
object - the DOM object we want to search in.class - the string of the object class we want to find.
document or some other container on the page is passed in with a string of a class. All objects which have that specific class are returned in an array.
//Find all DOM elements on the page that have a class of "box" and store it in a var called list
var list=axs.gecn(document,"box");
//Find all DOM elements inside the container with an ID of "feeds" which have a class of "box"
//and store it in the var called list
var list=axs.genc(axs.id("feeds"),"box");
//Log how many items were found
axs.log("Found "+list.length+" objects of class 'box'");
The search handles cases like these:
<span class="box">stuff</span> - matches <span class="box b">stuff</span> - matches <span class="a box">stuff</span> - matches <span class="a box b">stuff</span> - matches <span class="boxy"stuff</span> - does not match
min - [optional] the minimum version of flash we need. Defaults to 6.max - [optional] the maximum version of flash we need. Defaults to 10.min value then axs.fd returns a 0. Likewise a maximum version can be specified so checking stops at a specified max. For example, if you only need version 7 or higher then specify a max of 7 will stop checking at that level, even if version 9 is installed. We default to a max of 10 as it is the current latest version from Adobe. The test results are stored in axs.fd.result so additional calls to axs.fd will not waste time rerunning the tests. Instead axs.fd.result is returned. To force the tests to run again set axs.fd.result=0 and then make another call to axs.fd.
//See if we have flash installed and log the results
axs.log("flash version is "+axs.fd());
//See if we have flash 7 or higher installed and log the results
axs.log("flash version is "+axs.fd(7));
//See if we have flash 11 installed
axs.log("flash version is "+axs.fd(11,11));
//See if we have flash no higher than 8
axs.log("flash version is "+axs.fd(null,8));
//See if the user is running high contrast mode and log the results
axs.log("high contrast mode is "+axs.hd());
callback - This is the function axs.md should pass detection results toaxs.md.url - [optional] set the URL for where the md.swf file can be found
axs.md method can give your code insight into whether the user might be using some assistive technology and want to opt into alternative navigation or organization of the web site content.md.swf and hidden from display by CSS. This flash object does the actual detection then calls axs.md.cb with the results. axs.md.cb deletes the hidden div and then calls your function with the results. The md.swf file needs to be hosted somewhere and by default it is fetched from the same URL as the hosting page. If this is not the case then set axs.md.url to where you would like the SWF to be fetched from before calling axs.md. axs.md checks for browser/platform scenarios and will return a -1 if detection is not possible. The Flash embed HTML puts in the appropriate required version for either IE or Firefox so that old Flash version issues can be handled by the normal browser plugin behaviors. The detection itself should happen in under one second but if something should go wrong we set a 2 second timeout which will also return a -2. In other words, your callback will always get a result, but it may not always be true or false.
//See if the user is running with something using the MSAA API
function init(){
axs.md.url="http://someplace.com/md.swf";
axs.md(sr_result);
}
function sr_result(state){
axs.log('Screen Reader Presence is '+state);
}
object - the DOM object we want to change the content of.
text - the string of text or HTML we want to stuff into the object and replace what used to be there.
object and replaces it with the text passed in. Often chained with the axs.id method.
//Replace the content in the object specified by someID with new text.
var s="This is some new content";
var myObject=axs.id("someID");
axs.r(myObject, s);
//Alternativly you can do it all in one line
axs.r(axs.id("someID"),"Here is some new content");
parameters - attributes we would like to pass to the flash_xoxo function.parameters.o - [optional] DOM node to scan for xoxo lists. Default is document.parameters.c - [optional] Class name of xoxo list to convert to flash. Defaults to axs_flash_xoxo.parameters.r - [optional] DOM node whose contents will be replaced by the flash embed code. Defaults to replacing the xoxo list itself with the flash.parameter.p - [optional] Boolean - replace content of xoxo list's parent. Defaults to false.<ol class="hideme axs_flash_xoxo"> <li> <dl> <dt>version</dt><dd>7</dd> <dt>src</dt><dd>toolbar.swf</dd> <dt>width</dt><dd>554</dd> <dt>param</dt> <dd>allowScriptAccess</dd> <dd>sameDomain</dd> <dt>height</dt><dd>91</dd> <dt>align</dt><dd>middle</dd> <dt>param</dt> <dd>quality</dd> <dd>high</dd> <dt>param</dt> <dd>bgcolor</dd> <dd>#ffffff</dd> </dl> </li> </ol>Javascript examples showing how to scan for flash xoxo lists in various ways and convert them to flash blocks.
//convert any axs_flash_xoxo list into the flash block
axs.flash_xoxo();
//look for all lists of class "first" and replace the XOXO's parent with the generated flash block
axs.flash_xoxo({c:"first",p:1});
//look for all the lists of class "xoxo" within the DOM object with ID "moreFlashStuff" and replace that objects
//content with the Flash block
var spot=axs.id("moreFlashStuff");
axs.flash_xoxo({o:spot,c:"xoxo",r:spot});
//look for all the lists of class "xoxo" in the document and replace their parent's content with the flash block
axs.flash_xoxo({c:"xoxo",p:1})
object - the DOM object we want to object whose event we want to attach to.
event - event we want to react to in our code.
function - Function or method we want invoked when the even occurs.
window object gets a load event meaning that the page is fully instantiated. This method also does not destroy existing handlers that may be set up so it is convenient for adding multiple methods or functions to the same object. This avoids the common bug where multiple libraries try to set window.onload=myfunction which then clobber each other. Under the hood axs.ae handles both the standards and IE ways of doing this, works around a few bugs and allows adding functions or methods as the event handler.
if((a=o.attacheEvent)) which says that if there is an attachEvent method for the object o then point X to it; otherwise just fail through and do nothing.
//When the page loads call myFunction axs.ae(window, "load", myFunction); //When the page resizes call myFunction axs.ae(window, "resize", myFunction); //When the document has a key pressed call myFunction axs.ae(document, "keydown", myFunction);
text - string of text to log on screen.
//When the page loads call myFunction var x=10; axs.log(x+" good things happened");