18 - Data Forms
Created on 30 Sep 2009 16:18
By pieterh
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).
Does "%%field{news}%%" actually work? I'm working on it here: http://education-template.wikidot.com/home and it doesn't work. :-(
Kenneth Tsang (@jxeeno)
Not yet, sorry. I realize this makes forms slightly useless.
Portfolio
Yeah. LOL xD
Kenneth Tsang (@jxeeno)
Agreed.
I modified the document, to reflect design improvements made recently at Wikidot.
Files (including images) are stored at separate pages. This allows to keep additional history, dump metadata of the files, show a license text and better templating.
I removed the "index" property. The field will be indexed (to sort and order) based on its type (most if not all of field types should be indexed). No need to put "index" in the field definition.
Piotr Gabryjeluk
visit my blog
Umm, what do you mean?
I thought all files were stored in the wdfiles domain, under the url syntax of /local--files/page-name/file-name
Exactly.
But those fields won't attach the files to the current page, but create a separate page, attach files there and keep reference to that page in current one.
Piotr Gabryjeluk
visit my blog
I've implemented this on onlyjoking.wikidot.com. It would be nice if some fields recognised wiki syntax; as if you follow that link, you'll notice the "source" field which shows an un-linked url :(
Having realised the potential of this module, I am now very excited and hope all the features land soon :D
I forgot to add before. Why doesn't this share the same syntax with the MailForm Module? That syntax makes a lot of sense to me, and has some extra functionalities that aren't here already (for instance, matching regular expressions, and hints).
A big problem I found also, is the use of the data form code on a typical wikidot page (that is, a page that is not :_template). An AJAX error will occur every time you attempt to use the code. The same AJAX error message appears if you try to rename an :_template page to a normal wiki page. This is not desirable; it is much more friendly and useful to have an error-popup saying “You can't use data forms within typical wikidot pages. They can only be used within category templates.”.
This is fundamental ! With this, you can use this on your :_template page:
@James, thanks for the suggestions for CSS IDs, which I've incorporated.
Originally I wanted to use the MailForm syntax for obvious reasons. There was some debate internally. We settled on YAML because it lets us use the same syntax for the stored data, and for the form. It's also more expressive and it's a standard. So we can find syntax highlighters, we can find tools to process YAML data, etc. etc.
The Ajax errors are not nice: that's logged and we'll fix them. This code is still raw, obviously.
Portfolio
The current HTML output is:
I propose that each table row have an ID of the field-name, as it is a requirement that each field-name be unique. This way, we can control (via CSS) the form's output. HTML being rendered may look like this:
I'd like a way to let the user select from a list of options using the select type. Depending on which option they select, it should set a tag to the page in the same way that the NewPage module does. From what I can tell this is not yet planned?
'pagepath' seems like it might cover parents, from what I understand of it. But tags are missing.
~ Leiger - Wikidot Community Admin - Volunteer
Wikidot: Official Documentation | Wikidot Discord server | NEW: Wikiroo, backup tool (in development)
Short term feature requests
The things I need to implement this in a real scenario as planned:
Long term feature requests
And at a later date (though not necessary yet)
e.g. uploaded-file.zip which can be accessed by %%field{filename}%% or similar)
The reason I need the filename is that I have a link like this in my category's live template:
Asking the user to use a specific filename is a solution to the problem, but in this particular situation it's not ideal. At the moment I'm asking the user to manually type in the filename, which leads to mistakes if there's a space in the name (people don't use %20), or if they type in the full URL instead (which happens often)
Consider this post my "weneed" inside the weneed weneed:44
~ Leiger - Wikidot Community Admin - Volunteer
Wikidot: Official Documentation | Wikidot Discord server | NEW: Wikiroo, backup tool (in development)
I've incorporated the notion of tag and parent field types: great idea, and will be very useful. One thing to solve: a tag field should remove existing tags of a certain type. We could say that we remove all hidden tags if we set a new hidden tag. Or we could have a property like 'prefix' that means, 'put this text in front of the saved tag, and remove all other tags that start with it'. So, for an issue tracker, 'prefix: _state_'.
To set the parent automatically at creation, I guess NewPage will work as before.
For file type fields, I assume the value of the field would be the filename, yes.
Portfolio
Re: tags
The prefix idea has merit. The other alternative, of course, would be to delete all tags & replace them with the ones specified in the form (the form would be pre-populated with the current tags when editing the page, I assume)
What would be perfect, though not necessary, is an alias for each tag. For example, my "Three Word Category" could be represented by the tag _3 , and I'd want to show 'Three Word Category' to the page creator, instead of the actual tag name.
Re: parents at creation
Exactly. So for me, that would work well. For someone else, they may also need to convert a plain text field that the page creator enters, so that it's the parent of the page?
Re: filenames
The thought crossed my mind that the field might be something like C:\user\shane\desktop\image.png, but if it's just the filename, that works fine for my own needs, at least.
Or:
~ Leiger - Wikidot Community Admin - Volunteer
Wikidot: Official Documentation | Wikidot Discord server | NEW: Wikiroo, backup tool (in development)
My brain hurts with that, trying to figure out at what stage the _template is applied. But it could work, yes, and I really like the idea of moving this into user space.
Idea noted.
Portfolio
http://cyclods.wikidot.com/test2:new
View of page:
Page source:
Only the second one is appearing.
~ Leiger - Wikidot Community Admin - Volunteer
Wikidot: Official Documentation | Wikidot Discord server | NEW: Wikiroo, backup tool (in development)
This is directly related to something I discovered. You can't use attributes of the same name, otherwise only the latter identical name will be displayed.
More to the point, the code that Pieter posted above will not work correctly:
[[form]]
fields:
[[/form]]
The first field-name, name, is identical to the second field-name, name.
Only the second name data will be displayed.
Sorry, was too rushed to actually test the examples. Fixed it now.
Portfolio
Edit-Append should not create a second instance, but act just like a normal edit. I've noted this bug, thanks for testing that.
Portfolio
Thanks for the fix :)
Just a minor note, the error message says this —
"be" and "only" seem to be the wrong way around to me, it doesn't sound right the way it is =/
Sounds better (IMO)
~ Leiger - Wikidot Community Admin - Volunteer
Wikidot: Official Documentation | Wikidot Discord server | NEW: Wikiroo, backup tool (in development)
My eyes lit up when I saw this in my inbox. Thanks a lot Michal, Pieter, Piotr, and anyone else I've forgotten XD
Planned implementation
I assume that this only appears as a password on the form, but is saved as plain text? Or will it be encrypted somehow?
~ Leiger - Wikidot Community Admin - Volunteer
Wikidot: Official Documentation | Wikidot Discord server | NEW: Wikiroo, backup tool (in development)
The password field type is there for completeness but in fact I don't have a proper use case for it yet. We can assume it'll be stored in plain text, and can't be viewed afterwards except by the admin.
Portfolio