Formloom 3 plugin
Formloom Basics
Start by adding a Formloom page to your site (select ADD icon in Rapidweaver edit mode, then chose All Plugins -> Formloom 3) then you can editing form properties.
FormLoom Navigation Overview
When in Page Edit view, The Formloom plugin contains five separate input areas (Simply switch between views using the buttons at the bottom of your RapidWeaver window). These views are
Form Items
These are the fields presented in your form
Head/Foot
The header and footer content areas above/below your Form Items
Templates
Email templates for both the form submission and customer receipt emails
Text
Provide detailed text messages specific to your form - errors, instructions, etc
Save Data
If you wish to save your form results to a hosted MySQL database, you'll configure that here.
Overall Page Settings for the entire plug-in are located 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 selectes ONE
- Radio Menu User can select ONE of the predfined 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 (This is a legacy field type and included only to allow transition of Formloom2 pages to version 3. It is not recommended to use this field type in NEW Formloom3 forms, instead consider using the 12 column grid model to build rows/columns) This is another styling option for the site designer. Add a column break where you'd like one column of inputs to end and your second (or third) to begin. NOTE that the body of your page MUST have enough width to support columns. You can adjust column widths in the Page Inspector -> Style tb
- Date Adds a calendar type input for users to select a date. The default format is yy-m-d - this is the format that Date Validation will validate. If you change this format, you will not be able to use the Date type validation. Date can be formatted as follows:
d - day of month (no leading zero)
dd - day of month (two digit)
o - day of the year (no leading zeros)
oo - day of the year (three digit)
D - day name short
DD - day name long
m - month of year (no leading zero)
mm - month of year (two digit)
M - month name short
MM - month name long
y - year (two digit)
yy - year (four digit)
@ - Unix timestamp (ms since 01/01/1970)
! - Windows ticks (100ns since 01/01/0001)
'...' - literal text
'' - single quote
anything else - literal text - 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 Add a graphical text challenge to insure humans, not bots, are placing form submissions.
- Row Break (This is a legacy field type and included only to allow transition of Formloom2 pages to version 3. It is not recommended to use this field type in NEW Formloom3 forms, instead consider using the 12 column grid model to build rows/columns) Add a row break (Manually force following form elements down and to the left margin) and define its width.
- 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 Slider based input to select a time (24 hour format).
- 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.
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.
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.
Width Type
You can use the following methods to define the width for an input:
- Pixel Width - define the exact width, in pixels of the input (not recommended for forms where responsive use is required)
- Percentage Width - define the percentage of the parent element the item is contained in (in most cases this will be the body width of the theme)
- Grid WIdth - based on the BootSnap 12 column grid layout, this method works best for responsive performance. Simply select the number of grid columns (out of 12 total) that should be allocated to this input, when available. Learn more about grid layouts at w3schools.
Input Icon
Add Font Awesome icons to your inputs by enabling Input Icon and then provide the name of the Font Awesome icon you'd like to use. You can place the icon on the left side (Prepend) or right side (Append) of the input.
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.
Masked
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.
List Inputs Vertically (Radio, Checkbox Inputs)
For applicable field types, this will format input choices horizontally, allowing for a shorter form length.
Use Switches (Radio, Checkbox Inputs)
For applicable field types, this will format the input selector as a on/off switch.
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. - Email
Verifies that the data provide in this input is a properly formatted email address (user@domain.tld) - URL
Verifies that the data provide in this input is a properly formatted web address (http://www.domain.tld) - Date
Verifies that the input is provided in yy-m-d format. This is the default format of the Date input type. - Digits
Used to ensure that only numeric values are provided - 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.
Text
The Form Text panel contains text you can customize within the page:
Basics
- Success Message
Text displayed in the form boday ara after a successful submission. - Enter Security Code (captcha)
Instructional text that appears above the Captcha challenge.
Errors
- General Error Message
Generic error message displayed to users if form is unable to submit - generally due to mis-configuration of form. - Capthca Failed
Text displayed when user does not correctly complete a reCaptcha challenge. - Files Too Large
Text displayed if user attaches file that exceeds limits as specified in Security Settings. - File Not Allowed
Text displayed if user attaches file that is not allowed as established in Security Settings. - Invalid Login
If you have Login ENABLED on the security tab and the user fails to provide proper username/password, this text will be displayed. - Blocked Message
Text displayed when a user that has been blocked (based on email or IP as set in the Page Inspector -> Security -> Block List panel) tried to submit form.
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, click the Placeholders button in the top right hand corner of the screen (The menu button signified by 4 vertical lines). This will open a slideout panel showing all placeholders. 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#
Subject Template
New in Formloom 3.0.3, you can define a template for your subject which contains multiple placeholders.
Global 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);
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.
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.
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 attahments and user authentication - Code
CSS and PHP overrides - Style
Enable custom styling to select custom colors/fonts/widths for your form - Extra
More advanced settings, contains the following tabs:- 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. - Debug
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. - DKIM
This allows you an additional means to authenticate mail as legitimate mail authorized to come from your domain/server. Helps reduce mail being miscategorized 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!
- Redirect
Settings Tab
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.
Subject ( Deprecated in version 3.0.3 )
Please see Templates section on setting up Subject.
Send Receipt
Enable if you want to utilize the receipt email template (Receipt template under Text tool) to send an automated email receipt back to the sender. This will occur as soon as the form is processed.
Do Not Send Mail
This tool is for users who wish to disable the email function of FormLoom and instead save data only to MySQL.
No Theme
Enable No Theme if you'll be using the FormLoom Stack for Rapidweaver to place your FormLoom page INSIDE a Stacks page. This turns all all theme based content on the page allowing ONLY your form content to be placed on the stacks page.
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).
User Authentication
When authentication is ENABLED, users will need to supply a username and password before they can access your form. Add such username/password combos by pressing the + sybol at the bottom of the inspector.
SSL Mode
Enabling this feature will tell FormLoom to call any external scripts or stylesheets via HTTPS. Users should enable this if they are serving their FormLoom pages via a HTTPS (SSL) connection.
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
If you have been provided with custom CSS to modify the appearance of a product, it's easy to simply copy / paste this into Rapidweaver.
1. Copy the CSS code you'd like to utilize.
2. Open Rapidweaver and select the page to apply the styling to
3. Select Page Info -> Style -> Header
4. At the lower portion of this pane, choose the CSS tab.
5. Paste your custom CSS into this input
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.
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.
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).
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 the date will be presented in, by default this is yy-m-d which is the proper format to utilize with Date Validation. You can change the date format, but you can not use Date Validation with other format. m = month, d = date, yy = two digit year
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.
Calendar Locale
The language set that will be utilized for Datepicker field labels (ie, month, date, day of week name)
Formloom3 Remote 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 Formloom3 Remote 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 bottom (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 FormLoom3 Remote 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.
0 Comments