Guides
Tutorials
Pop Tags

Forms

If you're familiar with HTML forms, getting a form to work with Webpop couldn't be easier. Just write your HTML form as always, but replace the <form> tag with <pop:form>.

Inside of <pop:form> you can use <pop:success> to decide what to show when a form has been successfully submitted. Adding a "name" attribute to <pop:form> will send form submissions to the forms database which is located under the "Market" tab. There client users can view, search and export them.

You can also make your Webpop site email form submissions to any email address by adding a "mailto" attribute to <pop:form>.

A Simple Webpop Form

Here's a standard HTML contact form:

<form>
  <p><label>Name <input name="name"/></label></p>
  <p><label>Email <input name="email"/></label></p>
  <p><label>Message <textarea name="message"></textarea></label></p>
  <p><button>Send</button></p>
</form>

Lets convert this form so it sends emails and shows up in the form submissions list: 

<pop:form name="contact_form" mailto="me@example.com" mailsubject="New contact form submission">
  <pop:success><h2>Thank you, I'll get back to you straight away!</h2></pop:success>
  <p><label>Name <input name="name"/></label></p>
  <p><label>Email <input name="email"/></label></p>
  <p><label>Message <textarea name="message"></textarea></label></p>
  <p><button>Send</button></p>
</pop:form>

We've replaced <form> with <pop:form> and specified the email recipient and subject with the mailto and mailsubject attributes. We also added a success message with <pop:success>That's all - now the form works!

Form Fields

You can format the form markup however you want and use any of the field types: checkboxes, selects, radio buttons and even file fields. But just like a regular HTML form, if you include a file field you need to set the"enctype" attribute on the <pop:form> tag to "multipart/form-data".

Make sure all fields have a "name" attribute. In an HTML form, only fields with name attribute get send to the server. It's a good idea to keep the name fields lowercase and replace spaces with underscores (ie., a field called "Contact info" would get the name "contact_info").

If you need fields with multiple values, you'll need to add [] to the end of the name, otherwise only the value of the last field will count. Here's an example of a multi select field (note the name "colors[]"):

<pop:form name="favorite_colors">
  <pop:success><h2>Thank you!</h2></pop:success>
  <p>
    <label for="color-picker">Pick your favorite colors</label>
    <select name="colors[]" multiple="multiple">
      <option>Red</option>
      <option>Blue</option>
      <option>Green</option>
    </select>
  </p>
  <p><input type="submit"/></p>
</pop:form>

Form Validations

HTML5 defines a series of validation attributes for HTML forms. The <pop:form> tag is aware of these, and will make these validations serverside. Just like you can use <pop:success> to show a message when a form submission work, you can use <pop:error> to show a message when the validations fail.

Here's a small example of a form that uses the "accept" attribute on a file field to make sure that only PDF files can be uploaded.

<pop:form name="cv" enctype="multipart/form-data">
  <pop:success><h2 class="success">Thank you!</h2></pop:success>
  <pop:error><h2 class="error">Make sure you send your CV as a PDF</h2></pop:error>
  <p>
    <label for="cv-field">Your CV as PDF</label>
    <input type="file" name="cv" accept="application/pdf"/>
  </p>
  <p><button>Send your CV</button></p>
</pop:form>

Modern browsers will understand the "accept" attribute and limit the user to send PDF documents, but if a user sends a word document through an older browser, the "accept"validation will fail server-side and the user will see the error message.

Other useful HTML5 validation attributes:

  • required: <input name="name" required/> - this field needs to be filled out
  • minLength: <input name="name" minLength="2"/> - if this field is filled out, it must be at least 2 characters long
  • maxLength: <input name="name" maxLength="5"/> - this field can't be more than 5 characters long
  • pattern: <input name="name" pattern="[a-zA-Z]+" - for the daring, a regular expression can be supplied to validate the field

Modern browsers will automatically handle these validations client side, but for older browsers the validations will be handled server-side. Sometimes you might want to give more than just a generic error message when a validation fail. You can open up <pop:error> to customize errors for the individual fields. Here's a small example:

<pop:form name="newsletter_list">
  <pop:success><h2 class="success">Thank you!</h2></pop:success>
  <pop:error><h2 class="error">Please correct any mistakes below</h2></pop:error>
  <p>
    <label for="name">Name</label>
    <pop:error.name wrap="span" class="error">You must enter a name</pop:error.name>
    <input id="name" name="name" required/>
  </p>
  <p>
    <label for="email">Email</label>
    <pop:error.email wrap="span" class="error">You must enter an email address</pop:error.email>
     <input id="email" name="email" required pattern=".+@.+"/>
  </p>
  <p><button>Submit</button></p>
</pop:form>

If you're using a modern browser, it can be tricky to test the server-side error messages, since the browser will automatically do the validation client-side and simply won't let you send invalid data to the server. Adding a novalidate attribute to <pop:form> will disable browser validations - but the server-side validations will still be done:

<pop:form name="email" novalidate="true">
  <p>
    <label for="email">Email</label>
    <pop:error.email wrap="span" class="error">You must enter an email address</pop:error.email>
    <input id="email" name="email" required pattern=".+@.+"/>
  </p>
  <p><button>Submit</button></p>
</pop:form>

Custom Validations

Some times you might need to go beyond the built-in HTML5 validations and run some custom validation before storing a form submission.

The validator attribute tells the form engine to use an extension as a custom validator. The extension you specify must export a validate method. Here's a simple example validator:

exports.validate = function(options, params, errors) {
if (params.email && params.email.match(/@aol.com/)) {
errors.email = "Just don't write us from an aol email. Just dont...";
}
}

If this extension is stored as mail_validator.js you would be able to use it in a form like this:

<pop:form name="email" validator="mail_validator">
<pop:success><h2>Thank you!</h2></pop:success>
<pop:error><h2>Error!</h2></pop:error>
<p>
<label>Email: <input name="email"/></label>
<pop:error.email wrap="span" class="error"/>
</p>
<p><button>Submit</button></p>
</pop:form> 

If you try to submit this form with info@aol.com you would get an error message.

For a more involved example of a validator, check our ReCaptcha validation extension on GitHub.

Showing a Thank You Page

Use <pop:redirect> inside of <pop:success> to send people to another page upon a successful form submission:

<pop:form name="email" novalidate="true">
  <pop:success><pop:redirect to="thank-you"/></pop:success>
  <p>
    <label for="email">Email</label>
    <input id="email" name="email"/>
  </p>
  <p><button>Submit</button></p>
</pop:form>

Accessing Form Submission Data

Use <pop:params> to access the data of a form that was just submitted.
Let's say you have this simple form which ask for an email address:

<pop:form name="email">
  <input id="email" name="email"/>
  <button>Submit</button>
</pop:form>

You could show the email address that was submitted like so.

<pop:form name="email">
  <input type="email" name="email"/>
  <button>Submit</button>
<pop:success> <p>Thanks! The email address you submitted was: <pop:params.email/></p> </pop:success> </pop:form>

Entry Forms

Normally the form data is stored as generic form submissions, but it's also possible to use the <pop:form> tag to create entries in a section by adding a for attribute:

<pop:form for="submissions">
<pop:success><h2>Thank you!</pop:success>
<pop:error><h2>Error storing submission</h2></pop:error>
<label>
Title: <input name="title"/>
<pop:error.title wrap="span" class="error"/>
</label>
<label>
Body: <textarea name="body"></textarea>
<pop:error.body wrap="span" class="error"/>
</label>
<button>Submit</button>
</pop:form>

This will create a form that saves each new submission as an entry in the section with the id "submissions".

When using entry forms, you must make sure the fields included in the form matches the custom fields of the entries in the section specified in the for attribute. If the submitted data is not valid for that entry type, the form submission will not be stored (you can use the <pop:error> tag to access the validation errors).

Continue to Redirection »