(Original Page= http://www.wikidot.com/doc:data-forms )
Wikidot data forms make it possible to build simple applications into your wikidot sites. A normal wiki page holds unstructured text. A wiki page with a data form holds structured data ("fields"). Structured data is easier to edit, to understand, and to work with in many cases.
The data form feature is new and rapidly evolving. If you have feedback on it, come and discuss with us in this forum.
Examples of using data forms
Here are some examples of where data forms might work better than simple wiki pages:
- 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.
- I'm organizing my club membership and for each member I want a page with their name, email address and so on. By using a data form I can extract fields like the email address to send everyone a newsletter.
- I'm cataloguing my video game collection and using a data form means I can search on games by console, by publisher, and so on.
How to create a new data form
Wikidot stores pages in categories and when you use data forms, each page is one "object". So one category can have one data form, that applies to all pages in that category.
To create a new data form, edit the _template page in the category and add a [[form]] section. Here is a simple form that shows a few fields:
[[form]]
fields:
name:
label: Member name
email:
label: Email address
get-newsletter:
label: Get newsletter?
values:
0: "No"
1: "Yes"
default: 1
[[/form]]
When you define a [[form]] section, all pages in the category now magically show the form instead of the usual page editor.
How to use form data
The simplest way to use form data is to let people enter, browse, and improve it, just as for normal wiki pages. You can configure category permissions exactly as for normal pages so that, for example, only the author of a page can edit it. If you look at the page source you will see that the form data is stored in a format that looks a bit like the form definition.
You can also use form data in lists and reports, using the ListPages module:
%%form_data{name}%% | Field value from page data form if any |
%%form_raw{name}%% | For select and pagepath fields, the internal value saved in the page form data. For other field types, empty. |
%%form_label{name}%% | The label of the field as defined in the data form if any |
%%form_hint{name}%% | The hint of the field as defined in the data form if any |
These properties can be used in live templates to give greater control over the presentation of the data form on a page.
Is %%form_data{member-name}%% subscribed to the newsletter? %%form_data{newsletter}%%
====
[[form]]
fields:
member-name:
label: Member name
newsletter:
label: Subscribe to newsletter?
type: select
values:
1: "Yes"
2: "No"
[[/form]]
The Pagepath concept
Wikidot data forms have a unique concept, the Page Tree and pagepath, which is a way of organizing data. Imagine your video games collection, and you want to store for each game the genre of game. Game genres form a tree:
- _root
- Adventure
- Action
- Simulation
- Driving
- Other
- Combat
- Simulation
- Sports
- Football
- Racing
where each part of the tree is a wiki page. Imagine this tree is held in a category called genre:. Now we can use parent links to attach Racing to Sports, and Driving to Simulation to Action.
The Wikidot data form system makes it easy to navigate, and edit such a tree. You define a 'pagepath' field and tell it to use the genre: category. Then users can chose any genre, making the tree more precise (if the genre: category lets them create and edit pages) over time:
[[form]]
fields:
genre:
label: Game genre
type: pagepath
category: genre
[[/form]]
A page tree is always anchored to a page called _root that Wikidot creates automatically when you start using a page tree in forms.
Deleting a form
If you wish to remove a form from the _template, do not simply comment it out. Either delete it completely or change [[form]] to something like [[x-form]]. Otherwise the form will continue to be used.
Reference
The form definition is made in YAML, which is a simple structured markup language. A _template may have a single form. The form starts and ends with [[form]] and [[/form]] as for code blocks. Within those tags, we describe the form using YAML:
[[form]]
fields: # This is always required at the start
name-of-the-field: # Use a valid YAML name
label: Label # This is what the user sees
type: type-of-field # The field types
property: value... # Depending on the field type
[[/form]]
The default field type is 'text', unless you specify one or more values, in which case it defaults to 'select'.
Always start name of the field form with a letter. Field names starting with a digit or some other character is invalid. In case of special YAML symbols like true, false, yes, no, you may need to surround those with simple quote signs like this: "yes".
Field Properties
Properties that apply to all field types
The 'label' property
If you specify a 'label' property then the field gets that text in the left column, or before the field for joined fields. If you do not specify a label then the field has an empty space in the left column, or is squashed up after the previous field, for joined fields. For example:
[[form]]
fields:
address-line-1:
label: Address
width: 30
address-line-2:
width: 30
address-line-3:
width: 30
[[/form]]
The 'join' property
If you specify 'join: true' then the field is placed after the previous field, if any. This property has no effect if the field is the first in the form. For example:
[[form]]
fields:
city:
label: City
width: 20
postcode:
label: Postcode
width: 8
join: true
[[/form]]
The 'before' property
Provides a string of plain text that displays before the field value
[[form]]
fields:
phone:
label: Phone
width: 10
before: +(1)
[[/form]]
The 'after' property
Pprovides a string of plain text that displays after the field value
[[form]]
fields:
speed:
label: Car speed
width: 4
after: mph
[[/form]]
Properties that apply to specific field types
There are additional properties that only apply to specific field types. These are documented below with the field type(s) they apply to.
Field Types
The 'text' field type
Defines a text or text box field. Allows 'width' and 'height' as properties. If you don't specify a height you get a normal 1-line text field. If you do specify it, you get a text box. For example:
[[form]]
fields:
name:
label: Your name
type: text
width: 30
comment:
label: Your comment
type: text
width: 50
height: 3
email:
label: email address
match: /^[_a-zA-Z0-9\-\+]+(\.[_a-zA-Z0-9-]+)*@[a-zA-Z0-9-]+(\.[a-zA-Z0-9-]+)+$/
[[/form]]
The specific properties you can use on a text field:
- width: specifies the visible field width in columns (fixed spaced characters, more or less).
- height: specifies the field height in rows, 1 is normal text field, 2 or more is a text box.
- match: specifies a regular expression that the field value must match.
- match-error: specifies a custom error message.
- hint: provides a string of text that is displayed in the field when empty.
- default: defines a default value for the field shown on new pages.
The 'select' field type
Defines a multi-value selection field. Requires a set of values. If you specify two to four values, you get a horizontal radio field. If you specify five or more values, you get a drop-down select field. For example:
[[form]]
fields:
your-mood:
label: Your mood
type: select
values:
1: manic
2: happy
3: calm
4: down
5: depressed
her-mood:
label: Her mood
type: select
values:
1: silent
2: chatty
[[/form]]
The specific properties you can use on a select field:
- default: defines a default value for the field shown on new pages.
The 'checkbox' field type
Defines a checkbox field, stored in the form data as 0 or 1. For example:
[[form]]
fields:
onions:
label: Do you want onions?
type: checkbox
salami:
label: How about extra salami?
type: checkbox
default: 1
[[/form]]
The specific properties you can use on a checkbox field:
- default: defines a default value for the field shown on new pages.
The 'pagepath' field type
Lets the user create and select from a page within a page tree; the 'path' is the list of all parents plus that page. It is visualized as page / page / page / page with at each level, the option of viewing that page, changing the page, or adding a new child. This does not affect the actual page parent, and a form can have many pagepath fields. The pagepath field value is stored as a page full name. Hidden pages are invisible to users when selecting and navigating the page tree.
[[form]]
fields:
genre:
label: Game genre
type: pagepath
category: genre
[[/form]]
The specific properties you can use on a pagepath field:
- category: specifies the category that holds the page tree.
- default: defines a default value for the field shown on new pages.
The 'hidden' field type
Adds data to the form that the user cannot see or edit. Takes no space visually. This is for putting data into the page so that data can be used later. The value of the field is defined by the 'value' property.
[[form]]
fields:
version:
type: hidden
value: 1.0
[[/form]]
The specific properties you can use on a hidden field:
- value: sets the value of the field
The 'wiki' field type
Works like text but lets the user enter a block of wiki text. Note: wiki text is not allowed in normal text fields, it must be enabled explicitly with wiki fields.
[[form]]
fields:
version:
label: Fancy text field
type: wiki
[[/form]]
The 'static' field type
This shows uneditable wiki text and lets the form designer add text and formatting to the form. Static fields are not stored in the page. Static fields get their value from the 'value' property.
[[form]]
fields:
version:
type: static
value: Non-storable field with with **bold**, //strike// and __underline__.
[[/form]]
The specific properties you can use on a static field:
- value: sets the value of the field
The 'file' field type
This lets the user upload files directly from the data form. It is displayed as a link to the file.
Files are not uploaded to the same page. Instead, a separate page is created for each file in a different category, 'file' by default.
[[form]]
fields:
document:
type: file
label: Upload document
category: alternative-category
[[/form]]
The specific properties you can use on a file field:
- category: specifies the category that the page will be created in ('file' category if not specified), and the uploaded file is attached to this page.
Note that images won't be treated like they are when attaching an image to simple (non-data-form-enabled) page. This means there will be no thumbnails for them and they won't be displayed by [[gallery]] tag. We plan to make it more consistent with regular uploads, though. See the corresponding wish and if you feel this is an important issue, rate it up.
The 'url' field type
This lets the user enter URLs. This is displayed as a link.
[[form]]
fields:
info_link:
type: url
default: ftp://example.com/files/
match-error: Custom error msg.
required: true
default-schema: ftp://
[[/form]]
The specific properties you can use on a url field:
- width: specifies the visible field width in columns (fixed spaced characters, more or less).
- default: defines a default value for the field shown on new pages.
- default-schema: define a default schema for URL ('http://' if not specified).
- match-error: specifies a custom error message.
- required: specifies if the field is mandatory [true/false] ('false' if not specified).
The 'password' field type
This lets the user enter masked text. To the user, each character they type is replaced by an asterisk ( * ).
[[form]]
fields:
pass:
type: password
[[/form]]
Important: Entered text is not encrypted, you can always read it in page source.
CSS Styling
You can modify the look and feel of your data forms using CSS (either per-site, or per page using the CSS module. This is the CSS model for data forms:
- table
class: form-table- tr
class: form-row- td
class: form-labels- span
class: form-label
- span
- td
class: form-values- span/div (div for wiki and static)
class: form-value field-{name}
class': form-error (added to field while save when there is matching error)- label (auto-added to form when field have defined hint property)
class: form-hinted - {field}
class: form-{type} - span
class: form-message
- label (auto-added to form when field have defined hint property)
- span/div (div for wiki and static)
- td
- tr
Symbols:
{name} - name of the field
{type} - type of the field (text, select, pagepath etc.)
Live demo
- The forms.wikidot.com site is a live demo of the features of data forms.
- pagepath.wikidot.com shows examples of the pagepath concept.
*