====== tocselect Plugin ====== ---- plugin ---- description: Create table of contents for any wiki page in sidebar or in a wiki page. The TOC can be set using a textbox selection, the wiki:id for which can be changed as needed either manually or from its index of pages and namespaces, or it can be set to automatically load the TOC for the currently displayed page. author : Myron Turner email : turnermm02@shaw.ca type : syntax, action lastupdate : 2017-12-07 compatible : Ponder Stibbons, Hrun, Detritus, Elenor of Tsort, Frusterick Manners, Greebo, Hogfather depends : conflicts : similar : toc,inlinetoc,nstoc,tocafterheadline tags : toc,sitemap,index downloadurl: https://github.com/turnermm/tocselect/archive/master.zip bugtracker : https://github.com/turnermm/tocselect/issues sourcerepo : https://github.com/turnermm/tocselect donationurl: http://mturner.org/userfiles/donate.php screenshot_img : ---- ===== Installation ===== Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually. ===== Purpose ===== This plugin inserts a TOC and namespace index into the sidebar or into the current page. Depending on the syntax, the TOC may be for either a user-selected page or for the current page when configured to be automatically updated. When inserted into a wiki page, it replaces the Dokuwiki TOC. There is a Configuration Option which suppresses Dokuwiki's TOC. This is useful when the ''tocselect'' listing is placed in the sidebar and is set to be automatically updated to the current page. You can install only one ''tocselect'' listing at a time, that is it cannot be inserted simultaneously both into the sidebar and into the adjacent page. If this occurs, the sidebar takes precedence and the TOC/Index does not print to the page. A ''toselect'' listing can be placed vertically anywhere on the page, not just at the top. To change the horizontal alignment, you would have to make the relevant changes to ''.dokuwiki .tocsel_right'' in the plugin directory: tocselect/style.css. ===== Syntax ===== ==== Manual TOC Selection ==== ~~SELECTTOC~~ This format will create a textbox with a button. You then enter a ''wiki id'' into the text box and click the button. The table of contents for the selected page will load beneath the textbox. The list items in the TOC are clickable. If the TOC is in a sidebar, the ''tocselect'' TOC will retain its settings between page changes. ==== Auto-Selection of Current Page ID ==== ~~SELECTTOC>curID~~ This format will automatically select and open the TOC for the currently displayed page. In addition it retains the selection box illustrated in the previous form, making it possible to enter an alternate page ID. But when the page reloads, it will switch back to the current ID. ===== 'tocselect' Listings ====== Whichever of the above two syntax methods you use, the basic display and functioning is the same for both. ==== Index Listing ==== {{ http://mturner.org/userfiles/doku/index-2_zpsendkns6z.png?225 }} The ''Index'' lists both pages and namespaces. The items in bold are namespaces; when clicked they will moved down the namespace hierarchy into their own namespaces. ''The colon-asterisk'' markup '':*'' indicates a namespace. Page names (green) are modeled on Dokuwiki internal links and when clicked will load the [[#table_of_contents_listings|Table of Contents]] for the selected page. The ''Namespace Root'' link, when clicked, displays the root namespace directory and all of its files and namespaces. Clicking the Up Arrow moves you up to the previous directory. {{ http://mturner.org/userfiles/doku/mouseover_zpsezbbiqgi.png?225 }} As a convenience, when the mouse moves over the UP arrow, a tooltip displays the name of the previous namespace. A tooltip also appears when the mouse goes over the ''Select ID'' input box; this is particularly convenient in the case of long names. ==== Table of Contents Listings ==== The title of the listing depends on where you are at. If it is a namespace listing, then the title is ''Index'', as in the above illustrations. If it is a table of contents for one of the pages, then it will be labeled ''Table of Contents''. {{ http://mturner.org/userfiles/doku/toc_zps4sxhodyh.png?225 }} The items in the ''Table of Contents'' are links to the headings in the currently selected page. ===== Styling ===== The height and width of the TOC/Index can be reset in ''tocselect/style.css''. The current settings are suited to the default dokuwiki template's sidebar. ===== Configuration ===== There is one configuration option: |''notoc''|Suppress Dokuwiki's in-page TOCs| default: false| When set to true, Dokuwiki's own TOCs are turned off. This configuration option is convenient if you are going to install the ''tocselect'' listings in the sidebar, preventing duplication. When the ''tocselect'' TOC is installed in a page, the Dokuwiki TOC is automatically suppressed. ===== Non-Roman Alphabets ===== There is a version which supports Dokuwiki's urlencoding for names containing non-Roman characters, either all or in part. It does not support Dokuwiki's Safe Filename encoding, though that is a TODO. Download and install either manually or using the Manual tab of the Extension Manager: *https://github.com/turnermm/tocselect/archive/encodings.zip ===== Changes ===== {{rss>https://github.com/turnermm/tocselect/commits/master.atom date count=12}} For a complete history of the Changes to the plugin, see: [[https://github.com/turnermm/tocselect/commits/master|github commits]]