====== catlist Plugin ======

---- plugin ----
description: List pages and namespaces recursively in nested lists
author     : Félix Faisant 
email      : xcodexif@xif.fr 
type       : Syntax
lastupdate : 2023-12-16
compatible : Detritus, Elenor of Tsort, Frusterick Manners, Greebo, Hogfather, Igor, Jack Jackrum, Kaos+
depends    : 
conflicts  : 
similar    : nspages, dir, nspages, pagequery, pagelist, pglist
tags       : list create page namespace tree recurse links listing navigation
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/

----

===== Description =====

This plugin lists pages and namespaces recursively as a multilevelled list. You can exclude pages, namespaces and their elements with regex. There are multiple options to personalize headlines and links. Elements can be sorted and put in columns. New pages can be quickly created in a given namespace with ''Add page%%...%%'' buttons.

===== Screenshots =====

Example page [[http://wiki.xif.fr|here]].

{{http://dev.xif.fr:7979/catlist/screenshot_test_cols.png?nolink}}


===== Syntax =====

<code><catlist namespace: -option1 -option2...></code>
Here, ''namespace:'' represents the **full** path to the namespace. The trailing colon is optional.\\
The namespace itself is optional. If not provided, the namespace of current page is used by default (equivalent to ''.:'').\\
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 ====

Legend: ''[needed]'', ''(optional)''

^  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 ====

These options can be found in the DokuWiki configuration manager.

|  ''useheading''  |  Default use of page title vs page ID for item display. **Enabled** by default.  |
|  ''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.  |

To illustrate ''index_priority'' : if DokuWiki internal link would use ''index_priority'', the default value would be ''start,inside,outside''.

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.

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 :
<code><html><style>
	.catlist_columns {
		-webkit-column-rule: 1px solid #BBB;
		   -moz-column-rule: 1px solid #BBB;
		        column-rule: 1px solid #BBB;
	}
</style></html></code>

Here are the CSS classes you can use to modify the appearance :
  * ''catlist-head'' : the ''strong'' or ''span'' of the headline
  * ''catlist-nshead'' : the ''strong'' or ''span'' of namespace heads
  * ''catlist-nslist'' : ''ul'' of namespace sub-lists
  * ''catlist-ns'' : ''li'' that warp namespace sub-lists
  * ''catlist-page'' : ''li'' that warp page links
  * ''catlist_addpage'' : ''li'' that warp ''Add page…'' buttons

===== Installation =====

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/]].

===== Development =====

Source code is available on [[https://github.com/xif-fr/dokuwiki-plugin-catlist/|GitHub]].

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**
    * Initial release
  * **2012-09-02**
    * Resolved bug with multi-leveled namespace in generated links
  * **2012-09-15**
    * Added support for configuration option 'hidepages'
  * **2012-11-27**
    * Added support for configuration options 'userewrite', 'useslash' and 'sepchar' in the "Add page..." button
  * **2012-11-30**
    * Resolved a bug with empty 'hidepages' configuration option
  * **2013-01-28**
    * ''-noLinkStartHead'' now works
    * When URL rewriting is not enabled, the add button don't redirect to the base URL, but use a relative one
  * **2013-06-02** : Qing Xianhao <qingxianhao@gmail.com>
    * Fix a Add new page prefix problem
    * Add Simplified chinese translation
    * Add Enter key open edit page.
  * **2013-09-30** :
    * Don't list files that don't end with ''.txt''
    * Added ''-maxDepth'' option
  * **2014-10-04** :
    * Sort options
    * Added russian (from [[https://github.com/rmuratov|rmuratov]]) and japanese translation
  * **2014-11-29** :
    * Typo bug affecting the sort function (thanks to aweall)
  * **2015-07-03** :
    * Columns displaying
  * **2015-07-08** :
    * Corrected fatal PHP syntax error
  * **2015-10-09** :
    * Sort function doesn't make the plugin to crash any more on PHP < 5.4.0 (thanks to Frank Thommen and MJD for the report)
  * **2016-04-17** :
    * Support for encoded file names. Thanks to Guillaume Lecêtre and Chifeng Li.
    * Added ''-noNSHeadTitle''
  * **2016-04-20**
    * Added german translation (from [[https://github.com/georgmastritsch|georgmastritsch]])
  * **2016-06-27**
    * Added ''-nsLinks'' option and deprecated ''-forceLinks''.
    * Added CSS classes to various elements of rendered html.
  * **2017-01-11**
    * Added spanish translation (from Juan Manuel Castillo <juanmanuel.castillo@innn.es>)
    * Added ''index_priority'' and ''hide_index'' global options
    * 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 Issues and Wish List ====

Refer to the [[https://github.com/xif-fr/dokuwiki-plugin-catlist/issues|GitHub issue tracker]].

==== Languages ====

  * English
  * Chinese (Simplified)
  * French
  * German
  * Italian
  * Japanese
  * Russian
  * Spanish


[[https://translate.dokuwiki.org/plugin/catlist|Help is welcome!]]

===== Discussion =====

**Please send me an e-mail at [[xcodexif@xif.fr]]**