The Custom Forms module allows you to request information from users when they make reservations or requests. Forms can be created with powerful show/hide logic and can even be used to modify the appearance of reservations on your calendars.
Creating a Form
Forms are created independent from resources or services and are then attached to them so that a single form can be reused multiple times. To create a form, go to Administration > Forms and click the + Create Form button.
A form consists of a series of form elements that can be used to acquire or present different types of information to your users. Each field comes with a variety of options for where the information is displayed and restrictions on the value of data that can be provided. The supported types of fields include:
- Checkbox: A simple on or off checkbox with a label.
- Checkbox List: A list of simple on or off checkboxes with labels.
- Date Field: Request a date from a user and then decide a format for displaying that date.
- Dropdown Select: A dropdown select box that asks the user to select one value from a list of options.
- File Upload: Request users to upload a file. Limits on size and filetype can be specified.
- Number Input: Request a number from the user where the upper bound, lower bound, and step size can be specified.
- Text Input (Single-Line): Gather a short string of text such as a name or place. Limits on length can be specified.
- Text Input (Multi-Line): Gather a longer string of text such as a description or paragraph. Limits on length can be specified.
- Static Text: Simply display static text to the user for instruction or informational purposes.
- Reservation Color: Determine the color of a reservation with this form attached based on the values of other form elements. When used, this will override the default resource color on calendars.
- Computed Text: Compute a value of text to display based on the values of other form elements.
Common Form Field Options
Form fields can have their order changed by using the arrow buttons on the left hand side of each field to move them up or down one position, or directly to the top or bottom of the form.
- Label: The label used next to the form widget when presented to users.
- Hint: Provide hint text below the field to guide your users on appropriate or expected responses.
- Short Name: A short version of the label used for presentation purposes in CSV export or viewing responses in some scenarios.
- Required: Require a response from the user prior to proceeding.
- Only administrators can edit: Require moderator or administrator privileges to enter a value.
- Show directly on reservations and requests: Show responses from this field when viewing a reservation or request.
- Show on calendar and requests table: Show responses from this field directly on calendar events and on the requests table.
- Show in emails: Show responses from this field in confirmation emails.
- Make responses visible to all site members: Allow any site member to view the response to this field when viewing a reservation.
- Make available to all users through internal API: An advanced use case option that is required in some cases when advanced scripting is used.
Advanced Form Field Options
Advanced users are able to use scripting rules to decide on the visibility of form elements as functions of other form elements. For example, a group of fields can be shown only if an earlier checkbox is turned on. To access these options, and additional instructions and examples, click the Enable Advanced Mode button in the top right hand corner of the form editing page.
A form can be tested by using the Preview Form button at the top of the form editing page where field restrictions and advanced visibility logic can be previewed.
Attaching Forms to Reservations and Requests
Forms can be attached to reservations and requests by associating them with individual resources or site-wide.
Attaching to Individual Resources
When a form is attached to individual resources it will always be shown to the user after the standard reservation or request fields. This is because the standard request and reservation forms allow users to select, add, and modify the resources they are requesting, and thus, the relevant forms can only be determined after this point.
- Select a resource from the Resources list in Administration.
- Select the Reservations or the Requests tab.
- Select the Forms tab on the left.
- Select the form you wish to attach and then click + Attach Form.
- If more than one form is attached to this resource you can change their order by modifying the relative weights (higher values are shown later in the list of forms).
When a form is attached site wide, it is shown on every request and/or reservation made. Site-wide forms can be shown before or after the standard reservation or request fields and the final order will be determined by the relative weights. A negative weight is shown before the standard fields, and a positive weight is shown after the standard fields.
- Go to the Site Settings page in Administration.
- Select the Users & Reservations tab.
- Scroll down to the Reservation Forms card.
- Select the form you wish to attach and then click + Attach Form.
- If more than one form is attached to the site you can change their order by modifying the relative weights (higher values are shown later in the list of forms). The weight will also be used to determine relative order when combined with resource specific forms.
Important Note When Editing Forms
Form fields and their options are called a schema and the current schema used to generate forms for each reservation or request is stored with that reservation or request. If you edit a form in any way, the new schema will not be applied to existing reservations or requests; however, attempts to edit existing reservations or requests will apply the new schema.
For example, if you remove a field from your form, the previously submitted requests with that field will retain their responses; however, if these requests are edited then the updated version of the request will no longer contain that field.
Furthermore, if a Reservation Color field is added to a form, this new field will not be applied to existing reservations but it will be applied to all new reservations or edits of existing reservations.
Tip: To apply a new schema to existing reservations, click the reservation or request, select Edit and then save the request. If you are a moderator or an administrator you can choose to not notify the owner of that request and after the edit is saved, it will contain the updated schema.
This limitation is important because a form could change drastically making all previous instances of that form invalid; therefore, existing responses to forms are maintained even when forms themselves are updated.