Create custom forms to be filled out by site visitors. Form data may be saved, emailed to the form's owner, or both.
Based on code from the Profile plugin, several different field types are supported.
This plugin uses the glFusion automated plugin installer. Simply upload the distribtuion using the glFusion plugin installer located in the Plugin Administration page.
The plugin may be installed manually, if necessary.
The upgrade process is identical to the installation process, simply upload the distribution from the Plugin Administration page.
Forms are created by clicking “New Form” from the Forms administration menu. Each field has a help icon which will give information to help you make choices.
After a form is created and saved, you'll be returned to the form's edit screen. Scroll to the bottom and click “New Field” to start adding fields to the form.
If you wish to delete a field, you have the option of removing the field from the form, or removing it and its data. Either way the field's data will not be available, but if you leave the data in place then you have the option of re-adding the field and the existing data will again be available (except for users who've filled out the form in the meantime).
Form fields are created by clicking “List Fields”, then “New Field”, from the Forms administration menu.
A field may be one of several types:
Text fields are simple single-line text fields. The user may enter anything into this field. If “required”, then the field may not be left blank.
This is a single checkbox, which may or may not be selected. The “required” parameter does not apply to checkboxes since either “checked” or “unchecked” are valid responses.
This is a checkbox variable, where none or multiple items may be selected.
Refer to “Defining Multi-Value Fields” for instructions on setting up the options.
This creates a single-selection drop-down selection of the specified values. See “Checkbox” above regarding how to specify the values.
Refer to “Defining Multi-Value Fields” for instructions on setting up the options.
Radio Buttons work the same as Dropdowns. The “Required” parameter indicates that one item must be selected. Refer to “Defining Multi-Value Fields” for instructions on setting up the options.
The date field is used to collect a date and store it as a SQL-formatted date string (YYYY-MM-DD hh:mm:ss). If there is no time entry, the time value is set to “00:00:00”.
Dates use selections for the month and day, and a text box for the year. Any integer year value is supported; there may be some validation options added later.
The date format refers to which predefined format is used. Currently only “mm/dd/yyyy” and “dd/mm/yyyy” are supported.
Static fields simply display exactly what is entered as the Value. These can be used to insert a blank line in a form or display instructions.
Calculated fields use the Value parameter to perform calculations. The Value should be a comma-separated list of numbers and/or other field names. Complex calculations such as ”(A + B) * C” are not supported. Recursive calculations (using another calculated field as an argument) is supported, but be careful not to create a loop. For example, consider a tax calculation:
Field: tax Type: multiplication Value: .0875,amount Field: total Type: addition Value: amount,tax This would cause undefined behavior: Field: amount Type: any Value: 3,tax
There is a safeguard in place to ignore any references by a field to itself.
Some examples:
For single-value fields, such as text or date fields, the definition form should be fairly easy to use. For multi-value fields, such as radio buttons and dropdown selections, the creation of the options is a little less intuitive.
To add new fields, click on the small icon next to the “Value” prompt. An empty spot will appear where you can type the fields value. The radio button to the right is used to select the default value.
To remove an option from a multi-value field, simply erase the text. Empty fields are not saved with the field definition.
Forms will normally be displayed via an autotag (“forms:”) embedded within an article or other content. Forms can also be displayed by accessing {site_url}/forms/index.php?frm_id=XX, where “XX” is the numeric ID number of the form. If the current user is not allowed to fill out the form, they will be returned to the home page.
To embed a form by autotag, specify ”[forms:show form:XX]”, where XX is the form's ID number. Additionally, you may add an additional variable to specify a particular template file. You'll need to create this template, and it should be based on the “forms.thtml” file included with the plugin. This is an experimental feature. For example, to use a custom template to display form #3, you would use ”[forms:show form:3 template:custom.thtml]”. The custom template feature is only available when displaying a form via an autotag.
| Name | Required | Purpose |
|---|---|---|
| forms | Yes | Argument must be “form” to display the form |
| form or id | Yes | ID number of the form |
| template | No | Name of a custom template file. Any custom templates should reside in the {private_dir}/plugins/forms/templates/custom directory. |
Forms are only displayed to users who are members of the first group.
To display results within a page or article, the autotag would look like this:
[forms:results form:3 fields:address1,address2,city']
The available parameters are:
| Name | Required | Purpose |
|---|---|---|
| forms | Yes | Argument must be “results” to display the results |
| form or id | Yes | ID number of the form |
| fields | No | Comma-separated list of fields. All fields, except for the user ID/Name and submission date, will be displayed if this parameter is omitted. To include these as well, add “res_user” and “res_date”, respectively |
Form results are only displayed to users who are members of the correct group.
| Option | Description |
|---|---|
| Display glFusion Blocks | This governs which glFusion blocks are displayed when a form is called via http://site_url/forms/?frm_id=X. It has no effect upon forms displayed via autotags. |
| Default group to fill forms | Select the user group to be given access to fill out new forms, by default. This may be changed during or after the form's creation. |
| Default group to view results | Select the user group to be given access to view form results. If the current user is not a member of this group (or a form owner), then the results will be hidden from view when the “forms:results” autotag is used. |
| Default Text Field Size | Enter the number to be used as the default “size” parameter for text fields. |
| Default “maxlen” for Text Fields | Enter the number to be used as the default “maxlen” parameter for text fields. |
| Default textarea “rows” value | Enter the number to be used as the default “rows” parameter for textarea fields. |
| Default textarea “cols” value | Enter the number to be used as the default “cols” parameter for textarea fields. |
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
