ikiwiki (3.20130711) unstable; urgency=low
[ikiwiki.git] / doc / todo / access_keys.mdwn
1 Access keys (i.e., keyboard shortcuts) can be defined for common
2 features.  Something like the following:
3
4 * 1 - Homepage
5 * 2 - Search box
6 * E - Edit
7 * R - RecentChanges
8 * H - History
9 * P - Preferences
10 * D - Discussion
11 * S - Save the current page (when editing)
12 * C - Cancel the current edit
13 * V - Preview the current page
14
15 Then, for example, in Firefox one could press Alt+Shift+E to edit the
16 page.
17
18 For links, this is implemented as:
19
20     <a href="recentchanges/" accesskey="r">RecentChanges</a>
21
22 and for forms buttons:
23
24     <input type="submit" value="Submit" accesskey="s"/>
25
26 --[[JasonBlevins]], March 21, 2008 18:05 EDT
27
28 - - - 
29
30 There were also a few thoughts about access keys on the
31 [[main_discussion_page|index/discussion]]. Now moved to here:
32
33 > Would anyone else find this a valuable addition.  In oddmuse and instiki (the only other
34 > wiki engines I am currently using, the edit, home, and submit link tags have an
35 > accesskey attribute.  I find it nice not to have to resort to the mouse for those
36 > actions.  However, it may not be something everyone appreciates.  Any thoughts?
37 > --[Mazirian](http://mazirian.com)
38
39 > > Maybe, although it would need to take the critisism at
40 > > <http://www.cs.tut.fi/~jkorpela/forms/accesskey.html> into account.
41
42 > >> Thank you for that link. Given that the edit link is the first thing you tab to
43 > >> in the current layout, I guess it isn't all that necessary. I have had a 
44 > >> a user complaint recently that Alt-e in oddmuse was overriding his access
45 > >> to the browser menu.
46
47 ----
48
49 The main criticism there it
50 seems is that some browsers implement access keys in a way (via the Alt
51 key) that allows them to override built-in keyboard shortcuts.  I
52 believe this is not a problem any longer in Firefox (which uses the
53 Shift+Alt prefix) but I suppose it could still be a problem in other
54 browsers.
55
56 Another criticism is that most browsers do not display the access keys
57 that are defined.  The [article][] cited on the main discussion page
58 suggests underlining the relevant mnemonic.  I think it would be
59 sufficient to just list them in the basewiki documentation somewhere.
60
61   [article]: http://www.cs.tut.fi/~jkorpela/forms/accesskey.html
62
63 It's an unfortunate situation&mdash;I'd like an alternative to the
64 rodent but there are quite a few downsides to using access keys.
65 Tabbing isn't quite the same as a nice shortcut key.  There's always
66 Conkeror...
67
68 --[[JasonBlevins]], March 22, 2008 10:35 EDT
69
70 ----
71
72 I've written a plugin to implement access keys, configured using a wiki page similar to [[shortcuts]]. It works for links and most form submit buttons.
73
74 As I am new to ikiwiki plugin writing, feedback is greatly appreciated.
75
76 [[!toggle  id="accesskeys" text="Toggle: accesskeys.pm"]]
77
78 [[!toggleable  id="accesskeys" text="""
79
80         #!/usr/bin/perl
81         
82         package IkiWiki::Plugin::accesskeys;
83         
84         use warnings;
85         use strict;
86         use IkiWiki 3.00;
87         use CGI::FormBuilder;
88         
89         =head1 NAME
90         
91         accesskeys.pm - IkiWiki module to implement access keys (keyboard shortcuts)
92         
93         =head1 VERSION
94         
95         v.5.0 - initial version
96         
97         =head1 DESCRIPTION
98         
99         Access keys are defined on a page called B<accesskeys>, using the C<accesskey> directive.
100         Example:
101         
102             [[!accesskey command="Save Page" key="s"]]
103         
104         B<command> may contain only alphanumeric characters (and spaces), and must be a complete 
105         match to the target link or submit button's display name. 
106         
107         B<key> may only be a single alphanumeric character. 
108         
109         The access key is applied to the first matching link on a page (including header), or the 
110         first matching submit button in the @buttons array.
111         
112         The wiki must be completely rebuilt every time the B<accesskeys> page changes.
113         
114         =head2 Sample accesskeys page
115         
116             [[!if test="enabled(accesskeys)"
117                 then="This wiki has accesskeys **enabled**."
118                 else="This wiki has accesskeys **disabled**."]]
119         
120             This page controls what access keys the wiki uses.
121         
122             * [[!accesskey command="Save Page" key="s"]]
123             * [[!accesskey command="Cancel" key="c"]]
124             * [[!accesskey command="Preview" key="v"]]
125             * [[!accesskey command="Edit" key="e"]]
126             * [[!accesskey command="RecentChanges" key="c"]]
127             * [[!accesskey command="Preferences" key="p"]]
128             * [[!accesskey command="Discussion" key="d"]]
129         
130         =head1 IMPLEMENTATION
131         
132         This plugin uses the following flow:
133         
134         =over 1
135         
136         =item 1. Override default CGI::FormBuilder::submit function
137         
138         FormBuilder does not support any arbitrary modification of it's submit buttons, so
139         in order to add the necessary attributes you have to intercept the internal function
140         call which generates the formatted html for the submit buttons. Not pretty, but it 
141         works.
142         
143         =item 2. Get list of keys 
144         
145         During the B<checkconfig> stage the B<accesskeys> source file is read (default 
146         F<accesskeys.mdwn>) to generate a list of defined keys.
147         
148         =item 3. Insert keys (links)
149         
150         Keys are inserted into links during the format stage. All defined commands are checked 
151         against the page's links and if there is a match the key is inserted. Only the first 
152         match for each command is processed.
153         
154         =item 4. Insert keys (FormBuilder buttons)
155         
156         FormBuilder pages are intercepted during formatting. Keys are inserted as above. 
157         
158         =back
159         
160         =head1 TODO
161         
162         =over 1
163         
164         =item * non-existant page links ex: ?Discussion
165         
166         =item * Support non-submit array buttons (like those added after the main group for attachments)
167         
168         =item * Support form fields (search box)
169         
170         =back
171         
172         =cut
173         
174         #=head1 HISTORY
175         
176         =head1 AUTHOR
177         
178         Written by Damian Small.
179         
180         =cut
181         
182         my %accesskeys = ();
183         
184         # Initialize original function pointer to FormBuilder::submit
185         my $original_submit_function = \&{'CGI::FormBuilder::submit'};
186         # Override default submit function in FormBuilder
187         {    
188             no strict 'refs';
189             no warnings;
190             *{'CGI::FormBuilder::submit'} = \&submit_override;
191         }
192         
193         sub submit_override {
194             # Call the original function, and get the results
195             my $contents = $original_submit_function->(@_);
196         
197             # Hack the results to add accesskeys
198             foreach my $buttonName (keys %accesskeys) {
199                 $contents =~ s/(<input id="_submit[^>]+ value="$buttonName")( \/>)/$1 title="$buttonName [$accesskeys{$buttonName}]" accesskey="$accesskeys{$buttonName}"$2/;
200             }
201         
202             return $contents;
203         }
204         
205         sub import {
206             hook(type => "getsetup", id => "accesskeys", call => \&getsetup);
207             hook(type => "checkconfig", id => "accesskeys", call => \&checkconfig);
208             hook(type => "preprocess", id => "accesskey", call => \&preprocess_accesskey);
209             hook(type => "format", id => "accesskeys", call => \&format);
210         }
211         
212         sub getsetup () {
213             return
214                 plugin => {
215                     safe => 1,
216                     rebuild => 1,
217                     section => "widget",
218             },
219         }
220         
221         sub checkconfig () {
222             if (defined $config{srcdir} && length $config{srcdir}) {
223                 # Preprocess the accesskeys page to get all the access keys
224                 # defined before other pages are rendered.
225                 my $srcfile=srcfile("accesskeys.".$config{default_pageext}, 1);
226                 if (! defined $srcfile) {
227                     $srcfile=srcfile("accesskeys.mdwn", 1);
228                 }
229                 if (! defined $srcfile) {
230                     print STDERR sprintf(gettext("accesskeys plugin will not work without %s"),
231                                          "accesskeys.".$config{default_pageext})."\n";
232                 }
233                 else {
234                     IkiWiki::preprocess("accesskeys", "accesskeys", readfile($srcfile));
235                 }
236             }
237         }
238         
239         sub preprocess_accesskey (@) {
240             my %params=@_;
241             
242             if (! defined $params{command} || ! defined $params{key}) {
243                 error gettext("missing command or key parameter");
244             }
245             
246             # check the key
247             if ($params{key} !~ /^[a-zA-Z0-9]$/) {
248                 error gettext("key parameter is not a single character");
249             }
250             # check the command
251             if ($params{command} !~ /^[a-zA-Z0-9 _]+$/) {
252                 error gettext("command parameter is not an alphanumeric string");
253             }
254             # Add the access key:
255             $accesskeys{$params{command}} = $params{key};
256         
257             return sprintf(gettext("[%s] is the access key for command '<i>%s</i>'"), $params{key}, $params{command});
258         }
259         
260         sub format (@) {
261             my %params = @_;
262             my $contents = $params{content};
263          
264             # If the accesskey page changes, all pages will need to be updated
265             #debug("Adding dependency: for " . $params{page} . " to AccessKeys");
266             add_depends($params{page}, "AccessKeys");
267         
268             # insert access keys
269             foreach my $command (keys %accesskeys) {
270                 $contents =~ s/(<a href=[^>]+)(>$command<\/a>)/$1 accesskey="$accesskeys{$command}"$2/;
271             }
272             # may need special handling for non-existant discussion links (and possibly other similar cases?)
273             #$contents =~ s/(<a href=[^>]+)(>\?<\/a>Discussion)/$1 accesskey="d"$2/;
274         
275             return $contents;
276         }
277         
278         1
279
280
281 [[!toggle id="accesskeys" text="hide accesskeys.pm"]]
282 """]]
283
284 --[[DamianSmall]]
285
286 [[!tag wishlist]]