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
