DokuWiki

You've loaded an old revision of the document! If you save it, you will create a new version with this data.

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

---- plugin ----
description: List pages and namespaces recursively in nested lists
author     : Félix Faisant 
email      : xcodexif@xif.fr 
type       : Syntax
lastupdate : 2017-01-11
compatible : Angua, Adora Belle, Weatherwax, Binky, Ponder Stibbons, Hrun, Detritus, Elenor Of Tsort
depends    : 
conflicts  : 
similar    : nspages, dir, dirlisting, nstoc, pagequery, pagelist, pageindex, pglist
tags       : list create page namespace tree recurse links listing navigation
downloadurl: http://dev.xif.fr:7979/catlist/catlist-2017-01-11.zip
----

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

On the right, example sidebar using Bootstrap, visible [[http://www.tributieimposte.it/portaleiuc/|here]].

Example using columns:
{{http://dev.xif.fr:7979/catlist/screenshot_columns.png?nolink}}

===== Syntax =====

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

<code><catlist (namespace:) -option1 -option2...></code>
If namespace is not provided, the namespace of current page is used by default.\\
Relative (''.:ns'') and parent (''ns1:..:ns2'') namespaces can be used.

==== Options ====

^  Display options                       ^^
|  **[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. ACLs always prevails. **[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 ====

|  ''default_sort''      |  Default sort order. ''none'' (filesystem sorting, by **default**), ''ascending'', ''descending''  |
|  ''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''  |

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

==== Tips ====

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 :
<code>-excluPage:"mynamespace:[^:]*(?<!mypage1|mypage2)$"</code>

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

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

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.

Alternatively, install from these links
  * http://dev.xif.fr:7979/catlist/

===== Development =====

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

Git repo : [[http://satanas.net.xif.fr:1234/gitw/?p=catlist.git]] (rarely reachable)

=== Known Bugs and Issues ===

* Display bugs with ''-displayLine''

=== ToDo/Wish List ===

* 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
  * French
  * Chinese (Simplified)
  * Russian
  * Japanese
  * German
  * Spanish

===== Discussion =====

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

Please fill all the letters into the box to prove you're human. C Y S B U Please keep this field empty:

Edit summary

Note: By editing this page you agree to license your content under the following license: CC Attribution-Share Alike 4.0 International