create new tag
, view all tags


I give up, I'm totally confused about forms. I've blindly copied some examples, changed them and made them work, but have no idea why. So far I've read the main documentation TWikiForms, and searched this site for other interesting forms information such as HowToDoBookReviews, but I still can't follow what's going on and I'm typing lots of characters that I don't understand and can't see being used. What irritates me most is that the damn things always work fine so I can't present a problem to be solved smile

I'm wondering things like, why does it need two topics to make a form? And why does one example use only one topic and different syntax? What exactly does each column mean, e.g. what is "size" for and what can it be? Do I have to understand Category Tables first, or, are Category Tables something simpler that I could use?

OK, here's my real question. Is there any more verbose documentation somewhere that I've missed?

If not I guess I'll just sweat it out and write something up myself when I've worked through this mental block.

  • TWiki version: Dec 2001
  • Web server: Apache
  • Server OS: FreeBSD
  • Web browser: Lynx, Netscape
  • Client OS: FreeBSD

-- SueBlake - 22 Jul 2002


TWikiForms is the official doc for the TWiki forms. Let us know in more details what you do not understand, we constantly try to improve the docs.

Addressing some of your questions:

  • Q: Why does it need two topics to make a form?
    • A: The first one is the Form Template topic, it defines how the actual form looks like (has Form Fields like input fields, radio buttons etc). The second one is the Template Topic. A Template Topic is used as the template when you create a new topic. A topic can have optionally a form attached. This is why you need two topics to define a form, the Form Template topic and the Template Topic.
  • Q: What exactly does each column mean, e.g. what is "size" for and what can it be?
    • A: That depends on the type of the Form Fields. For example, the size column for a select type defines the number of options you can see, a size of 1 is a drop down box, a size of 3 means that you can see three options. The types of the Form Fields correspond to HTML input fields.
  • Q: Do I have to understand Category Tables first?
    • A: No, this is only of interest for people who used the older Category Table system
  • Q: OK, here's my real question. Is there any more verbose documentation somewhere that I've missed?

Hope this helps.

-- PeterThoeny - 23 Jul 2002

I struggled with this myself because it wasn't immediately obvious to me how the TWikiForms could actually be "used". For example, to create a new topic with form data filled in requires that you hand construct a html form to do this. A shortcut is to create the template topic (with the twiki form attached) then get the html source of the edit page (with your browser's view source function) and cut the html form from there (it will need some mods to make it do what you want, but at least it will have the right fields defined).

The docs could do with some description of this and a bit of a mention of how this actually relates to html forms (not every twiki user is a web developer - maybe a link to the w3c html forms doco or is that too techie?). A mention of or a link to how to search for form data and/or get form data using formatted search would also not go astray.

-- DarrylGreen - 24 Jul 2002

Good points, docs should be improved, see Codev.TWikiFormsDocWithExamples

-- PeterThoeny - 24 Jul 2002

I'm back to jot down a few points that could do with clarifying, or that I think I've clarified (but may not have). If anyone wants to make a start on Codev.TWikiFormsDocWithExamples but doesn't know what to write about, you might find some ideas here.

It would be helpful if the first few words of the forms documentation gave a definition of what TwikiForms are, and then a brief "Forms can be used for this, that, or the other thing, but they are commonly used for...". That would help a lot to orient the brain. Orientation concepts first, then examples of purpose, then howto, then howto examples.

So... a "select" type with size 1 gives a drop down box, and a larger number gives a list box with that number of items visible, and presents a scroll bar if there are more items in the list. These are two very different styles of presentation, so it would be handy to have that spelled out.

Apparently the size for radio and checkbox types means how many items are listed horizontally per line. You can get a nice vertical radio list by using 1, for example.

Text is simply the number of characters wide, but for textarea I think it is possible to state the size in width and height. Which way round and what's the syntax? What happens if you just put one figure like "42" for the size of textarea?

In TWiki/TWikiForms I'm still stuck on the two different ways of using forms that the doc tries to distinguish. I can't see the difference between "Defining a Form in One Topic" and "Defining a Form with Multiple Topics". I read both sections, and hear the same words in my head each time. In the example, under Name there are names like "Know.TopicClassification" but I'm not sure whether the web name should really be there or not, because I don't see it present in other examples.

I make a form and a form template to match its fields, following what I can of the docs and the Know web examples, and it works fine. Then just for kicks I edit the template metadata, delete a few fields, add some, change some, then create edit and display some more pages. It works exactly the same as before I changed the template! So why do we bother putting metadata in the WebEditTemplate?? And is there any point in faithfully updating it every time the form is amended??

When there was a choice of values, I could set and change the default value in my experiments. Then sometimes it wouldn't work. It's likely to be something I did wrong (it was just rough work) but here again I'm inclined to refer to the docs to see if there's a gotcha I should know about. If there were more docs and no gotcha mentioned, I'd check my work without hesitation smile Later... Hey, maybe I'm confusing myself here. There seems to be two ways to set a default: either use value="foo" in WebEditTemplate, or put the default item first if there are multiple values. Perhaps one overrides the other, or perhaps they are mutually exclusive.

If you create a new topic with a form (e.g. in the example Know web), and then radically alter the form:

  • new topics will use the new form fields, whether they are mentioned in the WebEditTemplate or not
  • old topics will display with the fields and values they had before, even if they have become extinct as far as the WebForm is concerned
  • if an old topic is edited, it will lose any extinct fields, and gain a few new ones

I guess that's pretty obvious after you discover it, but it'd be kinda nice to be able to read all about it up front.

Is it possible to mark multiple selections in a drop-down box? I have one field that has more than thirty options, and fairly rarely two or three choices will be relevant. The choice seems to be either to use two or three spare list boxes, or to fill a couple of screens with checkboxes. What I'd really like to be able to do is to look up the docco and go "oh, ok, I won't waste time trying that, I'll think of another way" if it can't be done.

What puts the [Change] button on top of forms being edited, and can it be made to say [ChangeFormType]? I had a nervous user thinking of it as a "save" button. Actually, I'd rather be reading about how all of it fits together than asking a specific question. Any takers?

I don't expect anyone to wade through and address all of this, but I hope it gives you an idea of how brains can go astray given any chance. When you understand something well it can be difficult to see where others are becoming entangled in the documentation, unless someone like me is prepared to plead stupidity on the world stage. I'd much prefer to remain silent and use TWiki without forms, it's pretty good already, but if I did that others would too.

As for Daryl's comments above, I haven't got a clue what he's talking about and I don't think I want to go there just yet, but I'm awful glad not to be alone here smile

-- SueBlake - 01 Aug 2002

I'm refactoring the comments I made here yesterday. (For reference, my original comments are available in r1.6 of this page.):

For me, talking about forms is the wrong thing to do, it just confuses me. It is simpler for me to think about data. TWiki can deal with 4 types of (text) data. (Note that I am ignoring pictures and so forth for the time being.)

Those 4 types of text (data) are:

  • Visible free format text
  • Hidden free format text
  • Visible structured text/data
  • Hidden structured text/data

Translating those terms into the language of TWiki:

  • Visible free format text is just the normal stuff that you type into TWiki, add TWiki markup, and see when you view the page. It is the only type of text most other wikis support. (IIRC)

  • Hidden free format text is what is called metadata on TWiki. (I'd write more, but I can't easily recite an example of how meta data is created and used -- I'll try to come back here later, but, in a way, it's beside the immediate point.)

  • Structured text/data: When I say structured data, I'm thinking about fields that have a limited set of possible values. For example, on this page, a variable called "SupportStatus" is used. It has the following possible values:

So, for me, SupportStatus is a piece of structured data. (I have suggested it be called a "data field", the current agreed upon nomenclature is "form field".)

On TWiki, all structured data is stored as meta (hidden) data, but it can be made visible or used without being made visible (I think -- I'll have to try to think of an example of metadata that is used but not normally displayed -- maybe the TWiki access "permissions", if hidden, are almost an example).

Structured data is "structured" by creating a form for data entry. That form is normally not visible, but is visible while editing a page. It allows you, on the editing page, to choose the values you want for the structured variables (form fields, or for me, data fields) that you've defined. (This is one of the two forms that get talked about when TWiki talks about forms.)

Aside: I will need to clarify a little more re "choose the values you want for the structured variables" -- on the edit page you choose the current value for a variable -- when you create the form for the edit page you define the possible values that can be chosen from on the edit page.

Anyway, continuing:

  • Visible structured data: The most common way of displaying structured data on TWiki. An example is the table at the bottom of this page (in view mode) labeled "WebForm". The form that creates this table is the second of the two forms that get talked about when TWiki talks about forms.

  • Hidden structured data: Data created in a form does not necessarily have to be displayed in a form (or even displayed at all, I think). On the "permanent" WikiLearn site, I would like to display "Wikilearn.PageStatus" data as a bulleted list instead of a table.

And, in fact, I may display the data at different places on a page, instead of all at the bottom. I would use the proposed %FORMFIELD{"FieldName"}% function. (See Codev.FormattedTWikiFormDataInTopicText (and, to a lesser extent, Codev.EditControlsBasedOnFormDefinition.)

And, maybe I won't display all of it on the page where it is created (the page that displays the form for editing when in edit mode). In that case, I think it would be appropriate to call it hidden structured data.

Ok, with all of this said, what are forms?

Forms are just:

  1. The means for creating structured data in TWiki
  2. The normal / most common means for displaying structured data in TWiki

And, the one type of form (displayed in edit mode) is used for the first purpose, and the other type of form (displayed in view mode) is used for the second purpose.

When I learn a little more, I'll add something about how / where these two forms are created, or, someone else who already knows can do that here, or give me some hints.

The following is some leftover material from the refactoring that might be worth incorporating above. Let me know if you see something that is worth saving, otherwise I'll probably delete this stuff in a few days:

(TWiki) Data Type Free Format/Structured Visible/Hidden
Traditional Wiki Free Format Visible
Metadata?? Free Format Hidden
"Forms" Structured Visible
Note 1 Structured Hidden

Note 1: I think you could use the one type of form to create hidden structured data, but not necessarily display it. It would be hidden metadata, that could be displayed by other means if desired. And people have asked for that capability -- it's one use for the proposed function . See FormattedTWikiFormDataInTopicText (and, to a lesser extent, EditControlsBasedOnFormDefinition).

-- RandyKramer - 03 Aug 2002

I've been yet another person trying to get my head around forms. Now that I've basically go them working I thought I should add some comments about where I had problems in understanding which may be of help to those writing future versions of the doco. I hope this is the best place to put this.

  • The stuff on categories should be moved to a link about ChangingCategoriesToForms, or maybe as part of upgrading from previous versions. If you're a newbie learning this stuff you don't need to be confused by having to realise that this doens't apply to you. At the very least put it at the bottom of the Topic.
  • The definition of the size field is very poorly documented. It's simple to understand for things like Text boxes but what does it mean for checkboxes? (It means how many check boxes to display on a row) and select types (If it has a value of 1 then you get a drop down list, if it's greater than 1 then you get a scrollable list).
  • Enabling Forms by Web is done by setting the WEBFORMS variable on the WebPreferences page to the list the webforms you want to use. I know it seems like a simple thing, but my initial reading was that you set this variable to "enabled". That's not right, Webforms are enabled by virtue of this variable being non-null.
  • I concur with the comments about the "Change" button being too obvious for it's frequency of use.
  • The Single Topic / Multiple Topic thing: This is really a question of do you put you selection options on the same page or a different page to your form. If you have lists of things you want people to select from, a separate form is the way to go. To help newbies trying to get started, I'd leave the "form in one topic" option to the end as a quick shortcut for experts.
  • Another comment for people getting started. The "Add Form" button you see people referring to only appears when you have added your form to the WEBFORM line of the WebPreferences (thus enabling webforms). It has nothing to do with the attach link at the bottom of a page. Attaching a file to a Topic and adding a form to a Topic are two different things entirely. I can't remember if I just thought it or it actually exists somewhere, but documentation should avoid using "attach a form to the template". The phrase should be "add a form to a template". I know it's a small thing, but I spent a bit of time searching for a form selection thing on the attach page.

  • Maybe a FormsHowTo would be helpful:
    1. Some terminology translations:
      • A form is to a web as a table is to a database
      • You put your "create table" into a WebForm called whatever you like. It also doesn't need to be in the "Know" web, it can be in your own web.
    2. Determine what data you want to collect.
      This what you want to get stored in the META data of Topics you create.
    3. Create a Topic to put form data in. Follow the instructions on TWiki.TWikiForms#Defining_a_Form_Template to create your form table. The values field is normally blank. (I'm writing this in the context of my comments above about the single topic option being a shortcut). For list elements, make each field in the name column a WikiWord to a Topic containing a table that lists the possible values for that field.
    4. Determine the values For fields types of your form that use a list: select, checkbox, radio. The list of possibilities goes on another page (this is what is meant by the "Multiple Topics" option).
    5. Create a Topic for each list field with a table of all possible options. These tables have three columns, the middle one is always "option".
    6. Once you have create your Webform Topic with it's table defining the Webform, and all your Topics, each with a Table for your list elements, you are ready to connect it into your web.
    7. Edit the WebPreferences page and add your web form topic name to the line that has "Set WEBFORMS =". This enables your web form so Twiki knows it exists. Everytime you now edit a topic you will have an "Add Form" on at the bottom of your page.
    8. Edit or create the "WebTopicEditTemplate". This topic is what you get as the default when you create a topic. By adding the form to this topic it will come up on each new topic you create.

I hope others will find these comments helpful and the experts will fix any errors in this.

Finally, Randy, leave your little table above in. That I found helpful.

-- AndrewSteele - 07 Sep 2002

"Finally, Randy, leave your little table above in. That I found helpful." -- Good, thanks! I've made one slight change to the table -- I've replaced "??" with "(TWiki) Data Type" -- does it help or hurt?

PS: Thank you for the comments above -- they touch on a lot of good points that should be covered in the documentation. I hope somebody will modify the documentation appropriately. (At some point in time I might come back to this page and try to carry my explanation further, touching on more of these points.)

Just for the record, I've only set up a TWiki using the categories approach -- I haven't set up one of the newer ones with forms, so haven't worked this all the way through for myself yet. Maybe sometime in the next months, then I might be in a position to revise the documentation.

-- RandyKramer - 07 Sep 2002

I've done some minor editing on my notes above, mainly to fix typos and such. I was in a bit of a hurry when I first wrote it all down but I didn't want to lose the stuff whilst it was still fresh in my mind.

Randy, the "(TWiki) Data Type" is helpful. The other bit that would be good to change the "Note 1" reference, which I presume is a historical refernce.

-- AndrewSteele - 07 Sep 2002

I restored the original note 1 -- it could probably use some rework, but I need to think about it.

-- RandyKramer - 09 Sep 2002

I have a question on making a form with multiple column values. For ex.

Name type size values values
task1 select 1 pass,fail yes, no
| task2 ..etc

I can only get a 1 column of selectable values in my form. Is there a way to have more than 1 column of inputs per row? Thanks.

-- JasonPark -06 Nov 2002

It's now several years after this topic was last modified (We're now on 2005), and yet, this was still the only topic which helped me out. Most specifically, the excellent HOWTO by AndrewSteele provides data found nowhere else. Just nowhere! I've combed through the whole site, and it was only here I could finally figure out the missing link:

"Edit or create the "WebTopicEditTemplate". This topic is what you get as the default when you create a topic. *By adding the form to this topic it will come up on each new topic you create.*"


I want to add this HOWTO to the official docs now.

-- ErezZukerman - 01 Apr 2005

Erez - feel free to add it.

-- MartinCleaver - 02 Apr 2005


I am frustrated by the docmentation on forms as well. There indeed should be examples. Spell out, step-by-step, what needs to done in order to create a form, including how to add to Web Preferences. Do I add Set WEBFORMS = Name of Form to my Web Preferences page? I know it may be obvious to many of you out there, but in my experience (as a technical writer) instructions should never assume knowledge. The TWikiForms page directs me to my Main Web Preference page, yet I find little to no help there:

  • Comma separated list of forms that can be attached to topics in this web. See TWikiForms for more information.

What does this mean exactly??

-- KellyRiley - 2009-06-19

Yes, assuming you created an "ExpenseReportForm" in the "Finance" web, you would enter this to the "WebPreferences" of the "Finance" web:

      * Set WEBFORMS = ExpenseReportForm

BTW, it is better to open a new support question.

TWiki is open source software. We invite you to get involved. Please feel free to update the docs in teh TWiki web on twiki.org, especially the ones you find not easy to understand such as TWiki.TWikiForms.

-- PeterThoeny - 2009-06-19

Edit | Attach | Watch | Print version | History: r16 < r15 < r14 < r13 < r12 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r16 - 2009-06-19 - PeterThoeny
  • 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-2018 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.