Feature: add custom columns link to custom metadata of the page listed

[Kromtar]

Motivation

Currently, it is easy to create columns with the standard metadata used by DokuWiki or the metadata used by compatible plugins with pagelist (Blog, Tag...). But accessing custom metadata (in the .meta page file) and converting types for these data is not trivial. This feature is designed to be used in combination with another plugin I developed (custom meta) that allows adding custom metadata to pages. Using pagelist and custom meta, it is possible to create highly customizable tables <3.

General

This feature allows adding new columns to a table. Each column will be populated with values from the metadata of the listed page that match the column title. It is possible to access metadata values that are at the first level of the data structure (ex: creator) or within an array (ex: geo). This way, you can access both standard metadata, metadata from other plugins, and completely custom-stored metadata. The feature also includes the ability to transform UNIX timestamp data into a more user-friendly format.

Syntax

New flag customcols=. Separated by commas, we indicate the name of the column to be added. This name must match the key that stores the value to be tabulated in the metadata. This name will be used as the header for the column.

customcols=new_col_1,new_col_2

If we want to convert a value stored as a UNIX timestamp in the metadata to a more user-friendly value, we can specify the desired format in "[ ]" after the column name. The converted value will be tabulated. NOTE: The format used to define the conversion is strftime.

customcols=my_date[%Y/%m/%d],new_col_2

By default, the values of the keys are searched at the top level of the metadata structure. This means that we will generally access the standard metadata of DokuWiki in this way.

customcols=title,creator

If the key/value is located within an array in the metadata, it is possible to use ":" to prepend the name of the array.

customcols=array_in_metadata:key_name

It is possible to declare columns where their key/value pairs are stored in different arrays.

customcols=plugin_a:key_name_1,my_array:key_name_2,date:modified[%Y/%m/%d]

If we have many columns stored in the same array in the metadata, it can be cumbersome to repeat the name of the array over and over. It is possible to define the name of the array only when specifying the name of the first column. For the subsequent columns, you can add the ":" symbol at the beginning, and the last defined array to the left will be used automatically.

customcols=my_meta_array:key_1,:key2,:key3
(key_2 and key_3 will be searched within the last defined array to the left, in this case my_meta_array)

It is possible to "escape" and combine this rule to create combinations.

customcols=my_meta_array:key_1,title,date:created[%Y/%m/%d],:modified[%Y/%m/%d],my_meta_array_2:key_2,:key_3
(key_1 will be searched in my_meta_array. title in the high level of the metadata. created and modified in the date array. key_2 and key_3 in my_meta_array_2)

In cases where our use case always requires accessing the same array in the metadata to retrieve information (throughout the entire wiki), we can use the global configuration metaparentname to define the name of the array. This way, it will not be necessary to define it in each pagelist; by default, that array will be used to search for the information.

Note: Cases of arrays within arrays are not currently supported.

Implementation

A three-stage parsing of customcols= is performed. Initially, the string is split by "," to organize the configurations for each column.

Next, it is divided by the ":" symbol. Here, it is determined whether the key of each column should be searched within an array or not, and whether that array was defined in this column or in one of the previous ones (inheritance rule from the left).

In the third stage, a division by "[" is performed to check if any column should be subjected to a conversion from UNIX to a more user-friendly time format.

All these configurations are stored for later use in $this->customCols

The key of each column is used to print the header (if the option is activated) in startList(). The key of each column, along with its parent array (optional), is used to retrieve the information from the metadata in the function getCustomColData(). In this function, the global configuration for an array name is used if it is set. Each value of the column is printed in printCustomCol(). In this function, the UNIX conversion is performed if necessary.

Minor code modifications were made to add support for the global configuration of an metadata array name.