Topics

Forms and Controls in Exponent

Overview

Forms and controls are a basic building block for many pages or interfaces within Exponent.  Therefore, we've developed some handy tools to make their use more intuitive and to provide better integration into the system.

Even though the information in this area deals primarily with the 'tags' placed in a view template to display controls in a form, it is also the reference for the form control classes which would be used to build a 'form' within a controller.

Building a Form in the View

A form not only displays data, it is used to send data back into Exponent.  Forms are fairly easy to create since in most cases they are simply a {form} block with {control} inside.  There are some important aspects though.  We must ensure we have an 'action' for the form to return to, include some basic hidden data such as the record id, and round it out with a {buttongroup} to do the work.  Here is the form we use to edit a text item in Exponent.

{form action=update}
        {control type=hidden name=id value=$record->id}
        {control type=hidden name=rank value=$record->rank}
        {control type=text name=title label="Title"|gettext value=$record->title|escape:"html"}
        {control type=html name=body label="Body Content"|gettext value=$record->body}
        {if $config.filedisplay}
            {control type="files" name="files" label="Files"|gettext value=$record->expFile}
        {/if}
        {control type=buttongroup submit="Save Text"|gettext cancel="Cancel"|gettext}
{/form}

Form and Control Guides

{control} smarty function

The {control} tag is used to place controls within the form.  Generally, the class file for each of these controls is found in the '/framework/core/subsystems/forms/controls' folder.  It is called in the following format:

...

{form} smarty block

The {form} block encapsulates a form in a template.  It accepts several parameters, but the most common is the action to take when the form is submitted via the buttongroupcontrol.

...

antispam Control

The antispam control places reCaptcha validation in the form based on the Anti-Spam Site Configuration settings.  You must have turned on the site anti-spam measures and set the reCaptcha Public and Private keys. It does NOT use the antispamcontrol class in the forms/controls folder.

...

autocomplete Control - autocompletecontrol Class

The autocomplete control places a text box in the form with autocomplete support.  It uses the autocompletecontrol class in the forms/controls folder.

...

buttongroup Control - buttongroupcontrol Class

The buttongroup control places action buttons in the form which are used to process the form entries.  It is typically placed as the last control in the form.  It uses the buttongroupcontrol class in the forms/controls folder.

...

calendar Control - calendarcontrol Class

This creates a widget with text entry date and/or time and a pop-up date selector.

...

checkbox Control - checkboxcontrol Class

The checkbox control places a checkbox in the form.  It uses the checkboxcontrol class in the forms/controls folder.

...

color/colorpicker Control - colorcontrol Class

This control creates a text box for entering a hex html color (e.g., #FF0055) and a sample of the color, It generates a popup color selection dialog when the text box or color sample is clicked.

...

country Control - countrycontrol Class

This creates a dropdown list of countries.

...

countryregion Control - countryregioncontrol Class

This control creates two synchronized drop-down lists of countries and regions/states.  The states list is dynamically updated based on the selection in the country list.

...

customcontrol Class

This class is used to embed a custom control such as a form within a form, etc...

...

datetime Control - datetimecontrol Class

The datetime control places a set of text based date time controls in the form.  It uses the datetimcontrol class in the forms/controls folder.

...

dropdown Control - dropdowncontrol Class

The dropdown control places a drop-down list in the form.  It uses the dropdowncontrol class in the forms/controls folder.

...

editor or html Control - ckeditorcontrol, tinymcecontrol, or htmleditorcontrol Classes

The editor or html control places a multi-line text box with a WYSIWYG editor in the form.  The two control types are a psuedonym for each other.  It uses the either the ckeditorcontrol or htmleditorcontrol class in the forms/controls folder based on the site selected WYSIWYG editor.

...

email Control

This creates an HTML5 email input field which provides some input validation and keyboard selection on handheld devices.

...

files Control - filemanagercontrol Class

This control creates the 'Add Files' widget control.

...

grouplistcontrol

This smarty function {grouplistcontrol ...} creates a listbuilder control populated with user groups.

...

hiddenfieldcontrol Class

This creates a 'hidden' field within a form.

...

listbuilder Control - listbuildercontrol Class

This creates a managable list where a list can be managed from a second list of all available items.

...

monthyear Control - monthyearcontrol Class

This control creates two drop-down lists for selecting a month and year.

...

number or quantity Control

This creates an HTML5 'number' input field with the up/down arrows used for incremental adjustments.

...

popupdatetime Control - popupdatetimecontrol Class

Creates a text date/time with an icon to select/change that date/time.

...

radio Control - radiocontrol Class

Creates a single radio button.  Generally this is a sub-component of the radiogroup control.

...

radiogroup Control - radiogroupcontrol Class

The radiogroup control places a radio button group in the form.  It uses the radiogroupcontrol class in the forms/controls folder.

...

range Control

This creates an HTML5 range input field which provides a slider to select from a range of numbers.

...

search Control

This creates an HTML5 search input field.

...

state Control - statescontrol Class

Creates a dropdown list of states/regions.

...

tags Control - tagpickercontrol Class

Creates a control to select from all the tags in the system.  This is how we currently implement tags.

...

tagtree Control - tagtreecontrol Class

This control crreate a managable tree of tags.  This is currently used for (nested) store categories.

...

tel or telephone Control

This creates an HTML5 telephon input field which provides keyboard selection on handheld devices.

...

text Control - genericcontrol Class

The text control places a single line text box in the form.  It uses the genericcontrol class in the forms/controls folder.

...

textarea Control - texteditorcontrol Class

The textarea control places a multi-line text box in the form.  It uses the texteditorcontrol class in the forms/controls folder.

...

uploader Control - uploadcontrol Class

This control allows a user to 'upload' a file, which in a form will send the file as an attachment.

...

url Control

This creates an HTML5 url input field which provides some input validation and keyboard selection on handheld devices.

...

user Control

Creates a dropdown list of all usernames in the system.

...

userlistcontrol

This smarty function {userlistcontrol ...} creates a listbuilder control populated with system users.

...

yuicalendar Control - yuicalendarcontrol Class

The yuicalendar  control places a YUI calendar widget control in the form.  It uses the yuicalendarcontrol class in the forms/controls folder.

...

yuidatetime Control - yuidatetimecontrol Class

The yuidatetime control places a YUI calendar widget and date/time control in the form.  It uses the yuidatetimecontrol class in the forms/controls folder.

...