Advanced Wiki (Part 2)

Building Powerful Wiki Applications

See also:

Start presentation

Slide 1: Building Wiki Applications

http://wiki.cfcl.com/bin/view/Help/WikiTrainingAdv2

  • Intended Audience
    • Anyone who is familiar with Wiki

  • Pre-requisites
    • An understanding of what Wiki applications can do WikiTrainingAdv
    • An interest in creating or using Wiki applications to enhance productivity

Slide 2: What's Covered

  • Overview
  • Applications - Details *Wiki Form
    • Template topic
    • Initialization
    • Instance pages
    • Query pages
  • Examples
  • References

Slide 3: Wiki Applications

Powerful Wiki applications typically consist of

  • A set of related Wiki topics ("*instance pages*")
    Created programmatically from
    • A Wiki template topic
    • A Wiki form
    • Initial user-entered data (HTML form)
  • One or more query (index) pages
  • Wiki plugins and variables

Slide 4: The Parts of an Application

Wiki applications are built from the following parts. Some of these are required; others are optional.

  • Wiki Form (1; required)

  • Template topic (1; required)

  • Instance pages (many; required)

  • Initialization form (1; recommended)

  • Query pages (formatted search; required)

  • Ancillary pages (optional)

Plan ahead. Design the parts.

Slide 5: 10 Steps to an Application

  1. Analyze the Problem
  2. Design the Application
  3. Create a Wiki Form and define fields
  4. Enable the form (set the variable WEBFORMS in WebPreferences)
  5. Create a Template Topic
  6. Add the Wiki Form to the Template topic
  7. Create an initialization form (HTML Form) with necessary fields
  8. Create the first instance page in your application
  9. Create query pages for listing items
  10. Review and refine

Slide 6: Analyze the Problem

  • What kind of application will this be?

  • Who is the audience for the application?

  • Who "owns" the application?

  • What kinds of data are involved?

  • What parts of the applications may change over time?

Slide 7: Analysis

  • What kind of application will this be?
    • What are the use cases?
    • What are the goals?
    • Is it mission critical?
    • Are there security issues?

  • Who is the audience for the application?
    • Who enters data?
    • Who runs searches?
    • Who updates information?

  • Who "owns" the application?

Slide 8: Analysis, Continued.

  • What kinds of data are involved?
    • What are the inputs? (gozintas)
    • What are the outputs? (gozoutas)

  • What parts of the applications may change over time?
    e.g. data formats, data values, report formats

  • How often are changes expected to occur?

  • What information will be static?

  • What information will be repeated?

Slide 9: Design

  • Choose a Naming Convention
    • Aids searching, indexing, and administrative tasks
    • Choose how instance pages will be named

  • Design The Parts off the Application
    • Wiki Form
    • Initialization Form
    • Template
    • Queries

Slide 10: Choose a Naming Convention

  • Design a general convention.
    • ProjectDetail

  • Think about searching and sorting.

  • Order name components from general to specific.
    • ProjectDetailForm
    • ProjectDetailPageCreate
    • ProjectDetailPageFormat
    • ProjectDetailTemplate

Note: A naming convention is not required by Wiki. It is recommended as Best Practice, however.

Slide 11: Plan Names for Instance Pages

ProjectDetail200809p0, ...

  • Remember, there will be many instance pages.
    • "derivative" is simpler than "creative"
    • p0 - "key" to this page

  • 200809 - If data is time sensitive, consider including a date stamp.
    • 4-digit year
    • 2-digit month (day, hour, ...)

  • Related pages can share part of the name
    • ProjectDetail200809p1
    • ProjectDetail200809p0_Prelaunch

Slide 12: Wiki Form

  • Defines the metadata to be associated with a class of instance pages

  • Is analogous to a table definition in a database "schema"

  • Guarantees consistency of metadata within the application

  • Defines the user interface for data entry or update on instance pages

  • Provides a framework for initialization process

Slide 13: Plan The Wiki Form

Ask yourself:

  • What data fields do you need?

  • What types should the fields be?
    • checkboxes or radio buttons
    • date picker
    • pulldown menus
    • text fields (free form)

  • Adding fields and values later is easy; removing or changing field values can cause problems!

Slide 14: Template Topic

Instance pages are created by copying from a template topic.

Template topics:

  • Are analogous to stationery in word processing programs

  • Are used during instance page creation

  • Ensure a consistent look and feel between instance pages

  • Allow variables to be passed in and expanded (magic :-)

Slide 15: Instance Pages

Each instance page is a "report", representing one (input) data record.

Instance pages combine static text and formatting with information derived from associated metadata. The format should be designed to make the information easy to find and comprehend.

Examples:

  • Contact page for a team member
  • Detail page for a project
  • Blog post entry

Slide 16: Design The Template Topic (Design the Instance Pages)

Each instance page in the application is copied from a template topic. In designing the template topic, you're really designing the instance pages.

Ask yourself:

  • What should an instance page look like?

  • Will a user be editing the instance pages?
    • or only the form data?

  • Can any parts of the instance page be shared (read-only) content?

Slide 17: Initialization Form

The initialization form creates an instance page from:

  • Template topic

  • Wiki form

  • Entered data

data flow diagram

Slide 18: Initialization Form

  • Often built with an HTML form (< form ... >).

  • Usually maps closely to the Wiki form.

  • Allow initial data entry

  • Create an instance page

Slide 19: Design The Initialization Form

Additional information can be specified at initialization time that is not defined by the Wiki Form.

For example:

  • The initialization process controls the name of the instance page.

  • Initialization can pass data directly into the instance page (e.g. current date, user name).

  • Initialization can set default values in Wiki form (no user interactiob)

Slide 20: Query Page

A query page provides dynamically generated reports using Wiki's formatted search capability.

Examples:

  • Simple index to all instance pages

  • Search form with user-specified criteria

  • Specialized index (e.g. only "in-progress" projects)

A query page may use, or combine, multiple information sources (e.g. sets of instance pages, system resources).

Slide 21: Design Your Queries

Ask yourself:

  • Which fields should be represented in the report?

  • Which fields might someone want to search on?

  • Which fields do not need to be presented on this page?

  • Can you use menus? Do you need "free-form" text searching?

  • Is any data be derived (e.g. calculated from multiple fields)?

Slide 22: Ancillary Pages

  • Ancillary pages (optional)

Applications may include optional ancillary pages, such as:

  • Shared content, included into all instance pages

  • Definition of menu or checkbox values for Wiki forms

  • Common code (e.g. "button builders")

  • Help pages and documentation

Slide 23: Design Any Ancillary Pages

Ask yourself:

  • Can I use shared content?

  • Should any of the values in the Wiki Form be defined in separate pages

  • What help pages and documentation do I need?

  • What have I missed?

Slide 24: 10 Steps to an Application

  1. Analyze the Problem
  2. Design the Application
  3. Create a Wiki Form and define fields
  4. Enable the form (set the variable WEBFORMS in WebPreferences)
  5. Create a Template Topic
  6. Add the Wiki Form to the Template topic
  7. Create an initialization form (HTML Form) with necessary fields
  8. Create the first instance page in your application
  9. Create query pages for listing items
  10. Review and refine

Slide 25: Create a Wiki Form

  • Topic name should include / end with the word Form

  • Field names are WikiWords
    • Can be "spaced out"

  • Field Types
    • text, textarea, date, select (menu), checkbox, radio button...

  • Attributes (optional)
    • hidden on view
    • mandatory

screenshot

See: WikiTutAppE1Form

Slide 26: Wiki Form: Field Values

Field values for menus, checkboxes, and radio buttons can be stored in separate pages (which may be dynamically generated).

screenshot screenshot

Slide 27: 10 Steps to an Application

  1. Analyze the Problem
  2. Design the Application
  3. Create a Wiki Form and define fields
  4. Enable the form (set the variable WEBFORMS in WebPreferences)
  5. Create a Template Topic
  6. Add the Wiki Form to the Template topic
  7. Create an initialization form (HTML Form) with necessary fields
  8. Create the first instance page in your application
  9. Create query pages for listing items
  10. Review and refine

Slide 28: Create the Template Topic

  • Topic name should include / end with the word Template

  • Base content for every instance page

  • Content may be derived from variables or form values

  • May include shared (read-only) content

Note: I make a distinction between templates that can be used without an initialization process and templates that require an initialization process. By convention, I use TemplateStrict for naming templates that require data to be passed in from an initialization process.

See: WikiTutAppE1TemplateStrict

Slide 29: Template: FORMFIELD Variable

The FORMFIELD variable is extremely useful in template topics. FORMFIELD provides access to the metadata stored in a form.

  • %FORMFIELD{"fieldname"}%

  • Form may be in this topic or another topic

  • Optional parameters
    • topic=... - Name of the topic that contains the form data
    • default="..." - Text shown if no value is defined for the field


%FORMFIELD{"ProjectName"}%

See: WikiVariables

Slide 30: Add a Wiki Form to a Template

1. "Enable" the form for the Web

Update WEBFORMS variable in WebPreferences topic.

   * Set WEBFORMS = TeamContactForm, ProjectDetailForm

2. Add the Form to the Template Topic

Use the "Add Form" button in Edit mode to add the form to the template. The form will be copied along with the template contents when you create a new instance page.

Note: Forms are "added" to topics. Files (images, Word docs, etc.) are "attached".

Slide 31: 10 Steps to an Application

  1. Analyze the Problem
  2. Design the Application
  3. Create a Wiki Form and define fields
  4. Enable the form (set the variable WEBFORMS in WebPreferences)
  5. Create a Template Topic
  6. Add the Wiki Form to the Template topic
  7. Create an initialization form (HTML Form) with necessary fields
  8. Create the first instance page in your application
  9. Create query pages for listing items
  10. Review and refine

Slide 32: Create an Initialization Page

  • HTML form <form... action=... >

  • Provides flexibility
    • instructions
    • ordering of fields
    • human-convenient field names

  • Fields (mostly) match Wiki Form
    • May omit/add some fields
    • Can provide default values

  • Submit creates new Instance page
screenshot

Slide 33: HTML Form - Features

  • Parameterized
  • Programmatic
  • Consistent
    • Template + Form + Data
  • Error Checking
  • Automatic naming

See: WikiTutAppE1Create

Slide 34: HTML Form

A minimal HTML Form that will create a new instance page:

screenshot

Slide 35: HTML Form - Action

<form action="%SCRIPTURLPATH%/save%SCRIPTSUFFIX%/%WEB%/"> 

The HTML Form runs a Wiki "script". This is usually one of:

  • edit - create the new page and open it in Edit mode

  • save - create the new page and save it (show in View mode)

Slide 36: HTML Form - URL Parameters

The HTML Form sends several URL parameters to Wiki, telling it how to create the new instance page:

name value required?
topic the name of the topic (instance page) to create required
templatetopic the name of the template topic to copy from required
topicparent the topic to use as parent for the new instance page recommended
onlynewtopic on recommended
onlywikiname on optional

onlynewtopic ensures unique names for new instance pages.
onlywikiname ensures that instance page names are WikiWords.

Slide 37: HTML Form - XXXXXXXXXX

<input type="hidden" value="TeamContactPageXXXXXXXXXX" name="topic" />

The string XXXXXXXXXX will be replaced by a unique sequence number when the new topic is created (saved).

Slide 38: HTML Form

Sample Code (a more complex form):

<form action="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%WEB%/"> 
<input type="hidden" value="TeamContactPageXXXXXXXXXX" name="topic" />
<input type="hidden" value="form" name="action">
<input type="hidden" value="TeamContactTemplateStrict" name="templatetopic" />
<input type="hidden" value="TeamDirectory" name="topicparent" />

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

 <tr>
 <th align="right">
   <span title="Full Name of this Person">Person Name</span>
 </th>
 <td align="left">
  <input type="text" name="PersonName"  size="60"  />   <br />
  Team Member's Full Name
 </td>
 </tr>

 <tr>
 <th align="right">
   <span title="Role / Responsibilities in team">Role, Responsibility</span>
 </th>
 <td align="left">
   <textarea name="RoleResponsibility" rows=2 cols=40 ></textarea>  <br />
   Role / Responsibilities in team (e.g. Engineer, DBA, Manager...) 
 </td>
 </tr>

<tr>
<th align="right">
  <span title="Date Joined">Date Joined</span>
</th>
<td align="left">
  <input type="text" name="DateJoined"  size="20" id="datecell" class="twikiEditFormTextField" /><input type="image" name="calendar" src="/pub/%SYSTEMWEB%/JSCalendarContrib/img.gif" align=MIDDLE alt="Calendar" onclick="return showCalendar('datecell','%d %b %Y')" />  <br />
  Date of joining team. <br /><i>Use a 3-letter month abbreviation!</i>
</td></tr>

<tr>
 <th bgcolor="#99CCCC" align="right">
   <span title="Where are you primarily located?">Org Location</span>
 </th>
 <td align="left">
   <select size="1" name="OrgLocation">
     <option selected="selected">Select one...</option>
     <option>Bangalore</option>
     <option>Dallas</option>
     <option>San Diego</option>
     <option>San Francisco</option>
     <option>Santa Monica</option>
     <option>Sunnyvale</option>
     <option>Other</option>
   </select>
   <br />
    Where are you primarily located?
</td>
 </tr>

<tr><td>&nbsp;</td>
<td align="center">
  <input type="submit" value="Add Person" />
</td></tr>

</table>

</div>
</form>


Note (Advanced)*: name=action value=form is used (optionally) when the new page will be edited. This presents only the form for editing, not the rest of the page.

Slide 39: Aack!

It's not as bad as it looks. You can copy most of the HTML form code from the Wiki form.

  1. Edit the template page, with Wiki form added, in the Wiki editor.
  2. "View Source" in your Browser.
  3. Locate, select, and copy the form code.
  4. Paste the form code into your initialization page.
  5. Save and review.
  6. Edit to taste.

See: WikiTutAppHowTo

Slide 40: 10 Steps to an Application

  1. Analyze the Problem
  2. Design the Application
  3. Create a Wiki Form and define fields
  4. Enable the form (set the variable WEBFORMS in WebPreferences)
  5. Create a Template Topic
  6. Add the Wiki Form to the Template topic
  7. Create an initialization form (HTML Form) with necessary fields
  8. Create the first instance page in your application
  9. Create query pages for listing items
  10. Review and refine

Slide 41: Create the First Instance Page

When the submit button is clicked on the Initialization form:

  • The template is copied

  • The Wiki form is copied

  • Data is added to the Wiki form

  • A new page instance is created

Slide 42: Instance Pages

An instance page:

  • May contain only a form

  • More likely to include content that references form values

  • May contain additional content

  • May be editable

  • or may be composed entirely of shared (read-only) content

  • rendered:
    rendered screenshot
  • raw view:
    raw view - screenshot
  • form:
    form screenshot

Slide 43: 10 Steps to an Application

  1. Analyze the Problem
  2. Design the Application
  3. Create a Wiki Form and define fields
  4. Enable the form (set the variable WEBFORMS in WebPreferences)
  5. Create a Template Topic
  6. Add the Wiki Form to the Template topic
  7. Create an initialization form (HTML Form) with necessary fields
  8. Create the first instance page in your application
  9. Create query pages for listing items
  10. Review and refine

Slide 44: Create A Query Page

Query pages perform dynamic indexing and search.

They may match on:

  • topic name

  • form name (all pages with this form)

  • form contents (all pages with this field value)

  • ...

screenshot

See: WikiTutAppE1Search

Slide 45: 10 Steps to an Application

  1. Analyze the Problem
  2. Design the Application
  3. Create a Wiki Form and define fields
  4. Enable the form (set the variable WEBFORMS in WebPreferences)
  5. Create a Template Topic
  6. Add the Wiki Form to the Template topic
  7. Create an initialization form (HTML Form) with necessary fields
  8. Create the first instance page in your application
  9. Create query pages for listing items
  10. Review and refine

Slide 46: Review and Refine

Review

  • Template and Instance pages
    • Do the have the fields you expected?
    • Do they look the way you think they should look?

  • Wiki Form
    • Does it have the appropriate fields?

  • Initiation Form
    • Does it have the appropriate fields?
    • Does it have adequate documentation and instructions?

  • Query page
    • Do the instance pages you have created show up?
    • What fields are missing?

Ask others to review and test.

What can be refined and improved?

Slide 47: Appendix: Date Picker Code

If there is a date picker (calendar field) in your form, add the following code at the end of the Initialization page:

<!--JSCALENDAR-->
<style type='text/css' media='all'>
  @import url('/pub/%SYSTEMWEB%/JSCalendarContrib/calendar-blue.css');
  .calendar {z-index:2000;}
</style>
<script type='text/javascript' src='/pub/%SYSTEMWEB%/JSCalendarContrib/calendar.js'></script>
<script type='text/javascript' src='/pub/%SYSTEMWEB%/JSCalendarContrib/lang/calendar-en.js'></script>
<script type='text/javascript' src='/pub/%SYSTEMWEB%/JSCalendarContrib/twiki.js'></script>

Slide 48: Appendix: INCLUDINGTOPIC Variable

The INCLUDINGTOPIC variable provides the name of the topic that includes the current topic. (If there is no %INCLUDE%, this is identical to %TOPIC%.)

If you include shared content into your template and instance pages, you'll need to use %INCLUDINGTOPIC%

  • when referencing form values
  • when referencing the Topic name of the current instance page

%FORMFIELD{"ProjectName" topic="%INCLUDINGTOPIC%"}%

%CALC{$IF($EXISTS(%WEB%.%INCLUDINGTOPIC%_KickoffForm),...}%

Slide 49: Appendix: TOPICTITLE Variable

Customize the page title to something more human-readable than a WikiWord name by setting the TOPICTITLE variable.

TeamDirectoryPage1 is clearly a team directory page, but whose?

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

screenshot (before) screenshot (after)
Default TOPICTITLE set

Slide 50: Appendix: Shared Content

Your application may define static text that is common to all instance pages of the same type. If users will never modify this text, consider including it (using %INCLUDE%) from a shared page.

Then, if the common content needs to change, you can edit a single location. All instance pages will automatically include the update!

%INCLUDE{"ProjectDetailPageFormat" section="shared"}%

Slide 51: Appendix: Wiki Application Tutorial

Wiki Application Tutorial

Ancillary pages

Sample Project Page

Slide 52: References

The following are part of the Wiki distribution:

Slide 53: Getting Help

Talk to your co-workers.

It's always OK to ask for help and share ideas.

Topic attachments
I Attachment Action Size Date Who Comment
DataEntry.jpgjpg DataEntry.jpg manage 94 K 27 Jan 2009 - 07:41 VickiBrown  
Field_values.jpgjpg Field_values.jpg manage 139 K 27 Jan 2009 - 07:41 VickiBrown  
Form_def.jpgjpg Form_def.jpg manage 108 K 27 Jan 2009 - 07:41 VickiBrown  
Form_def_part.jpgjpg Form_def_part.jpg manage 82 K 27 Jan 2009 - 07:41 VickiBrown  
Formcode_HTML.jpgjpg Formcode_HTML.jpg manage 40 K 27 Jan 2009 - 07:41 VickiBrown  
PageTitle1.jpgjpg PageTitle1.jpg manage 114 K 27 Jan 2009 - 07:41 VickiBrown  
PageTitle2.jpgjpg PageTitle2.jpg manage 115 K 27 Jan 2009 - 07:41 VickiBrown  
Query.jpgjpg Query.jpg manage 187 K 27 Jan 2009 - 07:41 VickiBrown  
TeamContactPage.jpgjpg TeamContactPage.jpg manage 120 K 27 Jan 2009 - 07:41 VickiBrown  
TeamContactPage_form.jpgjpg TeamContactPage_form.jpg manage 201 K 27 Jan 2009 - 07:41 VickiBrown  
TeamContactPage_rawview.jpgjpg TeamContactPage_rawview.jpg manage 45 K 27 Jan 2009 - 07:41 VickiBrown  
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