DokuWiki

It's better when it's simple

User Tools

Site Tools

Trace:
plugin:catlist

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
plugin:catlist [2016-10-23 16:50] – 91.69.202.160plugin:catlist [2024-03-07 19:31] (current) – Tested OK with Jack + Kaos dregad
Line 6: Line 6:
 email      : xcodexif@xif.fr  email      : xcodexif@xif.fr 
 type       : Syntax type       : Syntax
-lastupdate : 2016-06-27 +lastupdate : 2023-12-16 
-compatible : Angua, Adora Belle, Weatherwax, Binky, Ponder Stibbons, Hrun, Detritus, Elenor Of Tsort+compatible : Detritus, Elenor of Tsort, Frusterick Manners, Greebo, Hogfather, Igor, Jack Jackrum, Kaos+
 depends    :  depends    : 
 conflicts  :  conflicts  : 
-similar    : nspages, dir, dirlisting, nstoc, pagequery, pagelist, pageindex, pglist+similar    : nspages, dir, nspages, pagequery, pagelist, pglist
 tags       : list create page namespace tree recurse links listing navigation tags       : list create page namespace tree recurse links listing navigation
-downloadurl: http://dev.xif.fr:7979/catlist/catlist-2016-06-27.zip+downloadurl: https://github.com/xif-fr/dokuwiki-plugin-catlist/zipball/master 
 +bugtracker : https://github.com/xif-fr/dokuwiki-plugin-catlist/issues 
 +sourcerepo : https://github.com/xif-fr/dokuwiki-plugin-catlist/ 
 ---- ----
  
Line 21: Line 24:
 ===== Screenshots ===== ===== Screenshots =====
  
-On the right, example sidebar using Bootstrap, visible [[http://www.tributieimposte.it/portaleiuc/|here]].+Example page [[http://wiki.xif.fr|here]].
  
-{{http://dev.xif.fr:7979/catlist/screenshot_both.png?nolink}}+{{http://dev.xif.fr:7979/catlist/screenshot_test_cols.png?nolink}}
  
-Example using columns: 
-{{http://dev.xif.fr:7979/catlist/screenshot_columns.png?nolink}} 
  
 ===== Syntax ===== ===== Syntax =====
  
-Legend: ''[needed]'', ''(optional)'' +<code><catlist namespace: -option1 -option2...></code> 
- +Here, ''namespace:'' represents the **full** path to the namespace. The trailing colon is optional.\\ 
-<code><catlist (namespace:) -option1 -option2...></code> +The namespace itself is optional. If not provided, the namespace of current page is used by default (equivalent to ''.:'').\\
-If namespace is not provided, the namespace of current page is used by default.\\+
 Relative (''.:ns'') and parent (''ns1:..:ns2'') namespaces can be used. Relative (''.:ns'') and parent (''ns1:..:ns2'') namespaces can be used.
 +
 +==== More specific syntax ====
 +
 +Note that ''.'' refers to the page where the ''<catlist>'' tag is. **For use in a sidebar**, where the //displayed// page is what you want as the base namespace, use the syntax <code><catlist %%CURRENT_NAMESPACE%%></code>
 +
 +Here are some examples about exclusion :
 +  * List only namespaces relative to current namespace :\\ ''<catlist -exclupage>''
 +  * List everything except ''dirty_page'' relative to current namespace :\\ ''%%<catlist -excludeOnName -exclupage:"^dirty_page$">%%''\\ (to be strict) but most of the time,\\ ''%%<catlist -exclupage:"dirty_page">%%''\\ will be ok
 +  * List everything in ''.:foo_namespace:'', except pages whose name begins with a number :\\ ''<catlist .:foo_namespace -excluPage:"^foo_namespace:[0-9]">''\\ or equivalently\\ ''%%<catlist .:foo_namespace -excludeOnName -excluPage:"^[0-9]">%%''
 +  * Exclude all page in ''mynamespace'' except ''page1'' and ''page2'' (without excluding these pages in sub-namespaces) :\\ ''%%<catlist mynamespace: -excluPage:"mynamespace:[^:]*(?<!mypage1|mypage2)$">%%''\\ or, much more simply :\\ ''<catlist mynamespace: -excluPage:{mynamespace:mypage1 mynamespace:mypage2}>''
  
 ==== Options ==== ==== Options ====
  
-^  Display options                       ^^ +Legend: ''[needed]'', ''(optional)''
-|  **[Default]**  ''-displayList''   |  Display with ''<ul>'' and ''<li>''. Render is like on the first screenshots above.  | +
-|  ''-displayLine''                  |  Display pages and namespaces into a single line. The content of namespaces are warped with ''['' and '']''. **Warning** there is some display bugs with it.  | +
-|  ''-noNSInBold''                   |  Don't display namespaces and head in bold (with ''<strong>'')  | +
-|  ''-columns:[0-∞]''                |  Split the list into a certain number of columns. Uses the modern CSS features ''column-count''. **[Default 0]**  | +
-^  Exclude options                       ^^ +
-|  ''-exclude:{page1 ns1: page2 …}''  |  Exclude a list of pages/namespaces based on exact ids relative to the listed namespace ('':'' cannot be ignored on namespaces id). //Not implemented yet//. | +
-|  ''-exclupage(:"//regex//")''      |  Exclude pages that match with //regex// if provided; otherwise exclude all pages  | +
-|  ''-excluns(:"//regex//")''        |  Exclude namespaces that match with //regex// if provided; otherwise exclude all namespaces  | +
-|  ''-exclunsall(:"//regex//")''     |  Exclude all content of subnamespaces that match with //regex// if provided; otherwise don't show content of subnamespaces  | +
-|  ''-exclunspages(:"//regex//")''   |  Exclude pages of subnamespaces that match with //regex// if provided; otherwise exclude all pages of subnamespaces  | +
-|  ''-exclunsns(:"//regex//")''      |  Exclude subnamespaces of subnamespaces that match with //regex// if provided; otherwise exclude all subnamespaces of subnamespaces  | +
-|  **Note :** don't add delimiters to //regex//, the delimiter is ''/''  || +
-|  **[Default]** ''-excludeOnID''    |  Exclusion based on page IDs (''namespace:subnamespace:page'')  | +
-|  ''-excludeOnName''                |  Exclusion based on name, without namespaces (''page'')  | +
-|  ''-excludeOnTitle''               |  Exclusion based on the first title of the page (''The Page'')  | +
-|  ''-maxDepth://depth//''           |  Don't recurse deeper than //depth//  | +
-^  Headline                          ^^ +
-|  ''-noHead''                       |  Don't display headline  | +
-|  ''-smallHead''                    |  Display headline into a simple ''<span>'', not into a title  | +
-|  ''-noLinkStartHead''              |  Don't add link to the start page of listed namespace  | +
-|  ''-h[1-5]''                       |  Display headline into a title of the specified level **[Default -h1]**  | +
-|  ''-titleHead:"//Title//"''        |  Replace startpage title of listed namespace by specified //Title//  | +
-^  Namespace heads                         ^^ +
-|  ''-noNSHeadTitle''                |  Don't use the title of start pages for namespace heads. Imply ''-nsLinks:none''.  |  +
-|  ''-nsLinks:none|**auto**|force''  |  Namespace links : disable, automatically detect the start page, or force links even if the start page doesn't exist **[Default auto]**  | +
-^  Create page buttons options (takes into account user rights)           ^^ +
-|  ''-noAddPageButton''              |  Don't display ''Add page...'' button for listed namespace  | +
-|  ''-addPageButtonEach''            |  Display ''Add page...'' button for each namespace  | +
-|  ''-addPageButtonSubs''            |  Display ''Add page...'' button for each subnamespace (excluding the listed namespace)  | +
-^  Sort options                         ^^ +
-|  ''-sortAscending''                |  Ascending Sort (alphabetically)   | +
-|  ''-sortDescending''               |  Descending Sort (alphabetically)  |+
  
 +^  Display options                    ^^
 +|  **[Default]**  ''-displayList''    |  Display with ''<ul>'' and ''<li>''. Render is like on the first screenshot above.  |
 +|  ''-displayLine''                   |  Display pages and namespaces into a single line. The content of namespaces are warped with ''['' and '']''. **Warning** there are some display bugs in it.  |
 +|  ''-noNSInBold''                    |  Don't display namespaces and head in bold (with ''<strong>'')  |
 +|  ''-columns:[0-∞]''                 |  Split the list into a certain number of columns. Uses the modern CSS features ''column-count''. **[Default 0]**  | 
 +|  ''-noHeadTitle''                   |  Don't use the title (first heading) of pages as displayed name (overwrites global option ''useheading'').  |
 +|  ''-forceHeadTitle''                |  Force the use of the page title as displayed name (overwrites ''useheading'').  |
 +|  ''-noNSHeadTitle''                 |  Don't use the title of the start pages as namespace displayed name (overwrites the above options).  |
 +|  ''-hideNotFoundMsg''               |  Don't show an error message when the namespace is not found  |
 +^  Exclude options (can be used multiple time and combined)                       ^^
 +|  ''-exclude:{//page1 ns1(:) ns2:page2 …//}''  |  Exclude a list of pages/namespaces based on **full IDs relative** to the listed namespace. For namespaces, the optional trailing '':'' indicates that the content is excluded, but the namespace itself is shown (same behavior as ''exclunsall'' below).  |
 +|  ''-exclupage((!):%%"%%//regex//%%"%%)''       |  Exclude pages that match with //regex// if provided; otherwise exclude all pages.  |
 +|  ''-excluns((!):%%"%%//regex//%%"%%)''         |  Exclude namespaces that match with //regex// if provided; otherwise exclude all namespaces  |
 +|  ''-exclunsall((!):%%"%%//regex//%%"%%)''      |  Exclude all content of subnamespaces that match with //regex// if provided; otherwise don't show content of subnamespaces  |
 +|  ''-exclunspages((!):%%"%%//regex//%%"%%)''    |  Exclude pages of subnamespaces that match with //regex// if provided; otherwise exclude all pages of subnamespaces  |
 +|  ''-exclunsns((!):%%"%%//regex//%%"%%)''       |  Exclude subnamespaces of subnamespaces that match with //regex// if provided; otherwise exclude all subnamespaces of subnamespaces  |
 +|  If ''!'' is appended before the regex, the regex is **negated**. In other words, pages would be **filtered/whitelisted** based on //regex// : only pages matching the regex would be included. When multiple exclusion options are used, they combine in a //logical-or// way : one match is enough to exclude.  ||
 +|  **Note :** don't add delimiters to //regex//. The delimiter is implicitly ''/''.  ||
 +|  **[Default]** ''-excludeOnID''     |  Exclusion based on **full** page IDs (''namespace:subnamespace:page'')  |
 +|  ''-excludeOnName''                 |  Exclusion based on name, without namespaces (''page'')  |
 +|  ''-excludeOnTitle''                |  Exclusion based on the first title of the page (''The Page'')  |
 +|  ''-maxDepth://depth//''            |  Don't recurse deeper than //depth//  |
 +^  Headline                           ^^
 +|  ''-noHead''                        |  Don't display headline  |
 +|  ''-smallHead''                     |  Display headline as a simple ''<span>'', not as a title ''<h_>''  |
 +|  ''-noLinkStartHead''               |  Don't add link to the start page of listed namespace  |
 +|  ''-h[1-5]''                        |  Display headline as a title of the specified level **[Default -h1]**  |
 +|  ''-titleHead:%%"%%//Title//%%"%%''         |  Replace startpage title of listed namespace by specified //Title//  |
 +^  Namespaces                         ^^
 +|  ''-nsLinks:''\\ ''none|**auto**|force''  |  Namespace links : disable, automatically detect the start page, or force links even if the start page doesn't exist. ACLs always prevail. **[Default auto]**  |
 +^  Create page buttons options (takes into account user rights)           ^^
 +|  ''-noAddPageButton''               |  Don't display ''Add page...'' button for listed namespace  |
 +|  ''-addPageButtonEach''             |  Display ''Add page...'' button for each namespace  |
 +|  Default : shows an ''Add page...'' button only for listed namespace. If you want ''Add page...'' buttons only for subnamespaces, use both options.  ||
 +^  Sort options                       ^^
 +|  ''-sortAscending''                 |  Ascending sort (alphabetically : 1→9→A→Z→a→z)   |
 +|  ''-sortDescending''                |  Descending sort  |
 +|  ''-sortByTitle''                   |  Use page title (not page ID, which is the **default**) for sorting  |
 +|  ''-sortByModifDate''               |  Sort by (non-minor) modification date rather than by name  |
 +|  ''-sortByCreationDate''            |  Sort by creation date rather than by name  |
 +|  ''-sortByType''                    |  Additionally, put all namespaces at the beginning  |
 +|  **Note :** there is no sorting by default, ''-sortAscending'', ''-sortDescending'' or ''default_sort'' **must be set** before using ''-sortByTitle'', ''-sortByType'' or ''-sortByWhateverDate''  ||
 +^  ACL options                       ^^
 +|  ''-ACLshowPage''                   |  Force showing pages for which the user doesn't have read permission (entry would be shown, but without link). Not necessary to enable ''show_leading_ns'', but ''-ACLhideNs'' prevails.  |
 +|  ''-ACLhideNs''                     |  Force hiding namespaces for which the user doesn't have read permission (entry is shown by default, but without link). ''show_leading_ns'' prevails.  |
 ==== Global options ==== ==== Global options ====
  
-|  ''default_sort''                |  Default sort order. ''none'' (filesystem sorting, by **default**), ''ascending'', ''descending''    | +These options can be found in the DokuWiki configuration manager.
-|  ''startpages_outside''          |  Use pages like ''foo:bar'' as start pages for the ''foo:bar:'' namespace\\ if ''foo:bar:<start>'' does not exist. **Disabled** by default.  |+
  
-Example for ''startpages_outside'' option : {{http://dev.xif.fr:7979/catlist/startpages_outside-disabled.png?nolink}} ⇒ {{http://dev.xif.fr:7979/catlist/startpages_outside-enabled.png?nolink}} \\  +|  ''useheading''  |  Default use of page title vs page ID for item display. **Enabled** by default.  | 
-(if ''rootpage:<start>'' and ''rootpage:level1:<start>'' don't exist)+|  ''default_sort''      |  Default sort order. ''none'' (filesystem order, by **default**), ''ascending'', ''descending''  | 
 +|  ''sort_collator_locale''  |  Locale used to sort page names. When not empty, [[https://www.php.net/manual/en/class.collator.php|PHP Collator class]] is used; should be a valid locale short code, for example ''fr_FR''. When empty, plain alphanumeric sorting is used (default behavior).  | 
 +|  ''nocache''           |  Disable the cache on pages where catlist is used  | 
 +|  ''hide_index''        |  Don't show index pages, namely pages which are used as main page (title and link) for a namespace in catlist. **Enabled** by default.  | 
 +|  ''index_priority''    |  Priority order of pages used as index pages. Combination of ''start'', ''inside'' and ''outside''. **[Default ''start,outside'']**\\ Example with the namespace ''foo:bar:'':\\ ''start'' ≡ ''foo:bar:<start>''\\ ''outside'' ≡ ''foo:bar''\\ ''inside'' ≡ ''foo:bar:bar''  |  
 +|  ''hide_acl_nsnotr''  |  Hide namespaces for which the user doesn't have ACL Read permission. **Disabled** by default (entry is shown, but no link). Global version of ''-ACLhideNs''. ''show_leading_ns'' prevails.  | 
 +|  ''show_acl''  |  Ignore ACLs (show everything, regardless of the user) and show user permissions for each item. Intended for fixing permission issues.  | 
 +|  ''show_leading_ns''  |  Show leading namespaces to a page for which a user has ACL read permissions regardless of user ACLs on namespace. **Disabled** by default.  | 
 +|  ''nswildcards''  |  Replace wildcards such as ''@USER@'' in the namespace string, as for page templates, using the ''parsePageTemplate'' function. For details, refer to [[:namespace_templates#replacement_patterns]]. (:!: Use at your own risk, could be used by malicious users to leak data).  | 
 +|  ''pagename_sanitize''  |  Sanitize the page name of pages created by the ''Add page…'' button. When this is enabled, the feature respects the [[config:deaccent|deaccent]], [[config:userewrite|userewrite]], [[config:useslash|useslash]] and [[config:sepchar|sepchar]] configuration options. **Enabled** by default.  |
  
-==== Tips ====+To illustrate ''index_priority'' : if DokuWiki internal link would use ''index_priority'', the default value would be ''start,inside,outside''.
  
-You want to exclude all page in listed namespace (''mynamespace'') except ''mypage1'' and ''mypage2'' but you don't want to exclude pages in subnamespaces. It's a little bit hard in regex... I will simplify things like this  but in the meantime, here is the solution : +It is recommended to use the ''nocache'' global option or to add the ''NOCACHE'' [[:caching|directive]] if ''Add page…'' buttons are used, in order to force rescan of the namespace after creating a page. 
-<code>-excluPage:"mynamespace:[^:]*(?<!mypage1|mypage2)$"</code>+ 
 +Decision made when showing a namespace base on permissions and options : 
 +{{http://dev.xif.fr:7979/catlist/catlist-ns-perms.png?300}} 
 + 
 +==== Styles ====
  
 You can stylize the columns of the ''-columns:'' option by a small CSS code : You can stylize the columns of the ''-columns:'' option by a small CSS code :
Line 101: Line 136:
   * ''catlist-page'' : ''li'' that warp page links   * ''catlist-page'' : ''li'' that warp page links
   * ''catlist_addpage'' : ''li'' that warp ''Add page…'' buttons   * ''catlist_addpage'' : ''li'' that warp ''Add page…'' buttons
- 
-It is recommended to add the ''NOCACHE'' [[:caching|directive]] if ''Add page…'' buttons are used to force rescan of the namespace after adding a page. 
  
 ===== Installation ===== ===== Installation =====
  
-Install the plugin using the [[plugin:plugin|Plugin Manager]] and the download URL above, which points to latest version of the plugin. Refer to [[:Plugins]] on how to install plugins manually.+Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually. Alternatively, install from [[http://dev.xif.fr:7979/catlist/]].
  
-Alternatively, install from these links +===== Development =====
-  * http://dev.xif.fr:7979/catlist/+
  
-===== Development =====+Source code is available on [[https://github.com/xif-fr/dokuwiki-plugin-catlist/|GitHub]].
  
-=== Change Log ===+While this plugin is somewhat maintained, the author does not have much time to dedicate to it and does not use docuwiki presently. I would be happy to transfer the ownership to an actual user. 
 +==== Change Log ====
  
   * **2012-07-31**   * **2012-07-31**
Line 120: Line 153:
     * Resolved bug with multi-leveled namespace in generated links     * Resolved bug with multi-leveled namespace in generated links
   * **2012-09-15**   * **2012-09-15**
-    * Added support for onfiguration option 'hidepages'+    * Added support for configuration option 'hidepages'
   * **2012-11-27**   * **2012-11-27**
     * Added support for configuration options 'userewrite', 'useslash' and 'sepchar' in the "Add page..." button     * Added support for configuration options 'userewrite', 'useslash' and 'sepchar' in the "Add page..." button
Line 154: Line 187:
     * Added ''-nsLinks'' option and deprecated ''-forceLinks''.     * Added ''-nsLinks'' option and deprecated ''-forceLinks''.
     * Added CSS classes to various elements of rendered html.     * Added CSS classes to various elements of rendered html.
-  * **2016-10-13**+  * **2017-01-11**
     * Added spanish translation (from Juan Manuel Castillo <juanmanuel.castillo@innn.es>)     * Added spanish translation (from Juan Manuel Castillo <juanmanuel.castillo@innn.es>)
-    * Added ''startpages_outside'' global option +    * Added ''index_priority'' and ''hide_index'' global options 
-    * Added ''-addPageButtonSubs''+    * Fixed a bug (duplication of index pages with ''<catlist :>'') 
 +    * Code refactoring 
 +  * **2017-09-28** 
 +    * Bugfix with ''maxDepth'' 
 +    * ''nocache'' option added 
 +    * move ACL checks at display stage 
 +  * **2018-01-18** 
 +    * Changed license to MIT, except for some language files 
 +    * Added ''hide_acl_nsnotr'' option 
 +  * **2018-07-03** 
 +    * ACL bugfix (on private wikis, pages in namespaces didn't show up) 
 +    * Added ''show_acl'' option 
 +    * fixed add page button for ''userewrite=2'' 
 +    * better handling of page name for add page button 
 +  * **2018-07-22** 
 +    * fixed syntax error in lang/fr/settings introduced by 2018-07-03 
 +  * **2018-10-04** 
 +    * support all cases of ''fnencode'' (thanks to @shioyadan) 
 +    * fixed add-page-button for the case ''userewrite=2'' 
 +    * added options ''useheading''/''noHeadTitle''/''forceHeadTitle'' 
 +    * removed ''noNSHeadTitle'' => ''nsLinks=none'' 
 +  * **2019-03-28** 
 +    * added italian language 
 +    * bugfix (thanks to @bradbulger) 
 +    * added ''show_leading_ns'' option (thanks to @kevans91) 
 +  * **2019-05-19** 
 +    * added ''showhead'' global option (thanks to @FosseWay) 
 +    * added ''nswildcards'' global option 
 +  * **2019-07-18** 
 +    * added ''hideNotFoundMsg'' option 
 +    * disable character substitutions when ''[[:config:deaccent]]'' is enabled when using the ''Add page…'' button; romanization still not supported (thanks to @shioyadan & @hrko99) 
 +  * **2019-07-31** 
 +    * rewritten sorting, added sorting by title and by type 
 +  * **2019-09-13** 
 +    * fixed and improved sorting with ''strnatcasecmp'' (thanks @susnux and @hurzilein) 
 +    * fixed 'savedir' (thanks @fabienli) 
 +  * **2019-10-29** 
 +    * added ''-ACLhideNs'' and ''-ACLshowPage'' options 
 +    * fixed behavior when both show_pgnoread and show_leading_ns are enabled 
 +    * fixed "namespace not found" issue on Windows platform 
 +  * **2021-02-04** 
 +    * added the "dynamic" namespace option (thanks to @fabienli and @fwolfst) 
 +  * **2021-07-21** 
 +    * implemented ''-exclude:{}'' option 
 +    * implemented negation of regex exclusion options 
 +  * **2022-06-25** 
 +    * added ''pagename_sanitize'' option 
 +    * added sorting by date 
 +  * **2022-08-07** 
 +    * added Collator sorting 
 +    * bug fixing 
 +  * **2023-12-16** 
 +    * fix bug with the add page button in side bar
  
-=== Known Bugs and Issues ===+==== Known Issues and Wish List ====
  
-  * Display bugs with ''-displayLine''+Refer to the [[https://github.com/xif-fr/dokuwiki-plugin-catlist/issues|GitHub issue tracker]].
  
-=== ToDo/Wish List === +==== Languages ====
- +
-  * Clean ID when creating page (in JS) (is there a function for cleaning IDs in dokuwiki's scripts ?). Curently, I only replace spaces by ''_'' and check if pagename is not empty... +
-  * Sorting by title, not by file name +
-  * Alphanumeric index +
- +
-=== Languages ===+
  
   * English   * English
 +  * Chinese (Simplified)
   * French   * French
-  * Chinese (Simplified)+  * German 
 +  * Italian 
 +  * Japanese
   * Russian   * Russian
-  * Japanese +  * Spanish 
-  * German + 
-  * Spanish + 
 +[[https://translate.dokuwiki.org/plugin/catlist|Help is welcome!]]
  
 ===== Discussion ===== ===== Discussion =====
  
 **Please send me an e-mail at [[xcodexif@xif.fr]]** **Please send me an e-mail at [[xcodexif@xif.fr]]**
----- 
plugin/catlist.1477234255.txt.gz · Last modified: 2016-10-23 16:50 by 91.69.202.160
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki

Global DokuWiki Links