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 [2016-06-09 22:55]
24.78.88.211 [...using JavaScript]
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 37: Line 36:
  
 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 [[devel:event: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 70: Line 70:
 } }
 </code> </code>
 +
 +Try to use [[plugin:custombuttons]]
  
 ==== ...using JavaScript ==== ==== ...using JavaScript ====
Line 120: 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]]. 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]].
Line 180: 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.
  
  
Line 201: Line 203:
 Then take the string and append it to the 'blacklist' array in the 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.1465505737.txt.gz · Last modified: 2016-06-09 22:55 by 24.78.88.211