Meerkat Forms

Front End
Version 1.5.8+
8 min read

You are viewing the documentation for Meerkat version 1 for Statamic 2. The latest version is Meerkat 2 for Statamic 3.

Read v2 docs

Overview

Meerkat's {{ meerkat:create }} form has been designed to be compatible with Statamic's {{ form:create }} tag (you can find more information about this tag here). Because of this focus on compatibility, you can use Statamic's form features with your Meerkat comment submissions; this includes setting up automated emails and metric-based reporting!

This section is intended to give you a more in-depth look into how Meerkat integrates with Statamic forms; if you need to get up and running as soon as possible, consider checking out the Integrating Meerkat guide.

Creating a Form Set

Like Statamic forms, you can create a "form-set" with Meerkat and gain access to many useful features, such as validation messages, form success or failures, etc. To do this, we can use Statamic's {{ form:set }} tag. The following example demonstrates how to use this tag to open a formset for Meerkat. The example will also show you how to check if the form submission was successful or not, and how to display the errors generated by the internal validation systems.

Note: We need to specify that the form-set is meerkat in order for forms to post to Meerkat's comment storage.

{{ form:set is="meerkat" }}

    {{# Determine if the form submission was successful. #}}
    {{ if {form:success} == true }}
        <p>Thank you! Your comment submission was received!</p>
    {{ else }}
        {{# There were errors, let's display them! #}}
        <p>There was a problem receiving your submission.</p>

        {{ if {form:errors} }}
            <ul>
                {{ form:errors }}
                    <li>{{ value }}</li>
                {{ /form:errors }}
            </ul>
        {{ /if }}

    {{ /if }}

{{ /form:set }}

Perfect! We now know the basics of opening a form-set for Meerkat and how to display success and error messages! Now that we can do that, we should probably look into creating the actual form.

Creating the Form

Now that we can create a form-set, let's look at how to quickly generate a form that will submit comments to Meerkat. The following example demonstrates using the {{ meerkat:create }} and {{ fields }} collection to quickly build the form (we will continue using the form-set):

{{ form:set is="meerkat" }}

    {{ meerkat:create }}
        {{ fields }}
            <label>{{ display }}</label>
            <input type="text" name="{{ field }}" value="{{ old }}" />
        {{ /fields }}
    {{ /meerkat:create }}

{{ /form:set }}

Form Attributes

Many times it useful to supply attributes to the form when it is being created. Such uses might be to add class names, id's or even data attributes. We can do this by using the attr parameter when creating the form. The following will instruct Meerkat to create a form using Bootstrap's form-horizontal class:

{{ form:set is="meerkat" }}

    {{ meerkat:create attr="class:form-horizontal" }}

    {{ /meerkat:create }}

{{ /form:set }}

Add as many attributes as you'd like, just separate them with the pipe | symbol and give them a name. The following example will also set an id on the created form element:

{{ form:set is="meerkat" }}

    {{ meerkat:create attr="class:form-horizontal|id:mySuperAwesomeId" }}

    {{ /meerkat:create }}

{{ /form:set }}

Creating Custom Forms

It is possible to create custom forms to have complete control over the visual presentation of your form. While this is more involved, it will allow you to custom tailor the generated form to exactly meet the requirements of your site, and rearrange the input elements as you wish (versus using the {{ fields }} tag pair).

In the following example, we will create a custom form using Bootstrap with a layout similar to the following image (the exact styling will depend on your own site):

Meerkat | Custom form layout

To accomplish this, we need to create the form input elements ourselves; to make make the implementation easy to use, we will use the {{ old:* }} Statamic tag to retrieve old user input if there happen to be submission errors. The following example might look large and scary, but is really similar to just the plain HTML markup with a little bit of magic thrown in:

{{ form:set is="meerkat" }}

    {{ meerkat:create attr="class:form-horizontal" }}
        <div class="row">
            <div class="form-group">
                <div class="col-md-6">
                    <label for="name">Name</label>
                    <input class="form-control" type="text" id="name"
                           name="name" value="{{ old:name }}" />
                </div>
                <div class="col-md-6">
                    <label for="email">Email</label>
                    <input class="form-control" type="email" id="email"
                           name="email" value="{{ old:email }}" />
                </div>
            </div>
        </div>
        <div class="row">
            <div class="form-group">
                <div class="col-md-12">
                    <label for="comment">Comment</label>
                    <textarea class="form-control" id="comment"
                              name="comment" rows="5"
                              >{{ old:comment }}</textarea>
                </div>
            </div>
        </div>
        <div class="form-group">
            <input type="submit" class="btn btn-default" value="Submit Comment" />
        </div>
    {{ /meerkat:create }}

{{ /form:set }}

Make sure the names of your custom input element's match the names of your form's fields! If you're having troubles receiving comments using custom forms, this would be one of the things to check first.