DokuWiki

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

====== Dir Plugin ======

---- plugin ----
description: Show content of current namespace, including sub namespaces and/or parent/sibling namespaces, in a table or list
author     : Jacobus Geluk
email      : Jacobus.Geluk@gmail.com
type       : syntax
lastupdate : 2014-07-15
compatible : Detritus, Ponder Stibbons, binky, angua, rincewind, adora belle, weatherwax
depends    : pagelist
conflicts  : 
similar    : nspages, catlist, dirlisting, nstoc, pagequery, pagelist, pageindex, pglist
tags       : namespace, page

downloadurl: https://github.com/lupo49/dokuwiki-plugin-dir/tarball/master
sourcerepo: https://github.com/lupo49/dokuwiki-plugin-dir
bugtracker: https://github.com/lupo49/dokuwiki-plugin-dir/issues
----

===== Fork =====

The original seems to get no updates and the maintainers do not merge PRs and do not respond. So I created a fork for my own needs some time ago.

[[https://gitlab.com/dokuwiki-plugins/dir]]

Tested on Debian Bookworm with DW 2023-04-04a "Jack Jackrum".

* 2023-07-24: fixes for PHP 8.2 (''Unknown Array keys'').

===== Download & Installation =====

Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.

* 8-O For usage with **Hrun** or later, consider https://gitlab.com/dokuwiki-plugins/dir, download file [[https://gitlab.com/dokuwiki-plugins/dir/-/archive/option-collapse_sub/dokuwiki-plugin-dir-option-collapse_sub.zip|.zip]] (you may update lupo49's "official" one with that)
    * Sorry, but this doesn't work either --- [[user>mcgumbel|mcgumbel]] //2015-03-05 19:03//
    * runout-at's works very well on my sites with Hrun (Release 2014-09-29b as well as 2014-09-29c) - you should provide some more info on "doesn't work" - does nothing or does ugly things? note that you can add screenshots in [[https://gitlab.com/dokuwiki-plugins/dir/-/issues|an Issue report on runout-at's repo]] (don't hesitate to get a GitHub/GitLab account, you'll have more profit but less fuzz than with Facebook - and please don't think you have to be a hackathon's winner to utter something on GitHub!) --- [[user>hh lohmann|hh lohmann]] //2015-03-11 18:35//

===== Description =====

The Dir plugin searches a specified directory / namespace and lists the found pages in a tabular form, like the [[:plugin:pagelist]] plugin. The main difference with the [[:plugin:pagelist]] plugin is that the pages to be listed do not have to be specified manually. It resembles the "archive>" tag in the [[:plugin:blog]] plugin, but has some different options.

The produced table is a hierarchical tree. Each namespace is listed as a link to its start page. All other pages in that namespace are grouped below this start link. Sub namespaces appear below their parent namespaces and so on.

The produced table of pages can be sorted. Pages with certain tags can be selected or skipped (this only works if the [[:plugin:tag]] plugin is installed). The current page is skipped by default, but can be added to the list if needed. Non-start pages outside the current namespace can be skipped.

If the [[plugin:discussion]] plugin is installed, the number of comments of a page can be shown in a column.
If the [[plugin:tags]] plugin is installed, the tags of a page can be shown in a column.

The [[plugin:dir]] plugin has rudimentary support for the [[plugin:DokuTeXit]] plugin in the sense that it generates LaTeX output for that plugin.

===== Syntax =====

Shows
  ~~DIR:<namespace>?<flags>~~

^  **<namespace>**     ^Can be a list, separated with semicolons, of:  ^
|  **.**               |The current namespace  |
|  **..**              |The parent namespace   |
|  **subnamespace**    |The name of a sub namespace. Same as .:subnamespace  |
|  **..:sibling**      |The name of a sibling namespace  |
|  **::**              |The root namespace |
^  **<flags>**         ^Can be any of the following, in any order:  ^
|  **cols**            |A semicolon separated list of column names, see "Supported Column Names" below. |
|  **hdrs**            |A semicolon separated list of column header names.  |
|  **skip**            |A semicolon separated list of namespaces or page names that should be skipped.\\ Namespaces must end with a colon.  |
|  **tag**             |A semicolon separated list of tags that each page should have.\\ Pages that do not have all these tags are skipped.\\ A tag with a ! put in front of it means that a page with such a tag is skipped. |
|  **sort**            |A semicolon separated list of column names to be sorted, see "Supported Column Names" below.\\ Append **-ascending** (default) or **-descending** to each column name to get the desired effect. **-a** and **-d** work too.  |
|  **ego**             |Includes the current page in the result list (at least if it is part of the selected namespaces).  |
|  **widedesc**        |Shows the description of each page in an additional full width row.  |
|  **noheader**        |Do not show a header.  |
|  **table**           |Use the table style (styling of the [[:plugin:pagelist]] plugin is used)  |
|  **list**            |Use the list style (styling of the [[:plugin:pagelist]] plugin is used)  |
|  **nodefaulttitle**  |When this flag (or **ndt**) is present, the titles shown in the page column will not be the default titles but the page name itself.  |
|  **collapse**        |Limits the set of pages that is displayed to all siblings of the current page, all start pages of child namespaces (but not grandchild namespaces), all start pages of each parent namespaces and their sibling namespaces. This can be used to create a dynamic index. See [[plugin:dir:discussion#ego_and_collapse_background|Ego and collapse background]] for more information about this.  |
|  **namespacename**   |Instead using "start" as namespacename the name of the namespace will be displayed.|
|  **last**   | Do not display all pages but only the top X (e.g. last=5) |

| If you have one or more namespaces __and__ some flags, do not forget to put the question mark between them! |

==== Examples ====

If you put in a line like this, you will simply get a listing of all pages in the current namespace and below:
  ~~DIR~~

The same, but this time with the current page added to the listing:
  ~~DIR?ego~~

You can also add some columns, by starting with a question mark, the specification of the namespace is skipped. The current namespace will be used:
  ~~DIR?cols=page;user~~

You can add your own **column headers**:
  ~~DIR?cols=page;user;comments&hdrs=Whatever;User;# Comments~~

To display a wide description of the page, below each page row, you can use the **&widedesc** option:
  ~~DIR?cols=page;user;comments&hdrs=Whatever;User;# Comments&widedesc~~

To skip a sub namespace named archive:
  ~~DIR?skip=archive~~

To select only pages that have the tag "important":
  ~~DIR?tag=important~~

To skip pages that have the tag "concept": //(This currently only works when you also show the "tags" column, as in  ~~DIR?cols=page;tags&tag=!concept~~) -- jg//
  ~~DIR?tag=!concept~~

To select pages that have the tag book and the tag ebook and not the tag fiction:
  ~~DIR?tag=book;ebook;!fiction~~

To sort the pages by userid with a descending creation date:
  ~~DIR?cols=page;user&sort=userid;cdate-d~~

To show the pages in a sub namespace called "x":
  ~~DIR:.:x:~~

To show the pages in a sibling namespace:
  ~~DIR:..:y:~~

To show the pages in a sibling namespace with two columns, page title and user id:
  ~~DIR:..:y:?cols=page;user&hdrs=Page Title;User ID~~
  
In a sidebar, you could create a dynamic index, with only the parent namespaces, their sibling namespaces, the pages in the current namespace and its child namespaces:
  ~~DIR::?noheader&list&ego&collapse~~

===== Development =====

**If you have patches please send it via e-mail or github pull request.**

=== Changelog ===

{{rss>https://github.com/lupo49/dokuwiki-plugin-dir/commits/master.atom date}}

===== FAQ =====

=== Date Issues ===

> Thanks for the work, the plugin works basically fine. Only the dates are always set at '01.01.1970' (following my date format string 'd.m.Y'). Any hints? --- //breg, 31.10.2007 17:28//

>>The dates are taken from each page with the p_get_metadata function, which is a function of the DokuWiki itself. So the dir plugin does not produce these dates itself. --- // jg //

=== Syntax for listing subcategory ===

> Nice work, but what's the syntax for listing a subcategory?
> For example what should I write to list all the subpages of A:B:* ?

~~DIR:A:B~~

That would have to be: --- // jg //

~~DIR:.:A:B~~
  
=== Sort by title ===

> Thanks for the plugin! I am trying to get pages sorted by title (first header, not file name) but I don't see a way to do that.  
> Am I missing it?  sort=page gives me filename order. Here is how I invoke it:

>>  ~~DIR?sort=page-a&hdrs=additional topics~~

=== Namespace column ===

> I really like this plugin, there is only one thing I'm missing: when I list all the pages in all the namespaces, the "start" links start a namespace, and below that I can find the list of pages in that namespace. However, the name of the namespace is not included, so I cannot know, which namespace those pages are in, only if I point my mouse over the links. So there should be a column called "namespace", or an option, that includes the namespace name in the link name (like "playground:start"). --- //Totesz, 27.02.2011 11:15//

>> Like this? [[http://www.ummae.com/programming/programming]]FIXME. I have added displaying namespace feature myself. I dont know it's ok to share my edit version of this plugin, but if ok, I will share my edited version.

>> You should use the //namespacename// flag.

===== Discussion =====

Please refer to the external [[plugin:dir:discussion|Discussion]] site.
Especially to fix a problem with Hrun ... copied into here now 'cause it cost me a while to find out ...
 Since update to 2014-09-29 “Hrun”

[BUGFIX] Do not access protected renderer property The Renderer counter is not resetted if render mode is not latex. This prevents a PHP error when the protected _counter property is accessed.

This issue is fixed with pull request #20 with commit 3589642

But the pull request has not yet been accepted by the current project maintainer.

You can manually install the commit from this link

With this remediation I gave the compatibility for Hrun ...

Please fill all the letters into the box to prove you're human. R L T U N 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