Story Notes:

Overview Documentation

TWiki Application

The Story Notes tracking system is implemented as a TWiki "application". TWiki applications take advantage of structured data, defined in TWiki Forms, plus formatted search results, to build small "database" applications within a TWiki web.

See TWikiTutApp for a tutorial if you're interested.

Major Pieces

  • TWiki Form
    The Form defines the "schema" for a project.

  • Initialization and Index
    The initialization page is used to create a new entry. When you create a Story Note, the Template is copied and the Form is filled in.
    This page also provides an Index of all Story Notes.


When a new Story Note is initialized, the template is copied into the new page.

The sections of the template are:

  1. Boilerplate and Variables
  2. Content Section

Boilerplate and Variables

This section pulls data from the attached form (meta data).

      * Set TOPICTITLE = %FORMFIELD{"SN_Title"}% %TOPIC%

   ---+!! Story Notes - %FORMFIELD{"SN_Type"}%
   ---+!! %FORMFIELD{"SN_Title"}%

Content Section

The content section should be edited for each Story Note.

TWiki Form

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

A TWiki Form is described by table of field definitions. TWiki can be any of several types. Runbooks use text, textarea, and menu (aka "select"). See SN_Form for the complete list of fields, types, sizes, and values.

Enabling a Form

Before a form can be used, it must be enabled in the WebPreferences topic of the web where it will be accessed. Forms must also be attached to a topic before they can be used. The easiest way to use a form is to attach it to a template. Then, when a new project entry is initialized, the template will be copied and the new page will automatically inherit a copy of the form.

To attach a form to a template (or any topic), edit the topic and click the "Add form" button (lower right). Select the appropriate form from the list of "Possible form templates" shown on the next page.


sample form
Screenshot of "empty" sample form.

Data Entry

New projects are initialized by clicking the "Create Page" button at SN_Index (This button is affixed to an HTML form; there is a subtle but important difference between HTML forms and TWiki forms. Different types of forms are described at TWikiTutForms.)

Naming Convention

New story notes pages are named SN_XXXX, where XXXX is replaced by a unique 4-digit, zero-padded sequence number upon saving, e.g. SN_0005 ...


The SN_Index page provides a complete index to all projects.

Admin Pages

The following pages comprise the set of administrative pages. To create a similar application, copy and modify these:

Also Edit

This wiki page is maintained by Rich Morin, an independent consultant specializing in software design, development, and documentation. Please feel free to email comments, inquiries, suggestions, etc!

Topic revision: r2 - 16 Mar 2008, RichMorin
This site is powered by Foswiki Copyright © by the contributing authors. All material on this wiki is the property of the contributing authors.
Foswiki version v2.1.6, Release Foswiki-2.1.6, Plugin API version 2.4
Ideas, requests, problems regarding CFCL Wiki? Send us email