Form Builder Vocabulary

From PKP Wiki
Revision as of 22:01, 8 February 2010 by Tylkkn (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

The form builder vocabulary (fbv) is a set of symbols, each of which is associated with a smarty function; these functions generate html form output based on the symbol and any extra information that might be coded with the symbol.

Definition

The following grammar presents the structural possibilities for forms using the fbv.

 START -> {fbvFormArea} F {/fbvFormArea}

 F -> {fbvFormSection} C {/fbvFormSection} F | *empty*

 C -> {fbvCustomElement} H {/fbvCustomElement} C | {fbvElement/} C | *empty*

 H -> *html* H | E H | *empty*

 E -> {fbvCheckbox/} | {fbvRadioButton/} | {fbvTextInput/} | {fbvTextarea/} | {fbvSelect/}

Overview

It's a combination of the styles and the structural elements that makes the fbv useful. The generated html markup is the product of an fbv-coded form and is shaped by both the structural elements and the parameters passed through these elements.

Styles

There are four categories of fbv style info and each category is associated with a list of possible values.

  • size (SMALL, MEDIUM, LARGE)
  • float (RIGHT, LEFT)
  • measure (1OF2, 3OF4, 2OF3)
  • layout (THREE_COLUMNS, TWO_COLUMNS, ONE_COLUMN)

The names of these categories are also the names of the parameters that are passed to the structural functions. For example, the following code could be used to create a row with three columns:

{fbvFormSection title="common.name" layout=$fbvStyles.layout.THREE_COLUMNS}...{/fbvFormSection}

Note

  • $fbvStyles is a variable that's available to all forms
  • for the actual list of values, see the 'fbvStyles' variable in the 'pkp/classes/form/Form.inc.php' file.

Structural Elements

The fbvFormArea wrapper marks the boundaries for a group of form sections. It's purpose is to reduce stylesheet conflicts by blocking in an area for elements of a form, while creating a clean separation between fbv generated content and the other template content that might appear before, after, or in between form areas.

The example below demonstrates the separation of template code and fbv output.

 <form>
    <span>Part 1</span>
    {fbvFormArea id="part1"}...{/fbvFormArea}
    <span>Part 2</span>
    {fbvFormArea id="part2"}...{/fbvFormArea}
 </form>

The fbvFormSection wrapper is used to create and control a section of the form that contains form elements. In most cases, fbvFormSection is actually a row of form elements; however, by floating the section to the left or right, the section takes up only half of the row space. In any case, the form section can be divided into columns with the 'layout' parameter (see 'Styles' section).

The fbvElement and fbvCustomElement wrappers are used to place form elements (e.g. text boxes and radio buttons) correctly in the render context.

The fbv symbols, like fbvTextInput, fbvTextarea, and fbvRadioButton, accept the regular html tag attributes - except in some cases where attributes like 'class' will be ignored.

- Note that the following:

{fbvElement type="text"}
{fbvElement type="checkbox"}

- is equivalent to:

{fbvCustomElement}
    {fbvTextInput ...}
{/fbvCustomElement}
{fbvCustomElement}
    {fbvCheckbox ...}
{/fbvCustomElement}

- and that fbvCustomElement allows you to enter custom code and use the other fbv symbols, like:

 {fbvCustomElement}
     <p>How to use...</p>
     {fbvCheckbox ...}
 {/fbvCustomElement}

Tutorials

Custom Element Example

The form language chooser is composed of several elements, none of which are associated with fbv wrappings, so using fbvCustomElement is a good choice.

- original template code:

 <tr valign="top">
    <td width="20%" class="label">{fieldLabel name="formLocale" key="form.formLanguage"}</td>
    <td width="80%" class="value">
       {url|assign:"userRegisterUrl" page="user" op="register" escape=false}
       {form_language_chooser form="register" url=$userRegisterUrl}
       <span>{translate key="form.formLanguage.description"}</span>
    </td>
 </tr>

- fbv template code:

 {fbvFormSection title="form.formLanguage" for="languageSelector"}
     {fbvCustomElement}
       {url|assign:"setupFormUrl" op="setup" path="1"}
       {form_language_chooser form="setupForm" url=$setupFormUrl}
       <span>{translate key="form.formLanguage.description"}</span>
     {/fbvCustomElement}
 {/fbvFormSection}

Note that the 'for' parameter for fbvFormSection corresponds to the selection box Id that is generated through the form_language_chooser function.

Grouping Similar Fields

Grouping similar fields, like the components of a user's name, in a row can improve usability and save space.

- original template code:

 <tr valign="top">
	<td class="label">{fieldLabel name="salutation" key="user.salutation"}</td>
	<td class="value"><input type="text" name="salutation" id="salutation" value="{$salutation|escape}" size="20" maxlength="40" class="textField" /></td>
 </tr>
 <tr valign="top">
	<td class="label">{fieldLabel name="firstName" required="true" key="user.firstName"}</td>
	<td class="value"><input type="text" id="firstName" name="firstName" value="{$firstName|escape}" size="20" maxlength="40" class="textField" /></td>
 </tr>
 <tr valign="top">
	<td class="label">{fieldLabel name="middleName" key="user.middleName"}</td>
	<td class="value"><input type="text" id="middleName" name="middleName" value="{$middleName|escape}" size="20" maxlength="40" class="textField" /></td>
 </tr>
 <tr valign="top">
	<td class="label">{fieldLabel name="lastName" required="true" key="user.lastName"}</td>
	<td class="value"><input type="text" id="lastName" name="lastName" value="{$lastName|escape}" size="20" maxlength="90" class="textField" /></td>
 </tr>

- fbv template code:

 {fbvFormSection title="common.name" required="true"}
     {fbvElement type="text" label="user.salutation" id="salutation" value=$salutation size=$fbvStyles.size.SMALL}
     {fbvElement type="text" label="user.firstName" id="firstName" value=$firstName required=1}
     {fbvElement type="text" label="user.middleName" id="middleName" value=$middleName}
     {fbvElement type="text" label="user.lastName" id="lastName" value=$lastName required=1}
     {fbvElement type="text" label="user.initials" id="initials" value=$initials size=$fbvStyles.size.SMALL}
 {/fbvFormSection}
  • Notice how the text fields use the fbv style info. In the above case, the size parameter is an fbv style constant. Other than the special treatment of size and including a label parameter, all of the parameters associated with the corresponding html element will be accepted.
  • The value of the translated label parameter will be displayed under the field, except in the case of checkboxes or radio buttons where the label will appear beside the control. In situations where this label is unnecessary, omit the label parameter.
  • The section heading is always the translated value of the form section's 'title' parameter.

Future

There are many opportunities to better and enhance the fbv.

  • reduce the need for mingling HTML and fbv by building input hints into the design