DokuWiki

It's better when it's simple

User Tools

Site Tools


devel:toolbar

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
Both sides next revision
devel:toolbar [2013-12-05 22:00]
Klap-in
devel:toolbar [2019-04-21 03:47] (current)
Dr-Yukon
Line 1: Line 1:
 ====== The Toolbar ====== ====== The Toolbar ======
  
-The [[:toolbar]] makes DokuWiki easy to use even for novice users. Sometimes you may want to extend the toolbar with another button. This page will tell you a bit how the toolbar works and how to extend it.+The [[:toolbar]] makes DokuWiki easy to use even for novice users. Sometimes you may want to extend the toolbar with another button. This page will tell you a bit about how the toolbar works and how to extend it.
  
 ===== How the toolbar is built (and cached) ===== ===== How the toolbar is built (and cached) =====
Line 7: Line 7:
 The toolbar is completely built through [[JavaScript]]. Which buttons the toolbar contains, is read from an array called ''toolbar''. This array is initialized in ''/lib/exe/js.php''. This is simply done by converting the PHP array structure defined in ''**inc/toolbar.php**'' to JavaScript using JSON. The toolbar is completely built through [[JavaScript]]. Which buttons the toolbar contains, is read from an array called ''toolbar''. This array is initialized in ''/lib/exe/js.php''. This is simply done by converting the PHP array structure defined in ''**inc/toolbar.php**'' to JavaScript using JSON.
  
-This meansthe toolbar gets cached like any other JavaScript in DokuWiki. When ever you do changes affecting the toolbar you should invalidate DokuWiki's [[caching|cache]] (eg. ''touch conf/local.php'') and refresh your browser cache while editing a page (Hit Shift/Ctrl-Reload and ignore the post warning).  +This means the toolbar gets cached like any other JavaScript in DokuWiki. Whenever you do changes affecting the toolbar you should invalidate DokuWiki's [[caching|cache]] (eg. ''touch conf/local.php'') and refresh your browser cache while editing a page (Hit Shift/Ctrl-Reload and ignore the post warning). 
  
 ==== The toolbar array ==== ==== The toolbar array ====
Line 20: Line 19:
 | ''title'' | title of the button, displayed on mouseover | | ''title'' | title of the button, displayed on mouseover |
 | ''icon'' | icon to use for the button (based in ''DOKUBASE/lib/images/toolbar/'')| | ''icon'' | icon to use for the button (based in ''DOKUBASE/lib/images/toolbar/'')|
-| ''key'' | Hotkey for the button, a value of ''n'' here would result in the button being pressed when the user presses ''ALT + n'' in his browser. (See also the [[:accesskeys|access keys]] used by DokuWiki) |+| ''key''(optional) Hotkey for the button, a value of ''n'' here would result in the button being pressed when the user presses ''ALT + n'' in his browser. (See also the [[:accesskeys|access keys]] used by DokuWiki) 
 +| ''class'' | (optional) classname for styling buttons | 
 +| ''id''    | (optional) id added to button, and with a postfix to icon e.g. ''<id>_ico'' |
 ^ ''format'' type specific parameters  ^^ ^ ''format'' type specific parameters  ^^
 | ''open'' | opening tag of wiki markup to insert, cursor will be placed between opening and closing tag | | ''open'' | opening tag of wiki markup to insert, cursor will be placed between opening and closing tag |
Line 31: Line 32:
 | ''options'' | additional options for the popup window (comma-separated name-value-pairs valid as parameters for the JS function ''window.open'' | | ''options'' | additional options for the popup window (comma-separated name-value-pairs valid as parameters for the JS function ''window.open'' |
 ^ ''picker'' type specific parameters  ^^ ^ ''picker'' type specific parameters  ^^
-| ''list'' | list of insertable items. can either be an associative array (with the item to insert as the key and an image to use as the value) or just a simple array (with the text-items to insert directly displayed) | +| ''list'' | list of insertable items. can either be an associative array (with the item to insert as the key and an image located in ''icobase'' to use as the value) or just a simple array (with the text-items to insert directly displayed) | 
-| ''icobase''basedirectory for item images (based in ''DOKUBASE/lib/images/''). |+| ''icobase''subdirectory for item images (based in ''DOKUBASE/lib/images/''). |
  
 A look at [[xref>inc/toolbar.php]] should give you enough examples of what can be defined. Because the array is simply translated from PHP to JavaScript, the above description applies to the PHP array as well as to the resulting JavaScript array from which the toolbar is finally built. A look at [[xref>inc/toolbar.php]] should give you enough examples of what can be defined. Because the array is simply translated from PHP to JavaScript, the above description applies to the PHP array as well as to the resulting JavaScript array from which the toolbar is finally built.
 +
 ===== Extending the Toolbar... ===== ===== Extending the Toolbar... =====
  
-The toolbar can be customized in two ways - via JavaScript or PHP. Which method you choose basically depends on your skills and familiarity with the language at hand. For the PHP approach you will always need to write a plugin, the JavaScript method can be used from a [[javascript|userscript]] as well.+The toolbar can be customized in two ways - via JavaScript or PHP. Which method you choose basically depends on your skills and familiarity with the language at hand. For the PHP approachyou will always need to write a plugin, the JavaScript method can be used from a [[javascript|userscript]] as well.
  
 ==== ...using PHP ==== ==== ...using PHP ====
  
-To extend the toolbar from your plugin you need to write a [[devel:Action Plugin]] which registers as handler for the [[events_list#toolbar_define|TOOLBAR_DEFINE]] event with an AFTER advise. Your handler function will receive the toolbar array as described earlier.+To extend the toolbar from your plugin you need to write a [[devel:Action Plugin]] which registers as handler for the [[devel:event:TOOLBAR_DEFINE]] event with an AFTER advice. Your handler function will receive the toolbar array as described earlier.
  
 Create your button structure according to the above information and add it to the received event data.-function in ''inc/toolbar.php''. Create your button structure according to the above information and add it to the received event data.-function in ''inc/toolbar.php''.
Line 57: Line 59:
  * Inserts a toolbar button  * Inserts a toolbar button
  */  */
-function insert_button($event, $param) {+function insert_button(Doku_Event $event, $param) {
     $event->data[] = array (     $event->data[] = array (
         'type' => 'format',         'type' => 'format',
Line 68: Line 70:
 } }
 </code> </code>
 +
 +Try to use [[plugin:custombuttons]]
  
 ==== ...using JavaScript ==== ==== ...using JavaScript ====
Line 112: Line 116:
 </code> </code>
 Some notes: Some notes:
-  * Be aware of the default locations of the images ''lib/images/toolbar/'' and ''lib/images/''+  * Be aware of the default locations of the images''lib/images/toolbar/'' and ''lib/images/''
   * The available options for access keys depends on the [[:accesskeys|access keys]] used by DokuWiki and the whether they are reserved by a browser or operation system as short cut. There are many differences.   * The available options for access keys depends on the [[:accesskeys|access keys]] used by DokuWiki and the whether they are reserved by a browser or operation system as short cut. There are many differences.
   * More about [[devel:localization#javascript localization]]   * More about [[devel:localization#javascript localization]]
Line 118: Line 122:
 ==== Dynamic Data ==== ==== Dynamic Data ====
  
-The above methods work well for adding static buttons that add static data. When you need to do something more dynamic like adding the current date, you can not simply extend the ''toolbar'' array. Instead you need to dynamically add your button into the DOM using [[JavaScript]]. +The above methods work well for adding static buttons that add static data. When you need to do something more dynamic like adding the current date, you can not simply extend the ''toolbar'' array. Insteadyou need to dynamically add your button into the DOM using [[JavaScript]]. 
  
 The files [[xref>lib/scripts/edit.js]], [[xref>lib/scripts/toolbar.js]] and [[xref>lib/scripts/linkwiz.js]] contains some useful functions to help you with this. The files [[xref>lib/scripts/edit.js]], [[xref>lib/scripts/toolbar.js]] and [[xref>lib/scripts/linkwiz.js]] contains some useful functions to help you with this.
  
-When adding to the ''toolbar'' array you must set a custom value for ''type'' You must use characters that are valid in a function name and should capitalize the first character.  When the toolbar is constructed it looks at the value of ''type'' and appends it to the string ''addBtnAction'' before calling your code.  So if you set ''type'' to ''Click'' the toolbar will call ''addBtnActionClick'' This is an important note because if two plugins use the same ''type'' they will conflict with each other and cause strange behavior (such as both buttons doing the exact same thing).+When adding to the ''toolbar'' array you must set a custom value for ''type'' You must use characters that are valid in a function name and should capitalize on the first character.  When the toolbar is constructed it looks at the value of ''type'' and appends it to the string ''addBtnAction'' before calling your code.  So if you set ''type'' to ''Click'' the toolbar will call ''addBtnActionClick'' This is an important note because if two plugins use the same ''type'' they will conflict with each other and cause strange behavior (such as both buttons doing the exact same thing). 
 + 
 +The returned string is "the id for in aria-control". This is explained further in [[http://msdn.microsoft.com/en-us/library/windows/apps/hh767301.aspx|Accessible Rich Internet Applications]]. 
  
 Here is an example partly from the toolbar picker: Here is an example partly from the toolbar picker:
Line 175: Line 182:
   * If you don't want to append your button at the end of the toolbar, you just need to insert your data into the ''toolbar'' array at the position where you want your button, shifting the other buttons to the right.   * If you don't want to append your button at the end of the toolbar, you just need to insert your data into the ''toolbar'' array at the position where you want your button, shifting the other buttons to the right.
   * There are some [[devel:javascript#predefined global variables]] available which you can access from your Javascript. For example JSINFO contains the page id and namespace, usage: ''JSINFO.namespace''. This might be handy when doing some more dynamic stuff.   * There are some [[devel:javascript#predefined global variables]] available which you can access from your Javascript. For example JSINFO contains the page id and namespace, usage: ''JSINFO.namespace''. This might be handy when doing some more dynamic stuff.
-  * **Important**: If the button does not appear, expire the cache of your DokuWiki by saving your config in the Config Manager or touching the ''conf/local.php'' of your wiki AND delete your browser cache (Ctrl+F5 or Ctrl+R)! Than reload the editor page and your button should appear.+  * **Important**: If the button does not appear, expire the cache of your DokuWiki by saving your config in the Config Manager or touching the ''conf/local.php'' of your wiki AND delete your browser cache (Ctrl+F5 or Ctrl+R)! Then reload the editor page and your button should appear
 + 
 + 
 +=== Removing Buttons === 
 + 
 +If you want to remove some of the toolbar buttons, you can do so by adding the following code into ''/conf/userscript.js''. Note that this is not in any function, simply append this code to the end of the file: 
 + 
 +<code javascript /conf/userscript.js> 
 +if (typeof window.toolbar !== 'undefined') { 
 +   var blacklist = ["Bold Text", "Italic Text", "Underlined Text", "Monospaced Text", "Strike-through Text",  
 +   "Same Level Headline", "Lower Headline", "Higher Headline", "Select Headline", "Internal Link", "External Link",  
 +   "Horizontal Rule", "Add Images and other files (opens in a new window)", "Smileys", "Special Chars", "Insert Signature"]; 
 +    window.toolbar = window.toolbar.filter(function(elem){ return jQuery.inArray(elem.title, blacklist) === -1; }); 
 +
 +</code> 
 + 
 +This is from my personal wiki where I removed almost all the buttons. You can figure out what the title of your button is by running the following snippet in a javascript console: 
 +<code javascript>for (i in window.toolbar) { console.log(toolbar[i].title)}</code> 
 + 
 +Then take the string and append it to the 'blacklist' array in the code. 
 + 
 +See also the [[plugin:toolbuttondel|]] plugin for removing toolbar items. 
 + 
 +===== CSS Spritemap ===== 
 + 
 +If you need to reduce the number of server requests for downloading micro-icons, you can use the following style fix.\\ 
 +  - 15 icons of the 20 in the ''/lib/images/toolbar/'' folder are used in a constant order and can be combined into a vertical ribbon named **spritemap**. 
 +    - You can take the finished spritemap [[https://comicslate.org/lib/images/toolbar/toolbar.png|here]] and put it in ''/lib/images/toolbar/'' named as ''toolbar.png''
 +  - CSS used to show a certain point on spritemap. 
 +    - Add the following CSS rules to your local style file ''/conf/userstyle.less'' or template's style file ''/lib/tpl/<name>/css/design.less'': 
 +<code css> 
 +#tool__bar { 
 + button:nth-of-type(1), button:nth-of-type(2), button:nth-of-type(3), button:nth-of-type(4), button:nth-of-type(5), 
 + button:nth-of-type(6), button:nth-of-type(7), button:nth-of-type(8), button:nth-of-type(9), button:nth-of-type(10), 
 + button:nth-of-type(11), button:nth-of-type(12), button:nth-of-type(13), button:nth-of-type(14), button:nth-of-type(15) { 
 + background: url(/lib/images/toolbar/toolbar.png); 
 + height: 16px; 
 + margin: 4px 7px 3px 3px; 
 + vertical-align: middle; 
 + width: 16px; 
 + img { 
 + display: none; 
 +
 +
 + button:nth-of-type(1) { background-position: 0 0; } 
 + button:nth-of-type(2) { background-position: 0 -16px; } 
 + button:nth-of-type(3) { background-position: 0 -32px; } 
 + button:nth-of-type(4) { background-position: 0 -48px; } 
 + button:nth-of-type(5) { background-position: 0 -64px; } 
 + button:nth-of-type(6) { background-position: 0 -80px; } 
 + button:nth-of-type(7) { background-position: 0 -96px; } 
 + button:nth-of-type(8) { background-position: 0 -112px; } 
 + button:nth-of-type(9) { background-position: 0 -128px; } 
 + button:nth-of-type(10) { background-position: 0 -144px; } 
 + button:nth-of-type(11) { background-position: 0 -160px; } 
 + button:nth-of-type(12) { background-position: 0 -176px; } 
 + button:nth-of-type(13) { background-position: 0 -192px; } 
 + button:nth-of-type(14) { background-position: 0 -208px; } 
 + button:nth-of-type(15) { background-position: 0 -224px; } 
 +
 +</code> 
 + 
 +Maybe one day this fix will be obsolete due to the introduction of spritemap in the Dokuwiki.
devel/toolbar.1386277206.txt.gz · Last modified: 2013-12-05 22:00 by Klap-in