Cookbook Forms

Basics

Working with forms in pages is extremely easy, depending on what you want to do with them.

As with most things in pages, it requires the correct frontmatter as well as the html content.

Frontmatter for a basic contact form:

---
title: A Form
summary: A simple contact form
form:
    name: form
    schema:
        name: [string, required]
        email: [email, required]
        message: [string, required]
        checkbox_group: [string, required]
    redirect: thank-you
    honeypot: name_407d3z05
---

This sets up the basics - title, summary, the name of the form and the fields to be used. It also provides for a thank-you page redirect (which is the name of a Pages document without include the '.html.php' part of the filename).

It also sets up an anti-spam honeypot, which does away with the need for other anti-spam measures.

HTML for a basic contact form

<h1>Contact Form</h1>
<form method="post">
    <label>Name:</label>
    <input type="text" name="name" id="name" size="30" value="">
    <label>E-mail address:</label>
    <input type="email" id="email" name="email" size="30" value="" maxlength="100">
    <label>Message:</label>
    <input type="textarea" id="message" name="message">
    <fieldset>
        <legend>Checkbox Group</legend>
        <label>
            <input value="Option 1" name="checkbox_group[]" type="checkbox">
            <span>Option 1</span>
        </label>
        <label>
            <input value="Option 2" name="checkbox_group[]" type="checkbox">
            <span>Option 2</span>
        </label>
    </fieldset>
    <?= helper('form.honeypot', page()->form->honeypot); ?>
    <div>
	<button type="submit"  data-errormsg="Send message" data-successmsg="Sending">Send</button>
    </div>
</form>

You now have a basic form that will redirect to a thank you page (if you created it!).

The only problem we now have is... what to do with the data?

Sending the data

Sending the data is a built in feature of Pages, which includes support for both standard 'processors' and using the extensions function to add your own.

Here's what adding the processor for sending the contents of the form looks like in the frontmatter:

---
title: A Form
summary: A simple contact form
form:
    name: form
    processors:
        - csv
        - 'email':
            recipients: [email protected]
            title: The title of the form
            subject: The subject of the form
    schema:
        name: [string, required]
        email: [email, required]
        message: [string, required]
        checkbox_group: [string, required]
    redirect: thank-you
    honeypot: name_407d3z05
---

If you need multiple recipients you can overwrite it as an array:

processors:
        - csv
        - 'email':
            recipients: 
                - [email protected]
                - [email protected]

Saving the data

Saving form data to CSV is extremely easy, and supported out-of-the-box by Pages, requiring only a minor change to the frontmatter.

Note the new csv option in the processors section below:

---
title: A Form
summary: A simple contact form
form:
    name: form
    processors:
        - csv
    schema:
        name: [string, required]
        email: [email, required]
        message: [string, required]
        checkbox_group: [string, required]
    redirect: thank-you
    honeypot: name_407d3z05
---

Now, create a folder called 'logs' inside joomlatools-pages.

If you submit your form now, you should have a file called 'form.csv' in the logs folder that has the submission data.

Congratulations, you just built your first form in Pages!

Troubleshooting CSV storage

If you created the folder, but don't see the file, try creating the file called form.csv in the logs folder and try again.

If it still doesn't work, make sure the permissions and ownership for the folder and file are correct.

Creating a user

We can also use the Joomla! API to create users. The below example is an extremely simple implementation, with no checking for existing users, and no password validation or strength checks.

Create the processor

We're going to use Pages extensions feature to extend the capabilities of its data processing.

If you don't already have a folder called 'extensions' under your joomlatools-pages directory, create one now.

Then in the extensions folder, create another called 'processor':

/joomlatools-pages
- extensions
- - processor

Create a file called 'user' and add the following code to the file:

<?php
class ExtensionProcessorUser extends ComPagesControllerProcessorAbstract
{
	public function processData(array $data)
	{
		$payload = [
		 	'name'      =>  $data['name'],
		 	'username'  =>	$data['email'],
		 	'password1' =>  $data['password'],
		 	'email1'    =>  $data['email'],
 		];
		$lang = JFactory::getLanguage()->load('com_users', JPATH_SITE);
		JLoader::register('UsersModelRegistration', JPATH_BASE . '/components/com_users/models/registration.php');
		$model = JModelLegacy::getInstance('Registration', 'UsersModel');
		$result = $model->register($payload);
	}
}

As you can see, this uses the Joomla API to call the user registration functions, and we're mapping the fields in the form to the possible fields in the Joomla API. This includes email2 and password2 for validating those entries. In this case I'm also making the email the username for simplicity's sake.

Now we can create our form. Our frontmatter looks like this:

---
title: User registration
summary: A simple user registration form
form:
    name: form
    processors:
        - csv
        - ext:processor.user
    schema:
        name: [string, required]
        email: [email, required]
        password: [string, required]
    redirect: thank-you
    honeypot: name_407d3z05
---

You can see that we have added an extension called 'processor.user' to the processors list, calling the function we created earlier.

Now we just build the form fields:

<h1>Contact Form</h1>
<form method="post">
    <label>Name:</label>
    <input type="text" name="name" id="name" size="30" value="">
    <label>E-mail address:</label>
    <input type="email" id="email" name="email" size="30" value="" maxlength="100">
    <label>Password:</label>
    <input type="password" id="password" name="password">
    <?= helper('form.honeypot', page()->form->honeypot); ?>
    <div>
	<button type="submit"  data-errormsg="Send message" data-successmsg="Sending">Send</button>. 
    </div>
</form>

Before submitting the form, go to your Users menu, choose 'Manage', then click the 'options' button in the top right corner.

Make sure 'Allow user registration' is turned on. You may also want to ensure that the user either self-activates, or is activated by the admin.

Now try submitting your form - after which there should be a new user in your database!

NOTE As mentioned previously, the above implementation doesn't do any checks for existing users, it's a very simple implementation that should be expanded further.