Differences

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

--- devel:toolbar [2016-05-08 00:00] – Klap-in
+++ devel:toolbar [2019-04-21 03:47] – Dr-Yukon
@@ Line 1: / Line 1: @@
 ====== 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) =====
@@ 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.
-This means, the 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 ====
@@ 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.
 ===== 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 approach, you will always need to write a plugin, the JavaScript method can be used from a [[javascript|userscript]] as well.
 ==== ...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 a 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''.
@@ Line 70: / Line 70: @@
 }
 </code>
+Try to use [[plugin:custombuttons]]
 ==== ...using JavaScript ====
@@ Line 114: / Line 116: @@
 </code>
 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.
   * More about [[devel:localization#javascript localization]]
@@ Line 120: / Line 122: @@
 ==== 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. Instead, you 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.
-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]].
@@ 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.
   * 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.
+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.