Forms

Info

Forms were added in v0.8, giving you a large amount of flexibility while still enabling helpful behaviors. We have several other features on our wish list for forms so watch the release notes in your PhosisUI dashboard! But, in the meantime, we hope you’ll find this initial functionality useful.

Just like most other items in Phosis, forms start with vanilla HTML.

Forms automatically receive v3 of Mattermind’s basic spam/bot protection code to cut down on spam submissions using a combination of behavioral tracking and honeypot techniques. Because you control the frontend, you can also incorporate additional frontend-only spam protection methods, if you wish, though we’d recommend starting with just our built-in baseline. (Backend solutions such as Google’s reCAPTCHA require access that we aren’t providing at this time, but are evaluating how best to enable if needed.)

You can view successful and suspected spam form submissions within your PhosisUI dashboard’s Form Submissions section, or optionally configure them to be emailed to you.

No file inputs

Phosis does not currently support file uploads in forms, and may remove any inputs set to type="file" within a Phosis form in the future until we determine how best to handle uploads.

Valid Form Field Types

Phosis supports <input> (with some oddities around radio buttons as of v0.8¹), <textarea>, or <select> fields. It includes serverside validation of required fields, and additional validation for the following types of <input>:

• number - ensuring it’s a valid whole number, unless the step parameter exists and is a non-whole number (e.g. step="0.1", as per MDN’s documentation on step attribute)
  • Optional min and/or max attributes specifying values between -79,228,162,514,264,337,593,543,950,335 and 79,228,162,514,264,337,593,543,950,335 (minimum/maximum value of .NET decimals)
• Date & time types - Based on ISO 8601 standard. NOTE: min and max attributes are not presently supported for these types
  • date - Date in the format YYYY-MM-DD
  • datetime-local - Localized datetime format YYYY-MM-DDThh:mm:ss Z|+|-hh:mm (omitting milliseconds)
  • month - year & two-digit month (2020-04)
  • time - 24-hour time with leading zeros (17:30) with optional seconds (17:30:23)
  • week - year & two-digit week with leading “W” (2020-W09)
• Types with RFC validation
  • email
  • url
• color as valid hexadecimal value

Phosis also validates that the value of a <select> is a value of one of its child <option> elements.

Sample HTML

Here is an example contact form in HTML from our tutorial with several different field types, with the Bootstrap-specific CSS classes removed:

<div class="your-form-container-class">
    <form data-phosis-form>
        <dl>
            <dt>
                <label for="name">Name</label>
            </dt>
            <dd>
                <input type="text" id="name" name="name" required placeholder="Please enter your name" />
            </dd>

            <dt>
                <label for="email">Email</label>
            </dt>
            <dd>
                <input type="email" id="email" name="email" required placeholder="Please enter your email address" />
            </dd>

            <dt>
                <label for="reason">Why are you reaching out today?</label>
            </dt>
            <dd>
                <select id="reason" name="reason" required>
                    <option disabled selected>Please choose&hellip;</option>
                    <option value="ArticleFeedback">Feedback on an article</option>
                    <option value="BizDev">Business development idea</option>
                    <option value="General">General contact request</option>
                </select>
            </dd>

            <dt>
                <label for="comments">Additional comments?</label>
            </dt>
            <dd>
                <textarea id="comments" name="comments" rows="4" cols="30" placeholder="Any additional comments? (optional)"></textarea>
            </dd>
        </dl>
        <div data-phosis-form-message></div>
        <button type="submit">Submit</button>
    </form>
</div>

Include labels or placeholders for readability of emailed results

As we’ll describe below in the Form Submission & Validation section, Phosis tries to send you a readable email of submissions by using an input/select/textarea’s <label> or placeholder.

Notice that the <form> tag has no action or method attributes. Phosis will automatically add these based on what page the form ultimately lives on, allowing you to use the same single form markup throughout your site.

What’s with that markup?

You absolutely don’t have to use definition list markup for your form’s container elements like in this example. It’s just one of many ways to wrap your form labels and inputs in relatively-semantic code allowing for layout hooks.

Some developers use <div> tags; others use pseudoelements :before & :after the <label> or <input> tags (which may be the most semantically transparent approach as the markup is truly only the form elements); still others use unordered lists. This is merely what we chose to use in this example, and we often just end up using <div> tags ourselves.

All Phosis ultimately cares about are the <label>, <input>, <select>, and <textarea> fields within your form.

Atrributes

The following attributes are used to configure form behavior in Phosis:

data-phosis-form

Used on <form> elements

Within a form’s HTML, mark any <form> elements that you wish to Phosis-enable with the attribute data-phosis-form. This allows you to mix Phosis forms with non-Phosis forms such as Mailchimp signup or other CRM-type forms.

data-phosis-form-message

Used on any container element (<div>, <p>, etc.)

(Only relevant in Standard Form Submit)

Any element you mark with the attribute data-phosis-form-message will have their content set to all of the form validation/error messages, with each error wrapped in <span class="p-msg"></span> tags, or to a configurable success message.

If no element has this attribute in your form HTML, errors will be appended to the form’s DOM wrapped in <span class="p-msg"></span> tags directly after each offending form field, and the success message will be inserted after the submit button wrapped in <p></p> tags. We recommend defining an element with this attribute to better control behavior.

data-phosis-error-required="message"

Used on any form input (<input>, <select>, etc.) that has attribute required

Default: The field name is required.

This is the error message that will be displayed when an element that is marked as required doesn’t have a value.

data-phosis-error-invalid="message"

Used on any form <input>that has a specific datatype (number, email, date, etc.)

Default: Please check your entry for field name.

This is the error message that will be displayed when the information a user enters doesn’t match the input type or isn’t valid.

data-phosis-can-enable

Used on <option> elements

Phosis creates a list of potentially valid values for <select> boxes from its child <option>s, ignoring any that are marked as disabled (as the placeholder element is in the sample HTML above.) Add this attribute to any <option> that you may be programmatically enabling/disabling that should still be considered a valid value.

Form Submission & Validation

When a form is submitted in Phosis using either method, Phosis uses the original form’s HTML itself as the validation guide. In other words, the following validations are checked serverside on submit:

• Form fields that you mark as required in the markup using HTML5’s required attribute will be checked to ensure they have a value
• Fields that are email, datetime-local/week/date, number, etc. will be validated for the specific datatype and, in the case of email, that they are valid email addresses according to the RFC specifications
• Fields with min/max attributes will have their value validated (step is not validated)
• <select> boxes will be checked to ensure that their submitted value matches one of the <option> values they contain

Tip

You may be dynamically adding <option> elements to a <select> box via Javascript. If so, this <select> would fail validation as the selected value likely doesn’t exist within it in your original HTML markup.

In this situation, you need to expressly tell Phosis to not validate the field by adding an attribute named data-phosis-novalidate to it, as the standard HTML5 novalidate attribute can only be applied to <form> elements.

However, you should feel free to use whatever clientside validation you prefer, especially if you wish to enforce more specific validation than required or not and datatype validation.

Email Notifications

If you’ve configured Phosis to email you form results, it will attempt to send you a successful submission in an easy-to-read email in a key/value layout like:

Field name: What the user typed

Field name 2: Another value

It does this by attempting the following if a submission passes validation:

1. Phosis collects all the various fields <input>, <select>, and <textarea>
   1. If the field type is a <select>, Phosis will attempt to use the text of the selected <option> as the value emailed to you.
2. For each field, Phosis will attempt to find a <label> and use the label’s text as the field name in the email.
   1. If the field is type="checkbox" and is checked, Phosis will have its value be the word “on” and its label as the field name. If it has no label isn’t found, it should fall back on the input’s value.
3. If a <label> can’t be found for a field, Phosis will attempt to use the placeholder text as the field name in the email.
4. Finally, should all of these fail, Phosis will fall back on the value attributes.

Standard Form Submit

By default, Phosis will simply configure itself to submit via POST to the same page that the form is on, and populate the data-phosis-form-message container with success or failure messages (or adding the DOM elements directly to the form if no such container is defined.)

In this method, fields that are invalid will receive an invalid class, and likewise valid fields will receive a class named valid.

If no message container is specified with the data-phosis-form-message attribute, error messages will be added in <span></span> after the relevant input as described above.

Heads up

Phosis does not add any clientside Javascript to automatically clear invalid status on fields if the user corrects their input. You should handle this on your own.

You should redirect to a success page. This is ideal to at least prevent form resubmission, and is useful for funnel tracking purposes. You can set this up via PhosisUI when configuring the form behavior, and your visitors will automatically be redirected to the success page if there are no issues with their submission.

AJAX Form Submit

You may choose to intercept the form submit event in your custom Javascript code to instead package the submission for AJAX. In this case, your Javascript should just submit to the same URL as the page the form is on. Phosis will check the X-Requested-With HTTP header to identify that this is an AJAX request and return JSON instead of the page HTML. Then, you can take action on your page to mark invalid fields or update your UI to display a success message.

The values for X-Requested-With header that will trigger this behavior are:

• XMLHttpRequest
• fetch

Phosis does not set a CORS policy, so this approach can also help mitigate CSRF attacks.

You should package your form’s fields using your serialize method of choice to result in key/value pairs and pass it to the same URL as the page, just like when doing a Standard Form Submit described above.

Be sure to include Phosis’s fields

Be sure that when you package your form’s key/values for submission that you include any hidden fields Phosis Render adds. These are used to help validate and track the form submission — and if they’re omitted Phosis will assume that the submission is from a bot.

Result Object

Phosis will return a JSON object with the following structure that you can then take action upon:

{
    "s": "e", // "s" = success, "e" = error
    "m": "Overall error or success message",
    "f": [ 
        // If any fields are in an error state, the reason Phosis rejected the input, by field name/key:
        {
            "fieldName1": "Error message for a specific field"
        },
        {
            "fieldName2": "Error message for another field"
        }
    ]
}

Bot/Spam Detection

Phosis uses some custom heuristics and tests to evaluate whether a form submission is spam or not. Should Phosis suspect a submission is from a bot, it will be placed into a separate location in your PhosisUI’s Forms section and it will not be emailed to any recipients configured for the form.

However, on the frontend, it will act as if the input was valid as to not indicate to any bot/spammer that their submission was rejected.

Little Bot Peep™ v2.0

On February 8, 2021, Mattermind released a new version of our the bot detection heuristics used in Phosis, now called Little Bot Peep, for beta testing and analysis. This was to compensate for some new strategies spammers were using. Phosis previously primarily relied on behavioral analysis to detect spammers and completely ignored the contents of form submissions. LBP2 now also adds on to the behavioral analysis with a series of word analysis steps. In addition, as we build up a corpus of valid contacts & emails versus spam, we will eventually turn on a Naive Bayesian filter.

While behavioral events may cause a form submission to be marked as spam, the new features in LBP2 also compute a spam score. Any form submission that exceeds a configured threshold will be marked as spam.

You can now view various metrics of form submissions within the Forms section of PhosisUI, and adjust the spam threshold configuration in your Site Settings.

Should legitimate submissions on your site end up getting marked as spam, please reach out to Mattermind support and we can adjust the heuristics for you.

---

1. As of v0.8‘s initial forms release, input type="radio" elements have some oddities around how their value is displayed in the submission report or emailed copy. ↩