I'm getting started with using WikiDot and as an initial slightly complex task am using it to make a list of structured pages. WikiDot of course lets you create free-form pages with any content you want, but it also lets you create pages containing semi-structured data and present them pretty nicely. It also includes a "pagepath" feature that's supposed to create a hierarchical index of the pages. Their tutorial information is fairly useful but left me kind of confused initially, especially with the pagepath feature because part of it simply didn't work out of the box.
They describe the purpose as allowing you to "build simple applications into your wikidot sites" and say that "Structured data is easier to edit, to understand, and to work with in many cases." They give several examples including:
- I'm collecting references for my thesis, and for each reference I want to record it title, author, ISBN, date of issue, publisher, and language. If I use a data form with one field for each piece of data, I can easily produce reference lists in any format.
This is a pretty common need and fortunately they designed the data forms system so you describe your data with the exact fields you want, to make it easy to accommodate your precise needs.
Getting started
To get started you create a new category to house the data form entries, and define a category template that contains the form definition.
That may have been confusing, so let's break this apart a little. In WikiDot categories are defined simply by creating a page name of "category-name:page-name", where everything up to the ":" is the category name. Everything after the ":" is the page name. You could have the same page names within multiple categories. Category names get used many ways in WikiDot such as forums, blogs, and all your site templates are stored within the "template:" category.
You create a new category very simply by creating a new page with a new category name. For example to create a "reference" like the example above you enter something like "reference:Zen and the art of Motorcycle Maintenance" in the "Add new page" box.
You can easily create a category full of wiki pages this way, but we want to create a category full of pages using data forms. To enable a data form on a category you create the page "category-name:_template" (the page "_template" within your chosen category name), then edit the template and insert the data form description.
For example create the template for the reference data form by entering "reference:_template" into the "Add new page" box. Click the edit button at the bottom of the page then enter this form description (it lists the fields described above for References).
[[form]]
fields:
title:
label: Title
type: text
width: 50
author:
label: Author
type: text
width: 30
isbn:
label: ISBN
type: text
width: 30
publishing_date:
label: Publishing Date
type: text
width: 30
publisher:
label: Publisher
type: text
width: 30
language:
label: Language
type: text
width: 30
comment:
label: Your comment
type: text
width: 50
height: 3
[[/form]]
With this data form in place, if you now create "reference:Zen and the art of Motorcycle Maintenance" you've got a new kind of page editing experience. Normally when creating a page WikiDot gives you a text edit field, with a bunch of formatting buttons above it. But with the form description in the template you instead are presented with text entry fields matching the form described above.
The syntax of the data forms is fully described on the WikiDot doc:data-forms page linked below. It is fairly obvious how it works, fortunately.
Organizing your Data Form pages with the Pagepath feature
WikiDot lets you organize your Data Form pages using their Pagepath feature. It is a hierarchical organization system that is fairly easy to add to a data form description, but the user interface is pretty bad, and it automagically creates pages meant to help you navigate through the hierarchy but out of the box are next to useless.
Adding a pagepath is as simple as adding the following lines to the data form description.
genre:
label: Genre
type: pagepath
category: genre
Books come in Genre's (Sci-Fi, Fantasy, and maybe some others) and there are sub-genre's and so on. Humans like to create complexity so of course the categorization of books is complex. You can label your pagepath with anything you like.
Now when you create a new Reference a new field labeled Genre is shown. The Genre pagepath is tied to a new category, named 'genre'. Behind the scenes pagepath automagically creates pages for each name you enter in the Genre pagepath, but we're getting a little ahead of ourselves.
Go back and edit the "reference:Zen and the art of Motorcycle Maintenance" page we created earlier. Or if you like, create a new page in the reference category. While editing the page you'll see a new row labeled Genre, and a drop down thingy on that row. The drop down thingy will be empty except for the phrase "create new" and if you chose "create new" a text entry box will appear letting you type in a Genre name. If you have already entered some Genre names, they'll appear in the drop down thingy.
Go ahead and enter a Genre name, for the book Zen and the art of Motorcycle Maintenance, the Genre probably should be "Philosophy". You'll see a new dropdown pop into existence, and it'll probably list only "create new". If you need to use sub-categories this is how you'd add a sub-category. For example, for the book Zen and the art of Motorcycle Maintenance, the sub-Genre could be "Zen" perhaps. That would give you the full category "Philosophy / Zen", perhaps.
Now when you save the page you'll see a new row for Genre, containing a link with the genre name you entered. The link heads to a page named "genre:Genre Name You Entered". We'll discuss this page in the next section.
Navigating the Pagepath hierarchy
The purpose of using Pagepath is to organize similar entries in the data table. We've already seen that pagepath automatically creates pages within the category we named when creating the pagepath. BUT, out of the box, the category page is nigh on useless. It shows only the name of the pagepath entry, the breadcrumb trail leading to the pagepath entry, and nothing else.
The purpose of pagepath is to organize entries in a data table, but out of the box this doesn't do the job. Fortunately it's fairly simple to make a pretty decent stab at this.
We notice that pagepath links to a page named something like "genre:zen". We declared "genre" to be the category, which means we can edit the category template "genre:_template" and change how pages in this category are displayed.
A good start is this template:
%%content%%
[[module Backlinks]]
The Backlinks module takes care of creating a list of pages linking to the current page. Because pagepath works by creating links to the auto-created category pages, then Backlinks automatically generates a list of pages belonging to the specific category entry.
The "%%content%%" bit is useful so that you can edit the generated pages, and add some explanatory text at the top.
Using the Backlinks module isn't optimal. For example in a nested hierarchy doesn't show sub-categories properly. For example if you categorize Zen and the Art of Motorcycle Maintenance as "Philosophy / Zen / Sixties" the link to this book will be on the "Sixties" page but not on "Zen" nor on "Philosophy". Further neither the Zen nor Philosophy pages will have links to the sub-categories. I haven't figured out what to do yet.
Summary
We learned quite a bit in this tutorial. Such as:-
- Data tables in WikiDot
- The difference between normal page editing and data form editing in WikiDot
- Categories
- Category templates
- The pagepath feature
- A little about using modules
However we came out with a sub-optimal user experience. I have my doubts the result will be understandable to the unwashed masses, but that instead you'll have to write up training material before your users will be able to use the pagepath feature.
Creating categories and sub-categories in pagepath is non-intuitive and there is no option for embedding instructions in the middle of the form. This means you have no choice but to write some other page for instructions. Instructions that cannot be linked from the data edit page.
Another issue is the non-intuitiveness of creating a data form page in the first place. You have to know to create the new data form entry using the correct category prefix. Really? And they thought this was user friendly? I'm shocked.
These issues could be easily worked around with a a WikiDot managed by a small group of people. But what if your WikiDot is thrown open to the masses and they're expected to add data table entries on their own. How are you going to instruct them in successfully doing this? Really?
It's a good feature, just has a flawed user interface.
Source:
http://www.wikidot.com/doc:data-forms
http://www.wikidot.com/doc:data-forms#toc3