Custom Forms

Modified on Thu, 25 Apr at 4:24 PM

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.
Form Fields
A form consists of a series of form fields 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:
Basic Fields
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.
Advanced Fields
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.

Invoice Item Fields
View an Introductory Invoice Item Fields Video

Invoice item fields are a powerful tool to augment your reservations and requests with additional items for invoices. Customize the look of each item with a name, description, image, and rules around the quantity available to select and how tax rates are applied.
When an invoice is generated from a reservation or request with Invoice Item fields, these fields will be grouped on the invoice by form and be added to the total value.
If the minimum units are set to 0 and the maximum units are set to 1 then the user is presented with a toggle switch instead of a quantity selection to turn that option either on or off (selecting 0 or 1 units).
The total cost of a reservation or request including resource rates and invoice item form fields is not calculated until an invoice is created due to tax options and rounding options only available on invoices.

Example Use Cases
Catering menus
Simple add-on services or options
Optional configuration choices
Invoice Items Total Computed Field
For your convenience, an Invoice Items Total field is provided that utilizes the Computed Field type with a built in script to total all of the invoice items on your form and display the value to the user.
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 email body: Show responses from this field in confirmation emails.
Show in email subject: Show the response at the front of the confirmation email subject.
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.
Testing Forms
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).
Attaching Site-Wide
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.