create new tag
, view all tags

How to Create a TWiki Application

2010-09-10 - 00:18:42 by PeterThoeny in Applications
TWiki applications are a wonderful part of TWiki. They help automate workflows you have at the workplace. I am writing this how-to blog because not many people know about this very useful feature TWiki offers as a structured wiki. TWiki has a built-in database that can be used to write custom web applications. These are wiki applications that run in TWiki!

Here are some ideas on what is possible:

  • Workflow example Need to automate status reporting for your teams? Write a status reporting application with roll-up.
  • Need to keep track of your consulting hours for billing? Write an time tracker application.
  • Need to organize your server infrastructure? Write a data center inventory application.
  • Need to organize events of your social club? Write an event tracker application.
  • Need to manage expense reports in your organization? Write an expense report application.
  • Need to keep track of sales opportunities? Build a sales pipeline tracker application.
  • Need a shared contact list? Copy and customize the contact database described further below in this blog.

It is relatively easy to create a TWiki application. You do not need to ask IT to create a custom web application for you in Java, PHP or another programming language. Ask someone in your team who has some technical skills to write it for you using the TWiki markup language. Or, start writing a TWiki application yourself!

Screenshot of contact database This blog describes how to create a TWiki application using a contact database as an example. I invite you to replicate this application in your own TWiki as an exercise. It will take some time to grasp the idea when you do it the first time; it will be much easier the next time.

A typical TWiki forms based application consists of the following pages:

  • Application home page, typically containing links to other application pages. It may contain also a report showing data records.
  • Form definition page, defining the fields of a record.
  • Template page, used as a template for new data records. It is essentially a TWiki page with a form attached to it.
  • Header page: Optional page included in each record page to summarize the record.
  • Page to create new records.
  • Report page(s).

Use the following steps to create a contact database application. The links point to ContactDB application pages located in the Sandbox web here on twiki.org.

  1. Create application homepage ContactDB:
    • This is the main application page.
    • For now, add WikiWord links ContactForm, ContactTemplate, ContactHeader, NewContact to prepare for the next steps.
  2. Create form definition page ContactForm:
    • This is the form definition page, defining the fields with name, type, size, initial value.
    • Example:
      Name: Type: Size Values: Tooltip message:
      Salutation select 1 , Mr., Ms., Mrs., Miss, Dr. Pick salutation
      Name text 40   First name and Last name of person
    • Book Docs: TWikiForms
  3. Create template page ContactTemplate:
    • This is the template page used when new contact pages are created.
    • Add text you want to have on every contact page, such as help text or comment box.
    • Book Docs: TWikiTemplates
  4. Add the ContactForm created in the previous step to the template page:
    • Add ContactForm to the WEBFORMS setting in WebPreferences.
      TIP From TWiki-5.2 on this is no longer needed.
    • Edit ContactTemplate, click on the "Add form" button, select ContactForm to add that form to the template page.
      TIP From TWiki-5.2 on, the add form feature is accessible the "More topic actions" screen.
  5. Create header page ContactHeader: (optional step)
    • Create the page and add a summary of the contact record you want to have shown at the top of each contact page. The header is a separate page so that you can change the summary later in one location and have it take effect on all contact pages.
    • Edit the template page and include the header page at the top:
    • Book Docs: VarFORMFIELD, VarINCLUDE
  6. Create page to create new records, NewContact:
    • This page has an HTML form to create new contacts.
    • The HTML form action points to TWiki's save script:
      <form name="new" action="%SCRIPTURLPATH{save}%/%WEB%/" method="post">
    • The save script uses the form input field values to populate the TWiki form fields of the new contact.
    • Use HTML input fields to prompt for form fields. Match the name of the HTML input fields with the TWiki form field. For example, to prompt for the "Phone" field use this HTML:
      <input type="text" name="Phone" value="" size="20" />
      • UPDATED 2013-10: From TWiki-6.0 on you can use TML instead of HTML: %EDITFORMFIELD{ "Phone" form="ContactForm" }%
    • Book Docs: TWikiTemplates, TWikiScripts, VarEDITFORMFIELD
  7. Add a report to ContactDB page:
    • Add a SQL-like query to list all contacts.
    • Example:
      | *Name* | *Phone* | *Email* |
      %SEARCH{ "form.name='ContactForm'" type="query" format="| $topic | $formfield(Phone) | $formfield(Email) |" }%
    • Book Docs: VarSEARCH, FormattedSearch, QuerySearch

This contact database application can be enhanced further. For example, you could add a filter to the report to narrow down on contacts. You can use this TWiki forms based application as the base for your own applications. Be creative, the sky is the limit!

There are other ways to build applications and create content in a structured way. For example, you can use the EditTablePlugin to embed spreadsheets in TWiki pages. TWiki.org's Sandbox web lists a number of sample applications. The presentation Structured Wikis at Work - Enterprise 2.0 in Action gives an overview on the application capability of TWiki.

Let us know what kind of TWiki applications you have built or plan to build. Let us also know how you would like TWiki to be enhanced to make it easier to create TWiki forms based applications.

-- Peter Thoeny



Yesterday I gave a presentation to ACCU at Symantec in Mountain View, CA. I prepared the ContactDB application and created it during the presentation. Today I thought that it might help to expand on that by writing this blog post.

I am looking forward for your feedback.

-- Peter Thoeny - 2010-09-10

We have now an improved contact database, packaged as a TWiki application & ready to be used: ContactDbAddOn. Attached is a screenshot of the application homepage. There is now a filter row to search for entries. Useful if you have hundreds or thousands of entries.


-- Peter Thoeny - 2010-10-14

I will have a session on this topic tomorrow Saturday 11:15am at the Silicon Valley Code Camp, http://www.siliconvalley-codecamp.com/Sessions.aspx, room 4203. It is a free event for 3000 attendees, come and join us!

-- Peter Thoeny - 2011-10-08

when you say "Create page to create new records". Why is that? Could we use instead the form that is generated when we edit a page based on the Template ?

When we edit a page based on that template we are shown a nice form below the textbox of the content of the page. It seems to me that there should be a way to, instead of editing both: the content of the page, and the added form, just edit the form. No?


-- Daniel Ajoy - 2012-01-18

The actual page of the code-camp currently is: https://codecamp.pbworks.com/w/page/46626203/How%20to%20Create%20Web%20Apps%20in%20the%20Cloud%20Using%20TWiki%202011 . Though I was hoping for recorded video of the session.

-- Daniel Ajoy - 2012-01-18

It is certainly possible to create a page without a hand-crafted "create new records" page: Simply use the edit script and tell it to use the proper template, such as %SCRIPTURL{edit}%/%WEB%?topic=JimmyNeutron;templatetopic=ContactTemplate - this tells the edit script to create a topic called JimmyNeutron using template topic ContactTemplate. Nevertheless you lose convenience because you still need a form to specify the topic name. In some applications this is not needed, for example the TWikibug:WebHome bug tracker application uses topic names that are generated automatically. If you specify topic=ID-AUTOINC001 to the edit script, you will get consecutively numbered topics ID-001, ID-002, ID-003, etc.

-- Peter Thoeny - 2012-01-23

I'm looking forward for the second answer smile I want to reuse the page from creating new records for editing them. Is this possible?

-- Dirk Wilhelmy - 2012-04-10

Dirk, three options:

1. Use TWiki's edit feature to edit a form: Create a link that point to the edit script, telling it to edit only the form (not the page content). Example link: [[%SCRIPTURL{edit}%/%BASEWEB%/%BASETOPIC%?t=%SERVERTIME{$epoch}%;action=form][Edit contact]]

2. Create a ModifyContact page to modify an existing record: Copy content over from NewContact and modify as follows:

  • Add a new HTML form on top that shows a picklist of all existing contacts, name the select "contact". When you submit the form, the page will have a contact=JimmyNeutron parameter that will be used in the original form below.
  • In the HTML input fields, initialize the values based on the contact URL parameter. Example: <input type="text" name="JobTitle" value="%FORMFIELD{ "JobTitle" topic="%URLPARAM{ "contact" encode="entity" }%" }%" size="40" />
  • Change the topic name to a hidden field: <input type="hidden" name="topic" value="%URLPARAM{ "contact" encode="entity" }%" />
  • Disable the submit button in case the contact URL parameter is empty (consult Javascript docs). Condition: %IF{ " '%URLPARAM{ "contact" encode="entity" }%' = '' " then="..." else="..." }%

It is possible to combine the NewContact and ModifyContact into one page. Some conditional code is required using %IF{}%.

3. In-line editing: The most usable solution is to add the contact edit feature into the ContactHeader. The current header only shows a summary of the contact info in table format. It can be enhanced to toggle between view mode and edit mode, e.g. to change the content in-line. We have done that with the user profile pages; for inspiration study the Main.UserProfileHeader topic.

-- Peter Thoeny - 2012-04-10:

From TWiki-6.0 on it is easier to create custom forms to add or update records. You can use VarEDITFORMFIELD instead of hand-crafted HTML input fields. The input type is automatically taken care of based on the type defined in the TWiki form.

Example form to add a new record:

  %EDITFORMFIELD{ "form" type="start" action="save" method="post" }%
  | Title:    | %EDITFORMFIELD{ "Title"    form="ActionItemForm" }% |
  | Priority: | %EDITFORMFIELD{ "Priority" form="ActionItemForm" }% |
  | Status:   | %EDITFORMFIELD{ "Status"   form="ActionItemForm" }% |
  |  | %<nop>EDITFORMFIELD{ "form" type="submit" value="Add Action Item" }% |
  %EDITFORMFIELD{ "Updated" type="hidden" value="%SERVERTIME{$year-$mo-$day}%" }%
  %EDITFORMFIELD{ "topic" type="hidden" value="AID-AUTOINC0001" }%
  %EDITFORMFIELD{ "topicparent" type="hidden" value="ActionItems" }%
  %EDITFORMFIELD{ "templatetopic" type="hidden" value="ActionItemTemplate" }%
  %EDITFORMFIELD{ "onlynewtopic" type="hidden" value="on" }%
  %EDITFORMFIELD{ "onlywikiname" type="hidden" value="on" }%
  %EDITFORMFIELD{ "form" type="end" }%

Example to update an existing record: Custom form in an included header to update some values of the base topic

  %EDITFORMFIELD{ "form" type="start" action="save" topic="%BASETOPIC%" method="post" }%
  | Title:    | %EDITFORMFIELD{ "Title"    topic="%BASETOPIC%" }% |
  | Priority: | %EDITFORMFIELD{ "Priority" topic="%BASETOPIC%" }% |
  | Status:   | %EDITFORMFIELD{ "Status"   topic="%BASETOPIC%" }% |
  |  | %<nop>EDITFORMFIELD{ "form" type="submit" value="Update Action Item" }% |
  %EDITFORMFIELD{ "Updated" type="hidden" value="%SERVERTIME{$year-$mo-$day}%" }%
  %EDITFORMFIELD{ "form" type="end" }%

-- Peter Thoeny - 2013-10-09

It is useful to have both in the included header: Show the form content, and also a form to change the form content. Example:

Form Content

(Add table with %FORMFIELD{}% variables to show form content)

Edit Form

(Add table with %EDITFORMFIELD{}% variables to edit form content)

This can be done with the JQTABPANE of the JQueryPlugin. Raw text:

%JQTAB{"Form Content"}%
(Add table with %FORMFIELD{}% variables to show form content)
%JQTAB{"Edit Form"}%
(Add table with %EDITFORMFIELD{}% variables to edit form content)

-- Peter Thoeny - 2013-10-22


Edit | Attach | Watch | Print version | History: r12 < r11 < r10 < r9 < r8 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r12 - 2013-11-20 - PeterThoeny

Twitter Delicious Facebook Digg Google Bookmarks E-mail LinkedIn Reddit StumbleUpon    
  • Help
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2016 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.