Structured Data — a DokuWiki plugin

Author: DokuWiki.org. Link to original: http://www.dokuwiki.org/plugin:data (English).
Tags: database, DokuWiki, plugin, SQLite Submitted by alexgearbox 21.12.2010. Public material.
This plugin allows you to add structured data to any DokuWiki page.

Translations of this material:

into Russian: «Данные» — плагин для «Докувики». 25% translated in draft.
Submitted for translation by alexgearbox 21.12.2010

Text

====== Structured Data Plugin ======

---- plugin ----

description: Add and query structured data in your wiki

author : Andreas Gohr

type : syntax, action, helper

lastupdate : 2010-04-25

compatible : 2009-12-25+

depends : sqlite

conflicts :

similar : fields, pagemod

tags : database, sqlite, data, tags, tables, listing

downloadurl: http://github.com/splitbrain/dokuwiki-plugin-data/zipball/master

sourcerepo : http://github.com/splitbrain/dokuwiki-plugin-data/

bugtracker : http://github.com/splitbrain/dokuwiki-plugin-data/issues

donationurl: http://donate.dokuwiki.org/data

----

This plugin allows you to add structured data to any DokuWiki page. Think about this data as additional named attributes. Those attributes can then be queried and aggregated. The plugin is similar to what was done here for the [[plugin:repository|repository plugin]] but its internals are very different to the [[plugin:repository|repository plugin]].

**This plugin requires the SQLite extension for PHP!** (Should be included with PHP5).

===== Download and Installation =====

This plugin can be downloaded manually or through the [[plugin|Plugin Manager]] from the download link given above.

==== Changes ====

{{rss>http://github.com/feeds/splitbrain/commits/dokuwiki-plugin-data/master date}}

==== Updating from versions prior to 2010-03-22 ====

Since 2010-03-22, the data plugin uses the [[plugin:sqlite|sqlite helper plugin]]. Therefor, the database file location and structure changed. If you want to keep your old database, you have to perform the following steps prior to upgrading the data plugin:

- Install the [[sqlite]] plugin

- Move the file ''data/cache/dataplugin.sqlite'' to ''data/meta/data.sqlite''

- Perform the following SQL statements on the database (for example using the sqlite plugin’s admin page)<code sql>

CREATE TABLE opts (opt,val);

CREATE UNIQUE INDEX idx_opt ON opts(opt);

INSERT INTO opts VALUES ('dbversion', 1);</code>

- Upgrade the data plugin

If you upgraded the data plugin before these steps, a blank ''data.sqlite'' has been created and you have to copy the ''data/cache/dataplugin.sqlite'' over the existing ''data/meta/data.sqlite''.

===== Plugin Syntax =====

This plugin depends on multiple parts, each having a similar syntax. The syntax defines a block with various key/value pairs configuring the behaviour of the plugin part.

==== Data Entry (Input) ====

This part is used to add structured data to a page. All data entered here is tied to the page. Let's start with an example:

<code>

---- dataentry projects ----

type : web development

volume : 1 Mrd # how much do they pay?

employees : Joe, Jane, Jim

customer_page : customers:microsoft

deadline_dt : 2009-08-17

server_pages : servers:devel01, extern:microsoft

website_url : http://www.microsoft.com

task_tags : programming, coding, design, html

----

</code>

As you can see the block is defined by hyphens and the word ''dataentry''. You may add additional words after the ''dataentry'' keyword. Those will be added as additional CSS classes in the final HTML output and can be queried as ''%class%'' later. You can use this for styling how different entry types should be displayed later or limiting aggregation to certain types of pages.

You may use the ''#'' character to add comments to the block. Those will be ignored and will neither be displayed nor saved. If you need to enter ''#'' as data, escape it with a backslash (''\#''). If you need a backslash, escape it as well (''\\'').

Inside the block you see //column names// and their //values//. There are a few rules for the column names:

* Use any name you like

* If the name ends with the ''s'' character, you may add multiple values separated by commas (like in the employees row). This removes the last ''s'' character from the rendered column name. If you want to avoid the multiple value option and keep your column name as is, add an underscore to the end of your name (example: "thickness_ : 1cm").

* Special //types// can be added to the name to have the output formatted accordingly. Use an underscore to separate //identifier// and //type//. The following //types// are available currently:

* ''dt'' -- a date in the form YYYY-MM-DD, formatted as simple text but the input is checked for correct format

* ''page'' -- the entry is treated as Wiki [[:pagename]] and will be linked in output

* ''title'' -- like page, but an additional display title can be given separated by a pipe

* ''nspage'' -- like page, but the column name is treated as namespace for the link.

* ''url'' -- the value will be treated as external link

* ''tag'' -- the values are linked to a page named after the column name, using the value as control filter for a data table

* ''mail'' -- the value is checked to contain a valid email address, additional text is used as name that will be linked with the given email address

* ''img<num>'' -- the input is assumed to be a image URL or local media id. The optional <num> is the wanted width in pixels to resize the image to (defaults to 40)

* ''wiki'' -- render the input as wikitext

* ''pageid'' -- the input is the caption for a link to the data entry page

* when no type is given, it's just treated as simple string

* new types can be create by using [[#Type Aliases]]

* When using a type, add the ''s'' for multi-values at the very end (like in the ''server_pages'' row)

==== Data Table (Output) ====

To aggregate the structured data attached to various pages in your wiki this syntax is used. It will display a configurable table with the data you want. The table can be sorted and filtered. Paging is supported as well. And just as with the dataentry, you may add additional words after the datatable keyword. Those will be added as additional CSS classes in the final HTML output. Let's start with an example again:

<code>

---- datatable ----

cols : %pageid%, employees, deadline_dt, volume

headers : Details, Assigned Employees, Deadline, $$$

max : 10

filter : type=web development

sort : ^volume

----

</code>

The above config will display a table with all web development projects, the employees assigned to the project, the deadline and the volume. The table will be sorted by the volume and will display a maximum of 10 projects.

The keyword before the colon is a configuration option and the value behind is the actual setting. To make it more fault tolerant often multiple option names are possible. Here is a list of all available options:

^ Option(s) ^ Required? ^ Description ^

| cols\\ select | yes | These are the attributes you want to display. These are the same //names// you used in the Data Entry part |

| head\\ header\\ headers | no | If specified, these names will be used in the table headers instead of the column names |

| max\\ limit | no | How many rows should be displayed. If more rows are available the table will be made browsable. If not given all matching rows are shown |

| sort\\ order | no | By what column should the table be sorted initially? Prepend a ''%%^%%'' to reverse the sorting |

| filter\\ where\\ filterand\\ and | no | Filter by a column value. You may specify this more than once, multiple filters will be ANDed. |

| filteror\\ or | no | Like filter, but multiple instances will be ORed |

For filtering, multiple comparators are possible:

^ Comparator ^ Meaning ^

| ''='' | Exact match |

| ''!='' or ''<>'' | Does not exactly match |

| ''<'' | Less than |

| ''%%<=%%'' | Less or equal than |

| ''>'' | Greater than |

| ''%%>=%%'' | Greater or equal than |

| ''~'' | Wildcard match. Use a ''*'' as wildcard. Like ''Apple*'' to match ''Apple Pie'' and ''Apple Computer'' |

| ''!~'' | Negative Wildcard match. Select everything that does not match the expression. |

You may use the special word ''%user%'' in a filter to make it match against the currently logged in user. To compare with the current date, use the special word ''%now%''.

This syntax will disable all caching for the current page!

Pages: ← previous Ctrl next
1 2 3

© Андреас Гор и сообщество «ДокуВики». License: CC Attribution-Noncommercial-Share Alike 3.0 Unported