Creating and Populating Forms

This document outlines the steps necessary to build a dynamic form in Tcl code.

Important Note: The ad_form function has been written to be a more consistent, easier way to create and manage dynamic forms. Behind the scenes it uses the templating system's form builder, but it hides much of its complexity. You should definitely look at it and at the pages that use it in the survey package.

Create a form

Use the form create command to initialize a form:

form create add_user

See the form API for optional parameters to this command.

Add elements

Once the form is created, use the element create command to add elements to it:

element create add_user first_name -datatype text \ 
                                   -label "First Name" \
                                   -html { size 30 }

In auto-generated forms, elements appear in the order they were created. See the element API for optional parameters to this command.

Set values

Self-validating forms should check whether a request or submission is currently being processed. If a request is being processed, then form elements may need to be initialized with their appropriate values.

if { [template::form is_request add_user] } {

  set db [ns_db gethandle]

  set query "select ad_template_sample_users_seq.nextval from dual"
  template::query user_id onevalue $query -db $db

  ns_db releasehandle $db

  template::element set_properties add_user user_id -value $user_id
}

This may also be done using the value option to element create. In this case the value is set separately to avoid the additional database query during a submission.