You are here: start » snippets » dokuwiki » keyboard

Keyboard Plugin

Description

The keyboard plugin provides a combined syntax and action plugin in order to markup text as keyboard keys, similar to (and making use of) the existing (X)HTML tag <kbd>…</kbd>. A quick button for the markup is automatically inserted into the toolbar of the edit form.

In case you come across any bugs in this plugin, don't hesitate to report them.

The Darcs repository of the plugin can be found here.

Updates

Last updated: 2008/05/04

  • 2008/05/04:
  • 2007/07/17:
    • Fixed a small bug in the german language file (swapped Pageup/Pagedown translations, thanks go to Werner Mayer for the tip-off).
  • 2007/04/11:
    • Fixed the stylesheetname (styles.cssstyle.css, thanks to John Friar for the heads-up)
  • 2007/04/05:
  • 2007/04/03:
    • Fixed typo in english language file.
  • 2007/03/30:
    • Bugfix: 12
  • 2005/10/10:
    • Small bugfix (substitutionsubstition)
  • 2005/10/02:
    • Keycombination support

Acknowledgements

Special thanks to Christopher Arndt for suggestions and enhancements.

Syntax

Enclose the name of a key, or a combination of keys, separated by a dash (-), in a key tag, like this:

<key>Key</key> or <key>C-x</key>
  • The text inside the key tag is split at the occurrences of - (dash).
  • Each part is trimmed (surrounding whitespace removed) and known shortcuts or key names are substituted. E.g. C becomes Ctrl, Left becomes &larr; etc.
  • The substitutions are language specific. So, e.g. in German, C becomes Strg and Del becomes Entf. Only English and German are supported at the moment. Feel free to write additional language files and send them in for inclusion.
  • If no substitution was found, the first letter is capitalized and special HTML chars are replaced with entities.
  • The substitution table only has key aliases that begin with a capital letter. So lower letters will not be substituted, only capitalized and, for example, C-c becomes Ctrl-C
  • If you want to express the dash (-) key, use Minus.
  • If you don't want any trimming, alias or language substitution, or capitalization, enclose your key name in single quotes.

Examples:

  • Ctrl+Alt+Del to reboot. (<key>C-A-del</key>)
  • Ctrl+C to copy text to the clipboard. (<key>C - c</key>)
  • Ctrl+X to cut text and put it into the clipboard. (<key>C-x</key>)
  • Ctrl+V to paste text from the clipboard. (<key>C-v</key>)
  • Ctrl+Enter to insert a page break. (<key>C-enter</key>)
  • Ctrl+Shift+ to select from current cursor position to end of a word. (<key>C-S-Right</key>)
  • Ctrl+Shift+ to select from current cursor position to the beginning of a word. (<key>C-S-Left</key>)
  • Ctrl+Page↑ to go one screen page up. (<key>C-PageUp</key>)
  • Ctrl+ (<key>C-Minus</key>)
  • any key to exit. (<key>'any key'</key>)

Installation

With plugin manager

Let the manager do the dirty work, just give him this link to eat: plugin-keyboard.tar.gz

Without plugin manager

  1. Download the plugin: plugin-keyboard.tar.gz
  2. Extract it into your dokuwiki plugin folder (eg lib/plugins)

Quickbutton

A quickbutton is now inserted into the toolbar of the edit form via a small action plugin. In order for that button to show up, you might first need to purge the cached JavaScript by once calling http://www.yoursite.com/path/to/dokuwiki/lib/exe/js.php?edit=1&write=1&purge=1. Also, reload your edit form properly to purge any cached toolbar definitions from the browser cache as well.

As the event the plugin reacts on is only available in the Development version, the automaticly inserted quick button is only available in this version as well. For manual installation in prior versions of Dokuwiki – e.g. in version 20061106 – in inc/toolbar.php right after

   array(
      'type'   => 'signature',
      'title'  => $lang['qb_sig'],
      'icon'   => 'sig.png',
      'key'    => 'y',
   ),

add

   array(
      'type' => 'format',
      'title' => 'Mark text as key press',
      'icon' => '../../plugins/keyboard/keyboard.png',
      'open' => '<key>',
      'close' => '</key>',
   ),

More key name substitutions & translations

  • Create a directory with the two-letter code of your language in lib/plugins/keyboard/lang
  • Copy the file lib/plugins/keyboard/lang/de/lang.php to this directoy.
  • Edit the file and make your translations.
  • For substitutions that apply for all languages, edit lib/plugins/keyboard/lang/en/lang.php and make sure you don't override these in the other languages.

Discussion

Esther BrunnerEsther Brunner, 2005/09/29 23:37

Hi Gina

Nice plugin! A small suggestion: Instead of adding the style definition to design.css, create a file style.css in your plugin’s folder, that also works. And then you can create a .zip archive of the folder for the auto-install with the Plugin Manager by Christopher Smith. (btw: I know, I should update my older plugins on splitbrain which still recommend adding to design.css).

Gina HaeussgeGina Haeussge, 2005/09/30 00:06

Oh cool, thank you for that tip, I didn’t know that was also possible. Will change that asap :)

John FriarJohn Friar, 2007/04/11 17:15

In the current version of your keyboard plugin, the style sheet is named “styles.css” - my version of dokuwiki (dokuwiki-2006-11-06) needs the file to be named “style.css” in order to work (at least so far as the css styles are concerned).

Great plugin though!

Gina HaeussgeGina Haeussge, 2007/04/11 18:09

Should be fixed now.

Christopher ArndtChristopher Arndt, 2005/09/30 02:03

Nide idea! How about having shortcuts for the modifier keys? For example, if you wrote <key>C-v</key> it would automatically expand to the equivalent of <key>Ctrl</key> + <key>v</key>.

Gina HaeussgeGina Haeussge, 2005/09/30 12:31

Interesting suggestion. I’ll have to take a look into how to accomplish that, but I like the idea very much.

Pavel VitisPavel Vitis, 2005/09/30 18:12

Great idea! I have suggestion here. Usually one is writing this as: Press [ctrl]+[alt][del] So my suggestion is, parse such text where [] and + are together, as keys. It would be simpler to write than <key></key> and as well would be perfectly readable in raw dokuwiki.

Gina HaeussgeGina Haeussge, 2005/09/30 20:11

The problem with this would be that then no single keys would be possible anymore. I don’t think it would be a good idea to convert everything in [] into keys (”see [1]” for example would look weird), so the plugin would have to be limited to key-combinations (like Ctrl+Alt+Del), nothing like “Hit <key>Enter</key>“. I do agree with you though, I’d prefer a better markup than the key tags as well. Any non conflicting, good looking suggestions?

Christopher ArndtChristopher Arndt, 2005/10/01 15:26

I suggest adding the the follwing CSS:

background-color: white;

since not everybody has a wiki with a white background. :-)

Dmitry CherniachenkoDmitry Cherniachenko, 2005/10/03 10:54

Concerning Pavel Vitis proposal. I think you could add one more (meaning keeping the existing way of using <key> tag) pattern like: \[\w+?\](\s?+\s?\[[\w\d]+?\])+ (not sure if it’s really work as intended ;-) ).
Then it will catch [Ctrl]+[1] or [Ctrl] + [Alt] + [Del] but will not catch things like [1] or [Home]. For single keys one will still have to use <key> tag.

You could even limit prefixes to modifier keys only (e.g. not to catch [Abc]+[D]) but IMO it does not worth the efforts.

Uwe KirbachUwe Kirbach, 2005/10/09 18:49

Cool plugin.

Please replace the function:

    function getAllowedTypes() {
        return array('formatting', 'substitution', 'disabled');
    }

with

    function getAllowedTypes() {
        return array('formatting', 'substition', 'disabled');
    }

Otherwise you get tons of error messages like:

PHP Warning:  in_array() [<a href='function.in-array'>function.in-array</a>]: Wrong datatype for second argument in D:\web\dokuwiki\inc\parser\parser.php on line 159
Gina HaeussgeGina Haeussge, 2005/10/10 12:49

Thank you, didn’t encounter any problems so far with the former (although I can’t explain this), but changed it anyway, as the plugin-tutorial seems to say the same :-)

PabloPablo, 2005/10/17 08:38

Nice plugin. I offer a modified CSS though. I trimmed it down in places but also tried to make it look slicker. You’ll need to download the image from http://www.p-a-b-l-o.com/downloads/dokuwiki/plugin-keyboard/keybg.gif.

kbd {
  font-family: Arial,sans-serif;
  font-weight: bold;
  color: #444;
  text-align: center;
  padding: 1px 4px;
  margin: 0px 2px;
  border-style: solid;
  border-width: 1px;
  border-color: #ccc #666 #666 #ccc;
  background: url(keybg.gif) #fafafa no-repeat;
}
Truett HunterTruett Hunter, 2006/04/21 17:43

A couple of gotcha for noobs like me. The file links in the Without plugin manager section are older and don’t work (at least for me). The files in the With plugin manager section are current and work just fine.

I tried to install the quick button Extra, and had to modify the html_edit line from ‘&lt;key&gt;’ to ‘<key>’ (and the same with the /key) to get it to display the correct code in the text area.

These problems could be cause by my extreme noobishness.

Other than those 2 items, this plugin look really cool. Thanks!

Steve CarsonSteve Carson, 2006/05/27 19:10

Anyway to add an option for the “Windows” key?

Jernej JakobJernej Jakob, 2006/07/04 21:58
* Add the following code to inc/html.php, approximately after line 914, in the function html_edit():
formatButton('keyboard.png','<?php echo >$lang['qb_keyb']?>','&lt;key&gt;','&lt;/key&gt;','<?php echo $lang['qb_keyb']?>','k');

Could somebody say exactly where to put this code? Possibly include a snippet of html.php?

P.S. offtopic - you haven’t disabled debugging support - see http://wiki.foosel.net/doku.php?do=check

Gina HaeussgeGina Haeussge, 2006/07/05 10:15

Thanks for the heads-up concerning the debugging support. Must somehow have not taken a look at my check output for a loooong time ;)

Anyway, the place to add the format button seems not to be the html.php any longer, as the toolbar has been changed to some javascript thingy. ATM I can’t seem to find where to place the code now, but I will try to find out and update the wiki accordingly :)

Robert RiebischRobert Riebisch, 2007/03/30 14:40

After updating DokuWiki to `dokuwiki-2006-11-06.tgz’ I always get this error when saving pages with keyboard tags: * Warning: Cannot modify header information - headers already sent by (output started at /wiki/lib/plugins/keyboard/lang/en/lang.php:1) in /wiki/inc/actions.php on line 287 *

It was hard to find (at least for me), but the solution is easy: The language files provided with your .zip or tar.gz archives are in wrong format. These are in UTF-8, but DokuWiki (or some other software underlying) needs it in UTF-8 without a Byte Order Mark (BOM). (I used Notepad++ to convert.)

Best would be to take the content from keyboard#langenlang.php and keyboard#langdelang.php, save it correctly, and upload new archives.

Gina HaeussgeGina Haeussge, 2007/03/30 16:31

Thanks for the heads-up, I will look into it ASAP. Sorry for the inconvenience.

Gina HaeussgeGina Haeussge, 2007/03/30 17:20

Should be fixed now (at least it worked on my test installation here). I kinda wonder though how those BOMs slipped in... Anway, thanks for reporting this!

Robert RiebischRobert Riebisch, 2007/04/03 17:00

Thanks for the update, but I wonder, why I wrote detailed. You didn’t take the contents from this page. Now we still have the string “german version” in “lang/en/lang.php”. :-(

Gina HaeussgeGina Haeussge, 2007/04/03 17:50

Ooops... I didn’t see that one. Have corrected that now (but at least it wasn’t a critical bug ;)) and removed the source code from the page – people who want to take a look at it can download the plugin, and I can’t forget to keep it synched with the actual source anymore.

Robert RiebischRobert Riebisch, 2007/04/03 19:37

The download still has “german version”. ;-)

Gina HaeussgeGina Haeussge, 2007/04/03 19:57

I’m starting to doubt my sanity... I could swear I fixed it in my local version, saved it, packed the tarball and upped it. But it looks like I didn’t. I think I need a vacation, damn this bloody diploma thesis... sorry again ;-)

I just downloaded that thing, unpacked it, and now it IS fixed for sure *cough*

Werner MayerWerner Mayer, 2007/07/17 21:38

Hi Gina! In the german translation the PageDown and PageUp arguments are switched.

Gina HaeussgeGina Haeussge, 2007/07/17 22:20

Thanks for the hint, should be fixed in the current download :)

Daniel SchranzDaniel Schranz, 2007/08/30 14:17

Nice plugin, thanks for your work. One small suggestion though: When Camelcase-links are activated PageUp isn't replaced with the symbol instead the key is displayed with a link to the 'PageUp'-page. Perhaps replace 'PageUp' with 'Pageup'?

webwesenwebwesen, 2008/05/12 22:44

I think in the latest version the path to purge cached javascript is :

http://your.domain.com/path/to/dokuwiki/lib/exe/js.php?edit=1&write=1&purge=1
fooselfoosel, 2008/05/12 22:55

You are right, that was a typo, thanks for pointing this out.

Hugo BossardHugo Bossard, 2008/06/03 07:35

Your plugin works like a charm on my local xampp installation. However, on our intranet with IIS6.0, PHP 4.4.8 it does not. This means, that e.g. Ctrl+Alt+D is translated to Strg-Alt-D but the nice graphics formatting around it is completely missing. What can be the cause?

Hugo BossardHugo Bossard, 2008/06/03 11:44

I figured ist out: It works with PHP 5.2.6. May be the minimum version of PHP should be mentioned in the requirements of the plugin.

fooselfoosel, 2008/06/03 12:09

I actually was not aware of such a version issue. Could you maybe check again if the generated website source code on your IIS + PHP 4.4.8 installation contains a <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>Del</kbd> HTML markup? If it does, the plugin works flawlessly, and the problem is probably caused by some simple CSS-caching issues. If not, that would be a very interesting hint for debugging.

Enter your comment (wiki syntax is allowed):
SYHNZ
snippets/dokuwiki/keyboard.txt · Last modified: 2008/05/12 22:55 by foosel