18 - Data Forms
nav_first.pngFirst: design:1
1 - Rate Module
Edited: 29 Apr 2012 00:01 by: James Kanjo
Comments: 21
Tags:
nav_prev.pngPrevious: design:17
17 - Consistent Tool Arguments
Edited: 11 Nov 2009 15:46 by: Steven Heynderickx
Comments: 0
Tags:
Last: design:32
32 - Parenthood Module
Edited: 11 Nov 2009 21:47 by: Steven Heynderickx
Comments: 7
Tags:
nav_last.png
Next: design:19
19 - Join Module
Edited: 11 Nov 2009 12:06 by: Steven Heynderickx
Comments: 4
Tags:
nav_next.png

18 - Data Forms
Created on 30 Sep 2009 16:18
By pieterh

rating: +7+x
This is the Redirect module that redirects the browser directly to the "http://projects.wikidot.com/thread:126" page.

This is a design sketch for structured wiki page data. The goals of the forms system are:

  • To present normal users with a form instead of the raw wiki editor
  • To store that data in a structured format in the page
  • To show the data form as a properly-laid out form on the rendered data
  • To make this data available through the ListPages module

Overall, to make Wikidot accessible to a new class of user who is not able or willing to learn Wiki syntax, and thus to open the doors to a new class of wiki application: collaborative knowledge collection.

Current implementation

This is now available on wikidot.com. Please report any issues here.

How a form looks depends on the user. Site creators will edit the form layout, which goes into the category _template as a [[form]] definition. Site users will see the laid-out data when they view a page, the data entry form when they edit a page, and the data entry form when they create a new page via the NewPage module.

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           #  One of the field types, see below
    field-property: value...      #  Depending on the field type
[[/form]]

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 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
[[/form]]

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 field type is 'text' by default unless you specify values, in which case it's 'select' by default.

Usage notes

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]].

Planned implementation

Additional field types:

  • 'tag': works like select but sets a tag on the page, from a list of allowed tags. Note: we need a way to unset tags at the same time.
  • 'parent': works like select but sets the page parent, from a list of allowed parents. Note: only one parent field allowed per form, obviously. Further note: Shane suggests this field type is redundant if we can template the metadata for a page.
  • 'checkbox': shows a checkbox.
  • 'number': this lets the user enter numbers in various formats. For integers, decimals, etc.
  • 'date': this lets the user select a date from a calendar. Should show the date in a format consistent with the user's preferences.
  • 'password': this provides a text field that shows as a password. Note: password would be stored in plain text. We don't really have a use case for this yet.
  • 'pagepath': this lets the user create and select from a page within a 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. Note: does not affect page parent. Pagepath field is stored as a page full name.
  • 'wiki': 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.
  • 'file': this lets the user upload a file very simply. The file is shown with an icon and a 'preview' action. Note: might be extended to allow multiple file uploads. The value of the field (in ListPages) is the file name. A new page is created in given category (default: file). The file is attached to that page as an attachment. The page text may be added automatically containing metadata from the file.
  • 'image': this works as for file, but shows the picture with a caption. A new page is created in given category (default: image). The image is attached to that page as an attachment. The page text may be added automatically containing metadata from the file (for example stored in EXIF header). The displayed image is a link to that page. Normally you would create a photo:_template page that shows the image at original size and displays the metadata stored in the page.
  • 'hidden': this 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. Might work with template variables, e.g. %%user%%?
  • 'static': 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.

Each of these types has additional properties that we'll define later.

Additional field properties for all fields:

  • 'default' defines a default value for the field
  • 'join' shows the field on the same line as the previous field, if any
  • 'before' provides a string of wiki text that displays before the field value
  • 'after' provides a string of wiki text that displays after the field value
  • 'hint' provides a string of text that is displayed in a light color inside the field when it is empty
  • 'match' specifies a regular expression that the field value must match, on input

Additional functionality:

  • The NewPage module will detect that the target category contains a form, and show this. In the initial version, all fields in the form will be shown. Later we'll allow a selection.
  • Support for repeating fields that are laid out in a line.
  • Support for repeating groups of fields that are laid out as a table.

ListPages support:

  • Access to a field value using %%field{name}%%, and %%field_raw{name}%% for select fields.
  • Ordering and selection by form fields raw values.

CSS styling

Each table row has an ID of the field name (or the first field name on the row, if there are several).

Comments: 23

Add a New Comment