Login Welcome to LeeGarner.com
Friday, October 31 2014 @ 02:11 PM PDT
 

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.

Based on code from the Profile plugin, several different field types are supported.

Requirements

  • glFusion v1.2.0 or newer
  • PHP 5.1 or newer

Installation

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.

Upgrading

The upgrade process is identical to the installation process, simply upload the distribution from the Plugin Administration page.

Features

  • 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.

Usage

Creating Forms

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).

The form name does not have to be unique. However, that may change in the future and it's a good idea to use a unique name for each form

Creating Fields

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

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.

Checkbox

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.

Multicheck

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.

Dropdown

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

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.

Date

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

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

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,13
    • Result: (5 + 8 + 11) / 3 = 24 / 3 = 8

Defining multi-value fields

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.

Displaying Forms

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.

NameRequiredPurpose
formsYesArgument must be “form” to display the form
form or idYesID number of the form
templateNoName 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.

Displaying Results

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:

NameRequiredPurpose
formsYesArgument must be “results” to display the results
form or idYesID number of the form
fieldsNoComma-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.

Administration

Configuration Options

OptionDescription
Display glFusion BlocksThis 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 formsSelect 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 resultsSelect 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 SizeEnter the number to be used as the default “size” parameter for text fields.
Default “maxlen” for Text FieldsEnter the number to be used as the default “maxlen” parameter for text fields.
Default textarea “rows” valueEnter the number to be used as the default “rows” parameter for textarea fields.
Default textarea “cols” valueEnter the number to be used as the default “cols” parameter for textarea fields.

License

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.

glfusion/glforms/start.txt · Last modified: 2011/08/09 03:02 by lee
 
Except where otherwise noted, content on this wiki is licensed under the following license: GNU Free Documentation License 1.3

Random Image

 
 
PICT0130.jpg
Browse Album

My Account






Lost your password?