Table of Contents
Dir Plugin
Compatible with DokuWiki
Detritus, Ponder Stibbons, binky, angua, rincewind, adora belle, weatherwax
Show content of current namespace, including sub namespaces and/or parent/sibling namespaces, in a table or list
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 Extension Manager. Refer to Plugins on how to install plugins manually.
For usage with Hrun or later, consider https://gitlab.com/dokuwiki-plugins/dir, download file .zip (you may update lupo49's “official” one with that)- Sorry, but this doesn't work either — 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 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!) — 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 pagelist plugin. The main difference with the pagelist plugin is that the pages to be listed do not have to be specified manually. It resembles the “archive>” tag in the 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 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 discussion plugin is installed, the number of comments of a page can be shown in a column. If the tags plugin is installed, the tags of a page can be shown in a column.
The dir plugin has rudimentary support for the 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 pagelist plugin is used) |
| list | Use the list style (styling of the 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 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! |
| Supported Column Names | Description | Sortable |
|---|---|---|
| page | Link to the page | ✔ |
| desc | Description of the page (See also “widedesc”) | ✔ |
| description | ,, | ✔ |
| user | Full user names of the contributors | ✔ |
| userid | User id's of the contributors | ✔ |
| date | See mdate | ✔ |
| mdate | Modification date | ✔ |
| cdate | Creation date | ✔ |
| comments | Number of comments in the discussion section | ✔ |
| tags | The tags of the page | ✔ |
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
- Restore class tag while using default wiki table renderer (2017-05-18 22:33)
- Use the original Dokuwiki table renderer (2016-08-25 20:37)
- Merge pull request #23 from splitbrain-forks/php7-signature (2016-02-27 18:31)
- Adjust method signatures to match parent (2016-02-02 13:05)
- Update plugin.info.txt (2015-03-02 15:50)
- Merge pull request #17 from gamma/master (2015-03-02 15:48)
- Merge pull request #20 from Intera/master (2015-03-02 15:48)
- [BUGFIX] Do not access protected renderer property (2014-10-08 15:51)
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. 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 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 …