Author: jmorliaguet Date: Thu Nov 3 01:21:35 2005 New Revision: 28919 Modified: z3lab/cpsskins/branches/jmo-perspectives/engines/default/filters/accesskeys/README.txt Log:
- access keys doc update Modified: z3lab/cpsskins/branches/jmo-perspectives/engines/default/filters/accesskeys/README.txt ============================================================================== --- z3lab/cpsskins/branches/jmo-perspectives/engines/default/filters/accesskeys/README.txt (original) +++ z3lab/cpsskins/branches/jmo-perspectives/engines/default/filters/accesskeys/README.txt Thu Nov 3 01:21:35 2005 @@ -21,10 +21,10 @@ Description ----------- -The *accesskey* filter adds support for access keys [1] to web pages. +The *accesskey* filter adds support for access keys [1] in HTML pages. -Access keys allow users to go to a given page by pressing a given combination -of keys on the keyboard (ALT/CTRL, + <KEY> ). +Access keys allow users to jump to a given page by pressing a combination +of keys on the keyboard (ALT/CTRL, + <KEY>). They can be used to improve the site's accessibility and to add shortcuts in the application's interface. @@ -38,16 +38,29 @@ An access key configuration consists of: -- a key (an ascii character) +- a key (a single character) -- a URL (fixed strings or expressions) +- a URL (fixed strings or TAL expressions) [expressions are not implemented + yet] Key sets ~~~~~~~~ -Access keys are grouped by *sets*. -Not two same keys may be used inside a same set. +Access keys are grouped by *sets*. Not two same keys may be used inside a same +set otherwise there would be some conflicting information. + + +Rendered markup +~~~~~~~~~~~~~~~ + +The filter adds the following HTML markup at the top of rendered pages + + <div> + <a href="@@some-page.html" accesskey="K"></a> + <a href="@@some-other-page.html" accesskey="L"></a> + ... + </div> Access key usage @@ -61,30 +74,123 @@ - different theme *pages* may use different sets in different *perspectives*. -Since a key set contain keys that are unique, it is difficult to merge -several sets, hence pratically only one set -- the effective key set -- -will be used in a given context. +Since a key set contain unique keys, it is difficult to merge several sets +into one, so pratically only one set will be used in any given situation. Storage ~~~~~~~ -Key sets can be defined on the filesystem (read-only) or they can be persistent -objects stored in the ZODB. +Key sets can be defined on the filesystem (read-only setup) or they can be +persistent objects stored in the ZODB [so far only filesystem-based access +keys have been implemented] -Rendered markup -~~~~~~~~~~~~~~~ +Rendering engine +~~~~~~~~~~~~~~~~ -The filter adds the following HTML markup at the top of rendered pages +In the rendering engine's declaration, the access key filter should be +associated to the IThemePage renderer to make sure that the markup gets +inserted in the <body> section of the page:: - <div> - <a href="@@some-page.html" accesskey="K"></a> - <a href="@@some-other-page.html" accesskey="L"></a> - ... - </div> +<configure + xmlns="http://namespaces.zope.org/cpsskins"> + + <renderer + for="cpsskins.elements.interfaces.IThemePage" + engine="some engine"> + + ... + + <filter + name="accesskeys" + /> + + </renderer> + +</configure> + + +Configuration / setup +~~~~~~~~~~~~~~~~~~~~~ + +Access key collections are declared in ZCML:: + +<configure + xmlns="http://namespaces.zope.org/cpsskins"> + + <accesskeys + name="front page keys"> + /> + +</configure> + + +Access keys can be associated to collections in two ways: + +1) by being inserted inside an <accesskeys /> directive:: + +<configure + xmlns="http://namespaces.zope.org/cpsskins"> + + <accesskeys + name="front page keys"> + + <accesskey + key="0" + url="@@some-page.html" + /> + + </accesskeys> + +</configure> + +In this case the keys are registered at the same time as the collection. + + +2) by refering to an existing access key collection: + +<configure + xmlns="http://namespaces.zope.org/cpsskins"> + + <accesskey + collection="front page keys" + key="0" + url="@@some-page.html" + /> + +</configure> + +This method is appropriate in the case where a given engine registers a +collection and other engines register keys inside the engine's collection. + + +Associating access keys to engines +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The <cpsskins:engine /> directive can be used to associate a collection of +access keys to an engine:: + +<configure + xmlns="http://namespaces.zope.org/cpsskins"> + + <engine + name="default" + accesskeys="front page keys" + /> + +</configure> + + +Associating access keys to perspectives +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +TODO + +(access keys associated to perspectives override the keys associated to +engines) -The markup is invisible. +(...) [1] http://www.w3.org/TR/html4/interact/forms.html#adef-accesskey -- http://lists.nuxeo.com/mailman/listinfo/z3lab-checkins