This is an old revision of the document!
Table of Contents
catlist Plugin
Compatible with DokuWiki
"Frusterick Manners", Detritus, Elenor Of Tsort, Greebo
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
Syntax
Legend: [needed]
, (optional)
<catlist (namespace:) -option1 -option2...>
Here, namespace:
represents the full path to the namespace. The trailing colon is optional.
If namespace is not provided, the namespace of current page is used by default (equivalent to .:
).
Relative (.:ns
) and parent (ns1:..:ns2
) namespaces can be used.
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
exceptpage1
andpage2
(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
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 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] |
-noHeadTitle | Don't use the title (first heading) of pages as displayed name (overwrites 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). |
Exclude options (can be used multiple time) | |
-exclude:{page1 ns1: page2 …} | Exclude a list of pages/namespaces based on full 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 |
If ! is appended before the regex, the regex is negated. In other words, pages would be filtered based of regex, rather than excluded : only pages matching the regex would be included. Not implemented yet |
|
Note : don't add delimiters to regex, the delimiter is / |
|
[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 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 |
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, by ID) |
-sortDescending | Descending Sort |
Global options
These options can be found in the DokuWiki configuration manager.
default_sort | Default sort order. none (filesystem sorting, by default), ascending , descending |
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). |
show_acl | Ignore ACLs (show everything, regardless of the user) and show user permissions for each item. |
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
directive if Add page…
buttons are used, in order to force rescan of the namespace after creating a page.
Styles
You can stylize the columns of the -columns:
option by a small CSS code :
<html><style> .catlist_columns { -webkit-column-rule: 1px solid #BBB; -moz-column-rule: 1px solid #BBB; column-rule: 1px solid #BBB; } </style></html>
Here are the CSS classes you can use to modify the appearance :
catlist-head
: thestrong
orspan
of the headlinecatlist-nshead
: thestrong
orspan
of namespace headscatlist-nslist
:ul
of namespace sub-listscatlist-ns
:li
that warp namespace sub-listscatlist-page
:li
that warp page linkscatlist_addpage
:li
that warpAdd page…
buttons
Installation
Search and install the plugin using the 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 GitHub.
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 [at] gmail [dot] 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 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 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 [dot] castillo [at] innn [dot] es)
- Added
index_priority
andhide_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)
Known Issues and Wish List
Refer to the GitHub issue tracker.
Languages
- English
- French
- Chinese (Simplified)
- Russian
- Japanese
- German
- Spanish
Help is welcome !
Discussion
Please send me an e-mail at xcodexif [at] xif [dot] fr
Create a page option
If my person has seen right, if using it to create a page it would not consider namespace _template
but create an empty one. Is there a way to avoid it, if using this option? (Not having possibility to email, question raised here) — Samana Johann 2018-08-20 20:08
Is this a documented DokuWiki feature or is it something provided by a plugin ? If it's a DokuWiki feature, please open an issue on the GitHub page or send an email to ask to add this, I can't come here ofter to check your answer. — xif 2018-09-10 00:27
It's a documented (? probably) DokuWiki feature, Mr. Félix Faisant: namespace_templates “When a page is created, DokuWiki looks up whether a template file exists and it shows it within the editor window.” If using the add a page opinion, it would not consider possible template-use. (my person pardons the late replay, just came across, not using email and trying to avoid to enter places not invited by the owner may limit Mr. Félix's wish.) — Samana Johann 2018-10-15 15:25
Various incl. meta
Option list, for example-excluPage
: The syntax is not easy to see: “(”, “{”, since sometimes part of syntax, sometimes just an opinion. Trust it's of use and right gotten. — Samana Johann 2018-08-16 10:16