Developer's manual

um.keys

This array controls the Keyboard navigation module.

• Skip code example

//keyboard navigation
um.keys = [
	'38',   // up ["n"] ("38" = up arrow key)
	'39',   // right ["n"] ("39" = right arrow key)
	'40',   // down ["n"] ("40" = down arrow key)
	'37',   // left ["n"] ("37" = left arrow key)
	'119',  // hotkey ["n"] ("119" = F8)
	'none', // hotkey modifier ["none"|"shiftKey"|"ctrlKey"|"altKey"|"metaKey"]
	'27',   // escape ["n"|"none"] ("27" = escape key)
	'document.getElementsByTagName("a")[0]', // exit focus ["js-expression"]
	];

//keyboard navigation
$um['keys'] = array(
	'38',   // up ["n"] ("38" = up arrow key)
	'39',   // right ["n"] ("39" = right arrow key)
	'40',   // down ["n"] ("40" = down arrow key)
	'37',   // left ["n"] ("37" = left arrow key)
	'119',  // hotkey ["n"] ("119" = F8)
	'none', // hotkey modifier ["none"|"shiftKey"|"ctrlKey"|"altKey"|"metaKey"]
	'27',   // escape ["n"|"none"] ("27" = escape key)
	'document.getElementsByTagName("a")[0]', // exit focus ["js-expression"]
	);

up, right, down and left ["n"]

These values are the ASCII key-code of each directional button. I recommend not changing them. If you do change them don't use "9" (which is the Tab key), and note that not all key codes will work - letters and numbers won't, but system and function keys generally will.

hotkey ["n"]

Also an ASCII key code, this is the main button used for jumping on or off the navbar. I chose F8 as the default because it has the fewest number of environments in which it already has defined functionality.

But whatever you set for the hotkey, there's inevitably going to be people who can't use it, because their browser or OS has it configured to do something else. There's no way to know, so the thing to do is have a preferences form, and let people change it for themselves.

Only function keys are guaranteed to work, which are key-codes 112 to 123.

hotkey modifier ["none"|"shiftKey"|"ctrlKey"|"altKey"|"metaKey"]

You can specify a single modifier which must be pressed with the hotkey. If you set it to "none" it specifically means "no modifier is pressed", rather than "it doesn't make a difference". The value "metaKey" is the Command (apple) key in MacOS.

This option can also be set from the preferences form.

escape ["n"|"none"]

The escape key is the same as pressing the hotkey when the navbar already has focus - in other words, it resets the menu and send focus back to the page. The purpose of this is a kind of panic-button for users: it is possible that someone might Tab onto the navbar, not know it supports arrow-key navigation, and then press one of the arrow keys expecting it to scroll the page (when the navbar has focus it temporarily suppresses arrow-key scrolling, which is essential for arrow-key navigation to be possible at all; once the focus has left the navbar, scrolling works as normal). So in order to mitigate the chance of confusion, the escape key offers an extra, intuitive way out - that's why I chose key-code 27, which is Esc - the escape key.

exit focus ["js-expression"]

When you jump off the navigation bar, the script needs somewhere to send the focus to, so you define that here as a javascript expression which identifies a single element. It must be either a link or a form element, as these are the only ones which can universally accept the focus.

In the example above I've selected the first item in the anchors collection, which will exist on any page that has at least one link; I've used getElementsByTagName to reference it because document.links may not be available in XHTML mode.

Please note, however, that it's only useable in this case because the navigation bar is not the first thing in the source code - if it were, that expression would send focus back to itself. In such a siuation you'd be better to identify an exit-focus element using getElementById.

Here's a couple more examples - both equally acceptable, if you know that that element will be there:

• Skip code example

'document.getElementById("someLink")', // exit focus ["js-expression"]

'document.getElementsByTagName("input")[0]', // exit focus ["js-expression"]

um.speech

This array controls the Speech output module.

• Skip code example

//speech output
um.speech = [
	'no',  // asynchronous speech ["yes"|"no"] 
	'0',   // buffer length ["milliseconds"|"0"]
	'2',   // reading speed ["-10" to "10"]
	'yes', // read title attributes ["yes"|"no"]
	'navbar,menu,top,out of,link,to the,left,right,leaving menus', // vocabulary
	];

//speech output
$um['speech'] = array(
	'no',  // asynchronous speech ["yes"|"no"]
	'0',   // buffer length ["milliseconds"|"0"]
	'2',   // reading speed ["-10" to "10"]
	'yes', // read title attributes ["yes"|"no"]
	'navbar,menu,top,out of,link,to the,left,right,leaving menus', // vocabulary
	);

asynchronous speech ["yes"|"no"]

A value of "no" means that any speech event will override whatever is currently being said. This is synchronous speech, which I believe is most appropriate, because it allows you to navigate quickly through links and get immediate feedback on where you are. A value of "yes" gives asynchronous speech, where if the focus moves quickly between links they will cue-up and be read out in turn. If you use asynchronous speech you should set a decent buffer length:

buffer length ["milliseconds"|"0"]

Set a value in milliseconds which is the delay between a link receiving focus, and its text being read out. If the focus moves to another link before the timer is up, it will be cancelled and a new one will start. If you use asynchronous speech you can use this value to prevent 'drive-by' reading - long queues of links being read out one by one.

reading speed ["-10" to "10"]

I don't know what these figures actually equate to, but "0" is the default speed, "-10" is unuseably slow, and "10" unuseably fast. I would suggest a bit faster than default: "2" sounds good to me.

read title attributes ["yes"|"no"]

A value of "yes" means that for any link which has a title attribute, the title will be read out instead of the link text. With a value of "no", title attributes are ignored.

vocabulary

This is a comma-delimited list of exactly 6 words and 3 phrases, which is used to construct sentences giving spatial and content information. If you're working in English there's no need to edit this. Unfortunately I can't provide any translations at this time, but if you can translate the vocabulary yourself, the module will use whatever you put here. Please ensure that you keep the word-order the same.

Here are the contexts in which the words and phrases appear:

• "navbar top out of [n]"
• "[link text], link"
• "menu to the right" (or "left")
• "menu top out of [n]"
• "leaving menus"