Wiki Applications

Before reading this topic, we recommend that you review the training presentation, Advanced Wiki Applications: What and Why?

Add structure to content with forms attached to Wiki topics.

Wiki forms (with form fields) and formatted search are the base for building "database-like" applications.

Summary

  1. Create a Wiki Form and define fields
  2. Create a Template topic - stationery for all pages in your application.
  3. Add your Wiki Form to the Template topic
  4. Create an HTML Form with appropriate (matching) fields, to use for data entry
  5. Define a SEARCH function for querying and indexing pages.
  6. Begin creating instance pages

Major Pieces

  • Wiki Form
    The Wiki Form describes the "schema" for project metadata. A copy of the Wiki form will be attached to each instance page.
    A Wiki form is defined as a table with a very specific structure.

  • Topic Template
    The Topic Template ensures that all project pages contain the same information and have a consistent Look and Feel.
    The Topic Template and Wiki form are copied together to create each project instance page.

  • Creation form
    A "creation form" is used to create a new project page with appropriate metadata.
    The creation form is written in HTML (<form action...).

  • Index, Tracking, and Query
    The Index page is used to track and query the set of projects. It presents a "query form" for narrowing the set of pages to view.
    The query form is written in HTML (<form action...).

  • Instance Pages
    The instance pages are analogous to the "rows" in a database. You'll have one instance page for each project, blog entry, team member, status report.... whatever your application is tracking.

Wiki Form

Pages with Wiki Forms act like a distributed database, making Wiki "applications" possible. By adding structured, form-based input to a page, topics can be structured with unlimited, easily searchable data fields.

A Wiki Form is described by table of field definitions. Wiki form fields can be any of several types. Projects use text, textarea, and menu (aka "select") fields. See DataForms for a complete list of fields, types, sizes, and values.

CAUTION : If you make changes to the Wiki form, be sure to apply those changes to the HTML creation form as well!

screenshot

Sample Wiki Form Definition

Examples: WikiTutAppE1Form, WikiTutDocForm

Name: Type: Size: Values: Tooltip message: Attributes
Document Name
text
60
Name of this Document
Document Author
text
60
Author of this Document
Document Pub Date
date
12
Publication Date (planned)
select
1
Choose category
select
1
Choose type
Document Summary
text
60
Brief description (100 chars)
Document Keywords
textarea
80x6
Optional. Freeform field. Enter keywords that might make searching easier
Document Status
select
1
Draft, Published, Revising, In Review, Needs Review, Archived
Document Status

Sample Form Field Values

Form fields that have multiple choice values define those values in a separate topic. The topic name matches the field name.

Examples

If you change any of the fields of the Wiki Form, be sure to synchronize those changes with the initialization and search forms. (There are notes on all of these pages to remind you to keep the values in synch.)

Using Wiki Forms

Once you have defined a form, it must be attached to a topic before it can be used. The easiest way to use a form is to attach it to a topic template. Then, whenever a new instance page is initialized, the template will be copied and the new page will automatically inherit a copy of the form.

There are three ways to attach a form to a topic.

1. Use an HTML form to create the page (example below). Be sure the HTML form defines your Wiki formtemplate

2. Edit the topic, adding ?formtemplate=NameOfForm to the URL

3. Edit the page and click the "Add Form" button in the lower right. Select the appropriate form from the list of "Possible form templates" shown on the next page. Before a Wiki Form can be attached this way, it must be set in the WebPreferences topic of the web where it will be accessed, e.g.
 
   * Set WEBFORMS = MyForm, ThatForm, Yourform 

Note that WebPreference calls this "enabling" a form; this only means the form can be chosen from the "Add Form" button. It is not necessary to "enable" a form this way in order to use it.
Add form button

Topic Template

When a new project is initialized, the topic template is copied into the new page.

The sections of the template include:

  1. code to print a Warning Message if you're viewing the template itself
  2. Project Name
  3. Project Health (imported from Sprint Manager)
  4. Milestones and other project management tables
  5. ...

Create an Instance Page

New instance pages are created by filling in the (HTML) creation form. When you click "Submit", a new instance page will be created (by copying from the template) and the entered data will be placed in the associated Wiki Form.

Example: See WikiTutDocAppCreate

(Note: There is a subtle but important difference between HTML forms and Wiki forms; different types of forms are described at WikiTutForms.)

The HTML Form

The HTML-based form contains most of the same fields / types as the Wiki form.

CAUTION : If you make changes to the (HTML) creation form, be sure to apply those changes to the Wiki form as well!

Example:

<form action="%SCRIPTURLPATH%/save%SCRIPTSUFFIX%/%WEB%/"> 
  <input type="hidden" name="onlywikiname"  value="on" />
  <input type="hidden" name="onlynewtopic"  value="on" />
  <input type="hidden" value="DocAUTOINC00001" name="topic" />
  <input type="hidden" name="templatetopic" value="DocTemplate"  />
  <input type="hidden" name="topicparent"   value="DocIndex"  />
  <input type="hidden" name="formtemplate"  value="DocForm"  />


<div class="twikiForm twikiEditForm">
<table class="twikiFormTable">

<tr>
<th align="right"><span title="Name of Project"> Project Name</span></th>
<td align="left"><input type="text" name="TutProjectName"  size="60" class="twikiInputField twikiEditFormTextField" /></td>
</tr>

...

<tr>
<td colspan="2">
  <input type="submit" value="Submit"/>
</td>
</tr>
</table>
</div>


</form>

Form Field Values

See Form Field Values, above.

Search / Query

The index/query page allows you to narrow the projects you see based on various criteria. If you don't provide any Search criteria, this page usually provides an index to all instance pages in your application.

Naming Conventions

A naming convention for instance pages is strongly encouraged. For example, project pages might be named with the prefix WombatProject, runbooks with the prefix RunBk, and so on.

Wiki can automatically generate a unique topic name by adding a sequence numner to the prefix you choose.

Automatically Generated Sequence Numbers

A string of (10) XXXXXXXXXX will be replaced by a unique sequence number upon saving. For example, RunbkXXXXXXXXXX will result in RunBk1, RunBk2, RunBk3... Note that sequence numbers created this way will not be zero-padded. Also, if you ever delete a topic, the sequence number it had will be available for reuse.

Or, use AUTOINC, e.g. WombatProject_AUTOINC000 will result in WombatProject001, WombatProject002, etc. Note that sequence numbers created this way will not be zero-padded. Also, if you ever delete a topic, the sequence number it had will not be reused. See TWiki Templates for additional details.

Keep The Pieces In Sync

There is a very tight relationship between the parts of a Wiki application. For example, there are three "forms":
  • Wiki form -- provides structure to the metadata associated with each project page
  • "Creation form" (HTML) -- used to create a new project page
  • "Query" form (HTML; optional) -- used for querying project pages

The "Creation form" form sends initial data to a Wiki form. The Query form describes possible Wiki form fields you can search through. Be sure to keep the forms in sync with each other.

These forms share fields. If you add/modify/remove a field in the Wiki form:
  • Do you need to change the "Create" form?
  • Do you need to change the "Query" form?

Important: There is not, necessarily, a perfect one-to-one relationship between the fields in the three types of form. The Creation form can contain hidden fields that the user never sees (or ignore fields that are included in the Wiki form.) A Query form often presents only a subset of fields for searching.

Also, the field types do not need to match between forms. For example, the creation form may present a menu from which to select a property. However, the Wiki form (on each instance page) may treat this as a text field (unaffected if the menu ever changes).

Additional References

Documentation

  • DataForms - official documentation for Wiki Forms

  • WikiTutForms - An explanation of the multiple, subtly different, things in Wiki land that are all called "forms".

  • TOPICTITLE Override - customize the page title to something more human-readable than a WikiWord name

A Sample Application

Starter Pages

  • BaseForm - barebones Wiki form topic to build on (no fields defined)

Topic revision: r2 - 29 Mar 2014, VickiBrown
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding CFCL Wiki? Send feedback