Transcript

Perch 1.7 includes new forms functionality. Perch forms helps you to create forms on your website for users to complete. The data from these forms can be sent in an email and stored within the Perch admin allowing you to download this as a CSV – perfect for doing Mail Merge on contact data or importing the data into Excel or Access.

In this video I will show you how to get started by making a simple form.

First make sure you are running the latest version of Perch. As we are creating a form that submits to Perch you will also need the free Forms app which can be downloaded from http://grabaperch.com/add-ons/apps/forms.

Install the forms app by unzipping the app and placing the perch_forms folder into perch/apps/

Then open perch/config/apps.php and add the following line:

include(PERCH_PATH.'/apps/perch_forms/runtime.php');

Finally log into the Perch admin and click on the new link to Forms, this will trigger an install of the app.

We can then create our form. I am going to create a form that collects details of people who are attending an event I am running. I need to get their name and email address and some dietary preferences.

Form templates can include perch content as well as form tags. So they live in templates/content just as your other templates do and are used in the same way.

Create a new file called signup.html.

To create a form we need to start and end it with perch:form tags. This tells Perch that what we have is a form.

<perch:form id="signup" method="post" app="perch_forms">
</perch:form>

Inside the form I want to have an introductory message explaining to people what the form is for. So that this is editable in the admin I will add this as perch content.

<perch:content id="introtext" type="textarea" label="Sign Intro Text" textile="true" editor="markitup" />

Now I can add my fields using perch:input tags.

I want a name. I use the perch:label tag to create the label for the field, setting the id to name as this is the id of my name field.

I use perch:input with a type of “text”, I also set required to be “true” as users must fill in this field. The label attribute on the input field related to the label that will be used when this data is displayed in admin or in an email.

<div>
  <perch:label for="name">Name</perch:label>
  <perch:input type="text" id="name" required="true" label="Name" /> *
</div>

As this field is required, I need to also add an error message which will display if the form is submitted and the field has not been completed. I would like this error to display underneath the form field so straight after I add a perch:error tag with the for attribute set to “name” and type set to “required” – as we will see later there are different types of error that you can trigger.

Inside the perch:error tags I can write my message and any mark-up that I want to display on error. It is completely up to you what you put here. It is also worth noting that this error can go anywhere in the form – you get to decide how you display errors.

<div>
  <perch:label for="name">Name</perch:label>
  <perch:input type="text" id="name" required="true" label="Name" /> *

  <perch:error for="name" type="required">
  <span class="error">Please add your name.</span>
  </perch:error>
</div>

I would also like to capture the email address of the signup. So I add a new field for email address. This time using a type of “email”.

<div>
  <perch:label for="email">Email</perch:label>
  <perch:input type="email" id="email" required="true" placeholder="you@example.com" label="Email" /> *

  <perch:error for="email" type="required">
  <span class="error">Please add your email address.</span>
  </perch:error>
</div>

As email address is also required I use a perch:error with a type of required as an error block, however because I am using an email type I can also validate the format of this field.

If the field is completed with something other than an email address and submitted Perch will send back an error with a type of format. So we can catch this and display a message if the person did fill in the field but did not use a valid email address:

<div>
  <perch:label for="email">Email</perch:label>
  <perch:input type="email" id="email" required="true" placeholder="you@example.com" label="Email" /> *
	
  <perch:error for="email" type="required">
  <span class="error">Please add your email address.</span>
  </perch:error>

  <perch:error for="email" type="format">
  <span class="error">Please check the format of your email address.</span>
  </perch:error>
</div>

As you can see the additional perch:error tag that I have added has a type attribute with the value “format”.

I would like people to be able to tell me whether they prefer a vegetarian, meat or fish sandwich option. They can only choose one of these so I’m going to use a set of radio buttons.

To create a set of radio buttons you use a perch:input tag with a type set to radio. You then need to add an additional attribute of options. The value of this is a comma delimited list of options.

To have a different value for the label of the radio button than what is sent through to the form pipe delimit these values. So between the commas the first bit of text will be displayed on the page, then there is a pipe character, then the second bit of text will be sent through with the form. As you can see I have added clarification to the vegetarian option.

<div>
  <perch:label for="sandwich">Choice of sandwich</perch:label>
  <perch:input type="radio" id="sandwich" required="true" label="Choice of sandwich" 
      options="Vegetarian (may include dairy)|vegetarian,Meat|meat,Fish|fish" /> *
	
  <perch:error for="sandwich" type="required">
  <span class="error">Please select which sandwich you would prefer. 
        Use the notes field below to clarify any additional dietary requirements</span>
  </perch:error>
</div>

I will also add a free text area for people to add any additional information or to let me know that they are vegan or need a gluten free diet. I use the textarea perch:input tag but I have left off the required attribute and not added a perch:error tag as people may leave this blank.

<div>
  <perch:label for="message">Notes or other dietary requirements</perch:label>
  <perch:input type="textarea" id="message" label="Message" /> *
</div>

Finally a form needs a submit button.

<div>
  <perch:input type="submit" value="Signup" />
</div>

One very last thing before testing the form is that I want to add a message that will show after the form has been successfully submitted. I can do this by adding a perch:success tag.

<perch:success>
  <perch:content id="success" type="textarea" label="Success Text" textile="true" editor="markitup" />
</perch:success>

So that’s it. Save the template.

We now add our template just as we would add any other content template. I have a page here called signup.php. I add a Perch tag to the page “Signup form” and refresh the page.

Now I go to the admin and that page has appeared. I select the new field and then choose my signup template.

I can then add my intro text and success message and go back to the page. Refresh the page and a form appears.

If I just hit submit you can see the required field errors.

If I complete the form with a string of junk in the email field I get the email format error.

If I complete the form correctly I get the success message.

I can now create some rules in the Forms App to say how this form should be processed.

In admin go to the Forms app page, your new form should have appeared there. Click on Settings to get the settings page for the form.

By default storing results is checked, if you don’t want to store the results uncheck this.The next field is for if you have a form which has a field to upload a file or image. You can set here where they are stored. This should be outside of the root of your site so the file can’t be run in the browser.

If you want the form to send an email complete the email address or addresses here. You can also add a subject line and introduction text for the email so if you have a number of forms it is obvious which one this is.

Save this.

You can now test your form by putting some tests through and checking that the emails arrive.

If you have chosen to store results you can view them by clicking the name of the form. You can view the details online or download them as a csv and open it in Excel or similar.

One last thing. In the example so far I have had HTML5 set to false in my config. This is so I could show you Perch’s server side validation for format in action. If I set HTML5 to true then the fields will be rendered using the new HTML5 input types. So our email field now becomes an HTML5 email field and browsers which support HTML5 forms will validate the email address on the front-end without you needing to add any JavaScript.

Perch supports all of the new HTML5 field types so you can start using them right away in your designs. They are backwards compatible with older browsers so in a browser that doesn’t support the email field for example this will be treated as a text input and Perch’s validation will catch any format problem.