Forms Plugin

Create custom forms to be filled out by site visitors. Form data may be saved, emailed to the form's owner, or both.

• glFusion v2.0.0 or newer
• PHP 7.4 or newer

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.

• Several types of fields are supported:
  • Text
  • Textarea
  • Select
  • Radio Buttons
  • Checkboxes
  • Static text or HTML
  • Calculated based on static numbers or other fields
• Fields may be re-ordered as needed.
• Support for autotags.
  • [forms:show form:#] includes form “#” in another page.
  • [forms:results form:#] include a results table for form “#”
• Each form has an Owner and Group associated with it that are able to edit the form and view or download results.
• Access to fill out the form or view the results can be limited to specific groups.
• Results may be downloaded as CSV files for importing into spreadsheets.
• Individual form submissions can be printed for reference (useful for complex forms).
• Fields can be set as Normal, Read-Only, Hidden, and Required. Note that for checkboxes, Required means that the box must be checked in order for the form to be submitted.

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:

• Addition
  • Value: 1,2,3
  • Result: 1 + 2 + 3 = 6
• Subtraction
  • Value: 10,4,3
  • Result: 10 - 4 -3 = 3
• Multiplication
  • Value: 2,3,5
  • Result: 2 * 3 * 5 = 30
• Division
  • Value: 10,5,2
  • Result: 10 / 5 / 2 = 2.5
• Average
  • Value: 5,8,11
  • Result: (5 + 8 + 11) / 3 = 24 / 3 = 8

Any field type may be designated as “encrypted.” The submitted value for these fields is encrypted before saving to the database, and decrypted whenever displayed. This setting has no effect where forms are only emailed to users or groups.

The encryption uses a key that was generated when glFusion was installed and is unique to the installation. Therefore the data is not portable between glFusion installations.

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.

Forms are only displayed to users who are members of the “Group that can see results” defined for the form.

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:

Form results are only displayed to users who are members of the correct group.

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.