Formloom 4 Documentation

Avatar
Mike
Follow

Formloom 4 plugin

Formloom Basics

Start by adding a Formloom page to your site ( select ADD icon in RapidWeaver edit mode, then chose All Plugins -> Formloom 4 ) then you can editing form properties.

FormLoom Navigation Overview

When in Page Edit view, The Formloom plugin contains four separate input areas (Simply switch between views using the buttons at the left side of your RapidWeaver window).

These views are...

Form Items
These are the fields presented in your form

Header / Footer
The header and footer content areas above/below your Form Items

Templates
Email templates for both the form submission and customer receipt emails

Save Data
If you wish to save your form results to a hosted MySQL database, you'll configure that here.

 

Form Items (Fields)

To add a form item, click the + symbol. Once the item's been added, you can configure it.

Form Input Elements (Field Types)

Edit Form Item
FormLoom2 supports a variety of input types and options

Type
The first selection which must be made is the field TYPE. Choose the from the following fields in the Type menu

  • Text Field A single line text field for short text input
  • Select Menu A menu pre-populated with choices. User selects ONE
  • Radio Menu User can select ONE of the predefined option values you provide via selection of a button styled input
  • Multi Select Allows the user to select MULTIPLE pre-defined choices by using CMD-CLICK.
  • Checkbox Menu Allows user to select MULTIPLE pre-defined choices by simple on/off checkboxes
  • Hidden Form element not visible to the user. For example, if you your site were available in multiple languages, you might embed a field value for English on the form submitted from the English version of your site to allow you to know what language the submitter prefers.
  • Text Area A multi-line text area suitable for longer text input
  • File Input Allow users to attach files to form submissions.
  • Password A single line text input field with masked characters - character entry is hidden
  • Form Break This is essentially a style text field available for the site designer to add additional style text instructions or details - can be placed anywhere within a form
  • Column Break Deprecated in Formloom 4
  • Date Adds a calendar type input for users to select a date. ( format info )
  • Date/Time Advanced date picker that also includes sliders for time (24 hour format) - allow user to select a date AND time in a single input.
  • Time  Convenient time selector
  • Date Range Select date range based on specified availability.
  • Date - Time Range - Same as above but includes time as well.
  • Submit Button Add this field type where the form SUBMIT button should appear.
  • Reset Button Add this field type if you'd like to give users the option to clear their form and start over.
  • reCaptcha Test Deprecated in Formloom 4 - Now in Security Settings
  • Row Break Deprecated in Formloom 3
  • Email  Text input field prepended with Font Awesome envelope email icon.
  • Telephone  Text input field prepended with Font Awesome telephone icon.
  • URL  Text input field prepended with Font Awesome globe icon.
  • Number  This input allows the user to enter only numeric values.  Features increase/decrease selector which can be used in place of directly entering a value.
  • Rating  Five star rating input - user can click 1 to 5 stars to provide a rating value.  The value sent via email or saved to data source will be the numeric value of stars selected.
  • Color  Provides a color picker.  Users can visual select a color.  The color's hex value is saved and passed to your email template or data target.
  • Captcha  A more contemporary human challenge test, an alternate to reCaptcha.
  • WYSIWYG Allow your users to send HTML code using this input
  • Range Slider Slide-bar style input for selecting number range value.
  • Signature Accept actual digital signatures your users can sign
  • Security Question Get predefined answer before allowing form to be submitted.

Settings

EVERY form element has it's own Setting and Validation options. Just select the field you'd like to work with and make sure the Settings panel is activated.  Not all style options apply to all field types, but most fields allow you to modify individual input widths. Radio and Checkbox fields allow you to display option choices either vertically or horizontally.

Visibility
Checking this checkbox will hide this item when the page first loads. This is useful for inputs associated with Rules that show the item only when certain conditions are satisfied.

Tab Index
The tabindex attribute specifies the tab order of an element (when the "tab" button is used for navigating).

Label
The Label is how the field is reference on the form. For example, if you create a text field and enter FIRST NAME then the text FIRST NAME will be displayed next to your text field on the form.

Sub-Text
Additional text that will be displayed UNDERNEATH the input field on the form. Useful to provide input examples or field-specific instructions to users.

Placeholder
Placeholder Text will appear IN the input fields when the form is loaded.  This can be used to present additional information directly in the field.   For example, for a Name field, you may wish to enter:   Please provide your first AND last name......    Placeholder text will vanish when the user selects the field to provide their own data.

Class
If you're using your own custom CSS, we make it very easy to assign your own class names to individual fields.  If you're not writing your own CSS, you can simply disregard this setting.

Icon
Add Font Awesome 5 icons to your labels by enabling Icon and then provide the name of the  Font Awesome icon you'd like to use.  

Mask
Enable a mask to guide your user in entering their input - this is a formatting tool, not really a validation tool.  Use the following characters to setup a Mask:

  • a - Represents an alpha character (A-Z,a-z)
  • 9 - Represents a numeric character (0-9)
  • * - Represents an alphanumeric character (A-Z,a-z,0-9)

All other characters in a mask are literal - - -so if you enter them, they WILL be displayed.  Let's look at standard US formatted numbers as an example.  These numbers are formatted as such:  (313)456-1231.  So you have area code in parenthesis, followed by first three digits and last four digits of the number which are separated by a dash.  To require this type of format, your mask would look like this:  (999)999-9999.  Basically, your three mask characters (a,9,*) define user entered data and determine the TYPE of data, all other characters in your mask will be displayed as entered.

Tooltip
When enabled, a tooltip will appear when a field is selected.  Simply specify the location (in relation to the field) for the tooltip to be presented and provided desired text.

Grid Width
Formloom 4 now uses CSS Grid Width to assign the width of your form items. This new approach makes all your forms flow nicely from mobile to 27" iMac displays. 

 

List Inputs Vertically (Radio, Checkbox Inputs)
For applicable field types, this will format input choices horizontally, allowing for a shorter form length.

Default Value
Many field types will allow you to provide a default value. Text type fields have a Default Value text field where you can enter your desired text. Radio/Checkbox/Multiselectfields have a checkbox next to Option values. Simply enable the checkbox for values you would like to be enabled on the form by default.

Validation

FormLoom3 adds many new types of data validation.  You can enable multiple validation types and supply your own validation failure text for each type.

By default, field validation is set to NONE. You can enable the following validation types:

  • Required
    Enabling this checkbox will add your REQUIRED symbol next to the field. Some (any) entry into this field will allow submission, but it can not be EMPTY if required.
  • AlphaNumeric
    Input must only use numbers or letters. No special characters will be allowed.
  • Equal To
    User must provide input that is equal to either another field on the form.  Use the pulldown menu to select the field whose input must be matched.
  • Min Length
    A character counter.  Specify the MINIMUM number of characters this field must contain.
  • Max Length
    A character counter. Specify the MAXIMUM number of characters this field must contain.
  • Min Value
    A numeric value check.  Specify the MINIMUM numeric value that must be entered in this field.
  • Max Value
    A character counter. Specify the MAXIMUM number of characters this field must contain.

You can supply a custom error message in the Validation Error Message field. This is the test input to the right of each validation type.  This text will be displayed to the user if validation fails on THIS particular field. If you have multiple validated fields on a form, use this text to help call attention to the field not passing validation.

Header/Footer

Here you are given the option to place content above (header) and below (footer) your FormLoom generated form. These ares are STYLED TEXT - use the WYSIWYG editor to format text as you'd like it to appear. You can also drag in images to header or footer areas.

 

Templates

Templates in FormLoom allows you to format your emails however you like. To include values entered in your form, you will use placeholders. A placeholder is a representation of each form field based on it's name. To view your placeholders, expand the Item Placeholders section in the left sidebar. This will open a slide-out panel showing all placeholders available. You can simply drag them in to your message area.  It's that easy.  The Form Templates view has two tabs - Email and Receipt  (Toggle between the two at top of screen).  The Email template is what's sent to the FORM RECIPIENT.  The Receipt Template is used to send an automated message to the sender when the Receipt function is enabled in Inspector -> Settings.

An example template would be as follows...

Say we have three fields named name, email and message. In this case the place holders would be #name#, #email# and #message#.

So your Email Template may look something like this....

Name: #name#
Email: #email#
IP: #fl-ip#
Browser: #fl-browser#
Page: #fl-page#
Date: #fl-date#

Message:
#message#

Preview
Preview your emails right inside Formloom. You will know what your emails will look like before you even publish. A scalable window will open and show the current template you are working on. This provides a good way to see how emails will look on mobile and desktop devices.

Email Logo
Drag your company logo ( or any image ) into this well to include an image at the top of all your emails. Please make sure the image is not too big. Also make sure your Web Address is set in the projects General Settings. This URL will be used to link back to the image on your server.

Include in Email
Check the items you wish to include in Formloom generated emails.

Receipt Message
A short message that will be included as a header in your receipt messages to the sender. A good example would be " Thanks! The following information was emailed to our help desk".

Footer Text
Short bit of text to include at the bottom of the emails. This is a good place to include social media links, legal notes, etc...

Subject Template
Define a template for your subject which contains multiple placeholders.

Enable Custom Content
When checked, the custom content you type out will be used in  the body of the email ( instead of the default Formloom generated table ). This content can be Styled Text or Straight HTML. Please be careful, your custom content may break the Email Wrapper coding and cause the email to look undesirable. Only use this feature if you understand this.

Use Email Wrapper
On by default, this option uses the Formloom email html wrapper for all emails sent by Formloom. This provides a very professional look with zero effort on your part.

Base Placeholders
As you probably noticed in the above example, we also provide some global placeholder you can use in your templates.

  • #fl-ip#
    will insert the user's IP address.
  • #fl-browser#
    will insert the user's browser and platform.
  • #fl-page#
    will insert the page the form was sent from.
  • #fl-date#
    will insert the date and time form was submitted.

Receipt Email

This template behaves exactly like the one above for emails to the Site admin except the emails are sent to the person submitting the form. FormLoom2 allows you to send attachments along with receipts also ( see Page Inspector->Extras->Files ).

Save Data

MySQL Database Connection

FormLoom is capable of generating forms which not only submit results via email, but also archive form results in a MySQL database. You'll need to get the following information about your database (this is usually available from the company that hosts your site). As of Formloom 4 , all MySQL interactions are carried out via PDO.

MySQL Host Name
The address of your MySQL server. Default is normally localhost.

MySQL Username
The Username used to connect to your MySQL database server ( provided to you by your hosting company ).

MySQL Password
The Password used to connect to your MySQL database server ( provided to you by your hosting company ).

Database Name
The name of the database to use (some hosts offer multiple MySQL databases).

Table Name
You'll also probably want to create a table in your database to separate your Form data from other MySQL data.

Google Sheets

You can also save your form data to a Google Sheet (spreadsheet)

File ID
The Google ID Formloom needs in order to save data to your Google Sheet. You can find more information on how to find and use this value here. https://yabdab.zendesk.com/hc/en-us/articles/205171855

Field Assignments

This is basically a simple mapping of form fields to database fields. Select a form field to save to the database. Then use the Field Name text area to enter the field name in your database this form field data should be written to.  You'd enter those names here on field assignments next to the matching form fields.

For Google Sheets, you need to setup your columns using Column Headers. Here is a link to an article with instructions on how to properly do this... https://yabdab.zendesk.com/hc/en-us/articles/207082583-Set-Header-in-Google-Sheet

Extras

Browser
This will attempt to save the user's browser type to the designated field name in your database.

IP Address
This will attempt to save the user's IP Address to the designated field name in your database.

Date and Time
This will attempt to save the Date and Time to the designated field name in your database. It is best that you make this field of type DATE/TIME in your database structure.

Page Inspector

Once you've setup your basic form on the Form Items pane, it's time to take a look at the form settings in the Inspector - this is where you'll establish rules for processing and sending the form to the desired parties.

On your FormLoom page, you'll see five tabs under the Page Inspector

  • Settings
    The basics - where the form will be sent, who it will be sent from, etc
  • Security
    Rules for file attachments and user authentication
  • Code
    CSS , JS and PHP overrides
  • Style
    Enable custom styling to select custom colors/fonts/widths for your form
  • Text
    Place where you can s et custom text values to be used for errors, alerts, buttons, etc...
  • Extra
    More advanced settings, contains the following tabs:
    • Debugging
      If you're having trouble getting your form to work and would like server-level errors on what's going on, enable the debug options will allow script errors to show more detail - you can even have errors emailed to you.
    • Page Redirect
      If you'd like the form to redirect to another page altogether after a failed or successful submission, specify those pages (or offsite URL's here)
    • Files
      If you'd like to attach files to receipt emails, hit the + symbol and add them to the list. Keep it reasonable, some hosts will have limitations on file size or # of files that may be attached to script generated mail.
    • SMTP
      Optionally setup mail to be sent via an actual SMTP server you have access to.  A good option if you're forms appear to work properly and a success messages is presented, but you never receive mail.  Enabling SMTP insures that your mail goes out via an actual mail server instead of relying on the web server.
    • DKIM
      This allows you an additional means to authenticate mail as legitimate mail authorized to come from your domain/server.  Helps reduce mail being mis-categorized as spam.
    • Misc
      More advanced settings,  Also known as really useful things we wanted to add that didn't have a clear place of their own so the ended up in the Misc panel!

Settings Tab

Basic

  • Send Receipt - Email will be sent to person submitting the form.
  • Do Not Send Mail - Email will not be sent on submit.
  • No Theme - The current theme will not be used . Required when using Formloom Stack.
  • Persist Form Values - Input values will remain even if page is closed.

Recipients
Enter names and email addresses for form destinations. You can send TO, CC and BCC multiple addresses. Just click the + symbol to add a new recipient.

From Email
Enter the email address you'd like the form to be sent FROM - NOTE: Many hosts require the FROM address on email sent through their servers to match an actual account that exists on their network. If you're having trouble with forms not getting emailed, try entering a valid email address that exists on your host (ie, don't use an @gmail.com address as the from address on your @yourdomain.com form)

From Name
The name that will display in the email client as the FROM name. You might wish to use something like WebForm or Site Contact Submission if you use mail rules to perform actions on your form based mails.

Reply Email
The reply-to address on an email can be different than the FROM address, which is handy in cases where your host requires the form to be sent FROM an address associated with YOUR domain but you'd like replies to go directly to the sender. Select an email address on your form as the Reply-to address. This way your replies go directly to the person that submitted the form.

Reply Name
If you're soliciting the sender's name on the form, use the Popup menu to select their name to be populated as the reply-to name.

 Send From Reply Email & Name
Form will be submitted From the dynamic values submitted via the Reply-To Name and Email inputs. This is very dangerous and should be done only if understand that spammers could potentially hijack your form to relay spam. This is NOT RECOMMENDED

SMTP
By default, Formloom sends mail via php mail() on your host.  Some hosts disable this or don't have things configured properly, so we give you the option of enabling SMTP and sending via an actual mail server you have access to.  If your host provides you with an email account, then Formloom SMTP settings will use the exact same credentials you used when you setup your mail program or iPhone to connect to your mail account.  Use of SMTP is completely optional - but if you're having trouble getting your form to function once published, switching to SMTP is something you'll want to try. Additionally, SMTP supports SSL/TLS Authentication.  

  • Send via SMTP - Enabling this checkbox will enable SMTP as your form's mailer.
  • Host Name - your SMTP server's host name [Ex: mail.yourdomain.com]
  • Host Port - The port your SMTP server accepts connections on. This will probably vary depending on whether or not you are using a secure protocol (see below)
  • Send With Secure Protocol - If your host supports secure mail connections, select the proper protocol (SSL or TLS).
  • SMTP Authentication - Provide the username and password required to connect to your SMTP server. (most servers DO require authentication).

 

Security Tab

File Filter
Specify allowable file types to be attached. Any files sent to you must be of one of the allowable types you specify in this field. Separate allowable types with the | symbol (Shift + \ on most keyboards)

Word Filter
A comma-delimited list of words ( or strings ) to be filtered out of any form submission. This is good for removing any spam injection related strings like "bcc:" or "to:".

Max File Size
The max allowable size of each SEPARATE attachment here. (Note, if you have 3 file attachment fields and specify 10MB as your Max Attachment Size, that means each file may be up to 10MB - - or a total of 30MB for your form. Check with your host or ISP to make sure you don't exceed their maximum attachment size).

Google reCaptcha v.3
reCAPTCHA protects you against spam and other types of automated abuse. Formloom uses the invisible v.3 to make things MUCH easier on your site visitors. To create your required credentials, visit https://www.google.com/recaptcha/admin#list and register a new site using reCaptcha 3 as the type.

User Login
Control access to your form with User Login.  Enable the checkbox, then click the + to add usernames and passwords.  Users will be required to provide a valid username and password to access the form.  Only a login page will be shown until they have logged in.

Block List
The block list is a great way to stop spam or malicious submissions through your form.  You can add either IP addresses or email addresses to the block list.  Note that if you add the ip placeholder to your email template, you'll receive the sender's IP for every submission.  This is a good way to determine which IP's you may need to block.

Code Tab

CSS Override Code

Your own custom CSS that will be applied at the very end of stylesheet. 

 

PHP Override Code

This feature is for power-users that are very efficient with PHP. Any code entered here has the potential to break your form so USE IT AT YOUR OWN RISK!. If you have entered anything in this field, and your form stops working, then you are on your own. Do not send support tickets regarding this feature. Look at the output code and figure it out yourself. Not trying to sound harsh, but this is for experienced developers that need FormLoom to do a little extra.

JS Override Code

Same as above. Adding your own JS could seriously break things. Only use if you must.

 

Text Tab

Text Settings
Customize the text Formloom displays for various scenarios. This includes messages, labels and buttons.

 

Style Tab

Style Settings
If you'd like to utilize custom style defaults for your field, enable custom styling. When enabled, the settings in the following fields can be modified: 

  • Font - Comma separated list of fonts -- fonts will be displayed (when available on client computer) in order listed. Hint: USE WEBSAFE FONTS.
  • Color Pickers - use color pickers and font size selectors to customize fields, backgrounds and error/success styling.

Extras Tab

Redirect
Formloom gives you the option to redirect users to separate pages upon successful or failed form submissions. Enabling redirects will override any custom success/fail messages you have established. You can select either another page in your RW project OR enter a full URL to redirect to.

Files
You can supply file attachments WITH email receipts if you like. Simply enable File Attachments and then use the + symbol to open the file browser and add desired files to send along with the receipt email. Some hosts may limit the size of receipt files which can be sent, so pay attention to file sizes.

Debug
The FormLoom script can capture and report error event data. Enable DEBUG mode to see error messages on-screen during form submission. If you'd like to receive email notifications when errors occur, enable Notifications and supply a valid email address.  Note, that legitimate errors will result in a notification (a user forgetting to provide a valid field input, or failing recaptcha).  Please not:  All notifications are not a reason to panic, and do not indicate that something is wrong with your form - - it is simply a notification and another tool in your toolbox.

DKIM
DKIM is a method of allowing a user to add a digital signature to a message to prove that it is originating from a server they have authorized.  In some cases, this may help reduce the possibility of form based mail being mistaken as spam.  You need intermediate/advanced knowledge of DNS and have administration rights on openssl server to generate your keys.  There are some other options to generate keys but you may need to judge the security of those options for yourself, however, we can not recommend a method other then key self generation.  You are responsible for generating your own keys, you simply need to enter your DKIN data that you've generated into Formloom.  You will need to make sure you have SMTP enabled in the Formloom page inspector to use DKIM signing.  A great primer on DKIM can be found at  http://www.dkim.org/info/dkim-faq.html

Enable DKIM - this is disabled by default.
Domain Name - the domain name of the sending mail server.
Domain Key - the private key you've generated or obtained.
Selector - for organizations with multiple mail servers, establishing a selector name for each server permits multiple keys under the same organization.
Passphrase - required if your DKIM key is encrypted.

Misc
Additional/advanced customization options

Required Symbol
The symbol that will appear next to form fields that you have designated as required fields. This is * by default.

Date Format
The format used for internal saving functions when date is used. The following elements will use this format

  • The #fl-date# placeholder in emails and receipts
  • MySQL date column
  • Google Sheet date column

This format is different from the date input items. This format is the PHP format. You will need to use PHP formatting symbols on this settings.

Username Label
Text label that will be displayed next to username prompt if Authentication is enabled.

Password Label
Text label that will be displayed next to password prompt if Authentication is enabled.

Login Button
Text label that will be on the login button if Authentication is enabled.

Receipt Prefix
Text that will be prepend the Receipt Email's subject (Re: is standard US/English abbreviation for Reply and is a common prefix for the email subject line if it is a reply to an inquiry. For no prefix, simply leave blank.

Email Charset
If your language utilizes characters not supported by ISO-8859-1, which is the default setting, choose a compatible character set from the pulldown menu.

Transfer Encoding
If you have a specific encoding requirement or are connecting to an BITMIME SMTP server, you may need to update your encoding selection. The defualt will work for most users. If your mail host or an application you'll be working with to manage mail specifies alternate encoding, you can select your desired method here.

 

Formloom 4 Helper Stack

In the past, there have been various third party products used to place Formloom forms in other page types.  Some worked better than others.  Ultimately we felt it was best to give users the ease of building a plugin based page, then placing their complete form onto a stacks page.  The Formloom 4 Helper stack serves just this purpose.  Here's a rundown of the workflow:

  • Create your form using the plugin
  • Go to the Page Inspector -> Settings tab and enable the NO THEME option at the top under Basic (this prevents theme nav, sidebar, etc from getting pulled into the Stacks page as well)
  • Remove the Formloom plugin page from site navigation so it's not also directly available to users (Page Inspector -> General Settings -> Show in Navigation)
  • Go to your Stacks page.  Place the FormLoom 4 Helper stack where you'd like to place the form.  Be sure to give consideration to how much total width you have available - your Formloom page is responsive and will render in the area available.

The stack has only ONE setting, Set Link.  Select this to invoke the page selector tool.  Make sure the TYPE is set to Page and select the Formloom page from the Page menu (all pages in your site should be available, make sure you select only the Formloom page)

You will need to publish your page to view the imported Formloom content, it will not work in Preview mode.

 

Have more questions? Submit a request

0 Comments

Article is closed for comments.
Powered by Zendesk