Acceptance Testing III - Contact Form

Creating the contact form that our acceptance test will pass


In the previous article, we created the acceptance test for our contact form in MODX. In this one we'll create the contact form itself in the MODX Manager and test it with that acceptance test.


MODX logo

This article assumes that you've installed and configured Composer, Codeception, PhpUnit, MODX, Java, WebDriver, and ChromeDriver as described in earlier articles. It also assumes that you've created the test in the previous article.


Quick Intro to MODX

If you're familiar with MODX, you can skip this section. We're going to create a page in MODX on our test install, then test it with an acceptance test. When MODX gets a request, it gets the corresponding resource (document) from the database. Every resource has a template which is the surrounding HTML for the page.

Once it has the resource, MODX gets its designated template from the database. The template contains MODX tags which pull things into the page. All tags take the format [[...]]. There's a token at the beginning of the tag that tells MODX what kind of tag it is. A chunk tag looks like this: [[$chunkName]].

Chunks contain blocks of HTML. When MODX sees a chunk tag, it replaces it with the content of the named chunk. In PHP code, MODX can also get the content of the chunk with $modx->getChunk('ChunkName'). The chunk may also contain tags.

In MODX, no PHP code is allowed in chunks or resource content. PHP code is held in a snippet and used on a page with a snippet tag: [[SnippetName]]. MODX replaces the snippet tag with the return value of the snippet code, which is always a string.

There are also Resource Content tags and placeholder tags. A Resource Content tag looks like this: [[*fieldName]], and is replaced by the value of the named field of the resource (e.g., pagetitle, content, description). Placeholder tags look like this: [[+placeholderName]]. Placeholders are usually set by the code of a snippet. MODX replaces the placeholder tag with the value of the named placeholder.

If this is confusing, it should become clearer as we create the form using these elements.


Creating the Contact Form

To make our form work in MODX, we're going to create a template, a resource (document), a chunk, and a snippet with PHP code to both display and process the form.

This is not going to be a very sophisticated form. There's no JavaScript (though there could be), not much styling, and no validation of the fields other than making sure they're not empty. It won't even send the email. The point is just to demonstrate what a working acceptance test looks like.


The Template

We could use the default template from our MODX install, but it's quite a bit heavier than what we need and fairly slow to load, so we're going to create our own.

Log into the MODX Manager by going to http://localhost/test/manager and entering your credentials (JoeTester/TesterPassword). Once you're in the Manager, click on the "Elements" tab at the left. Then right-click on the "Templates" section and select "New Template." Put MinimalTemplate in the "Name" field, and the following code (also available at GitHub, here) in the "Template Code (HTML)" text area, then click on the "Save" button.

<!doctype html>
<html lang="en">
<head>
    <title>[[*pagetitle]] - [[++site_name]]</title>
</head>
<body>
    <div style="padding:40px;">
        <h2>[[*longtitle]]</h2>
        [[*content]]
    </div>
</body>
</html>

In the title section above, the title is set with a Resource Content tag for the pagetitle and a System Setting tag for the site name.

In the body, the H2heading brings in the longtitle field of the resource, and just below it, the resource content field for the main section of the form (more on those in the next section).


The Resource

Switch to the "Resources" tab at the left of the Manager. Right-click on the Website folder, and select "Create->Document." That will take you to the Create/Edit Resource panel to create a new resource (document).

Put ContactForm in the "Title" field. On the right, Click in the "Uses Template" drop-down and select the Minimal Template we created in the last section.

Put Contact Form (with a space) in the "Long Title" field and contactform (all lowercase, no spaces) in the "Resource Alias" field.

Finally, put just this tag in the large "Content" field:

[[!ContactSnippet]]

Double-check the steps above because the form may not work if any of them are wrong.

Finally, click on the "Save" button.

You might have suspected that the resource's Content field would contain the HTML for our form. Most of that will be in our chunk, and will be pulled in by the ContactSnippet snippet code referred to in the tag in the Content section. This will allow us to present the form, inject error messages into it, and process the form.


The Chunk

Switch back to the "Elements" tab at the left of the Manager. Right-click on the "Chunks" folder and select "New Chunk." Put ContactChunk in the name field, and this HTML code in the "Chunk Content (HTML) field (also available at GitHub, here).

<p>To contact us, please fill out the following form and click on the send button.</p>

[[+error_message]]

<form method="post" action="">
    <br>
    <label for="user_name">Name: </label>
    <input type="text" id="user_name" name="user_name" value="[[+user_name]]">

    <br>
    <label for="user_email">Email: </label>
    <input type="text" id="user_email" name="user_email" value="[[+user_email]]">

    <br><br>
    <label for="user_msg">Message: </label><br>
    <textarea id="user_msg" name="user_msg" rows="10" cols="70">[[+user_msg]]</textarea>

    <br><br>
    <button type="submit" id="submit_button" name="submit_button"
            value="submitted">Send Message
    </button>
</form>

Click on the "Save" button.

The error_message placeholder tag near the top will be used by the snippet to add an error message if any form fields are empty. If no matching placeholder is set, MODX will replace that tag with nothing, so nothing will appear there when the form is first rendered.

The three other placeholder tags (one for each input field) will be set by the snippet when there's an error so that when the page reloads, the user won't lose what they've already entered.


The Snippet

Still on the "Elements" tab, right-click on the "Snippet" folder and select "New Snippet"

Put ContactSnippet in the "Name" field.

Put this PHP code (also available at GitHub here) in the "Snippet code (php)" field:

<?php

if (isset($_POST['submit_button']) &&
        $_POST['submit_button'] === "submitted") {
    /* Handle submitted form */
    $errors = array(
        'user_name' => 'Name is required',
        'user_email' => 'Email is required',
        'user_msg' => 'Message is required',
    );

    foreach ($errors as $key => $errorMessage) {

        if (empty($_POST[$key])) {
            $fields = array_merge($_POST,
                array('error_message' =>
                '<p style="color:red">' . $errorMessage . '</p>'));

            return $modx->getChunk('ContactChunk', $fields);
        }
    }

    return "<p>Thank you, we'll respond
        as soon as possible</p>";


} else {
    /* Display Empty Form */
    return $modx->getChunk('ContactChunk');
}

In the code above, we first look at the _POST['submit_button'] value to see if the form has been submitted. If not, we drop all the way to the bottom of the snippet and just return the empty form from our chunk with $modx->getChunk('ContactChunk');.

If the form has been submitted, we check the $_POST array for the values of the three input fields to make sure they're not empty. At the first empty field, the snippet sets the error_message placeholder and the three input field placeholders, and returns the form. The second parameter to $modx->getChunk() is a PHP associative containing the keys and values of the placeholders. For each key, MODX replaces the specified placeholder tag with the associated value.

If no field is empty, the code falls through to the "Thank you" line and that is all that's returned.


Review of the Process

MODX gets the resource that's been requested, then it finds its template and loads it. The Resource Content tags in the template are replaced with values from the resource.

When MODX gets to the snippet tag, it launches the snippet and replaces the snippet tag with whatever the snippet returns. The snippet checks to see if the form was submitted. If not, the snippet returns the chunk with the fields empty. If it was submitted, the snippet check the fields, returning the chunk (after setting the error_message and form field placeholders if any fields are empty.

If no fields are empty, it returns the "Thank you" message.


Running the Test

Now our test should run and make sure the form behaves as it should. In the _build directory, give this command:

codecept run acceptance T12_ContactFormCest

The test should run and produce this message at the end:

OK (1 test, 5 assertions)

If not, review the steps above to make sure you've named everything correctly and filled all the appropriate fields of the objects we created.


Coming Up

In the next article, we'll take a look at logging in to the MODX Manager in an acceptance test.



For more information on how to use MODX to create a web site, see my web site Bob's Guides, or better yet, buy my book: MODX: The Official Guide.

Looking for high-quality, MODX-friendly hosting? As of May 2016, Bob's Guides is hosted at A2 hosting. (More information in the box below.)



Comments (0)


Please login to comment.

  (Login)