DEV Community: Chris Wright

Integrating APIs with Wordpress and Contact Form 7

Chris Wright — Wed, 04 Mar 2020 02:49:47 +0000

Contact Form 7 is an invaluable tool for building forms in Wordpress. My team has been using it for quite some time due to its ease of use and flexibility. Some of the features touted on its plugin page are:

Ability to manage multiple contact forms
Customization of form and mail contents
AJAX-powered submissions
reCAPTCHA support
Akismet spam filtering

While it definitely has some issues we've had to overcome, it is one of the first plugins installed on a new project. One such issue I've personally felt is—despite generally having decent documentation around its core functionality—a somewhat lack of insight around integrating with third party services. In this article I would like to outline an approach I've been using to integrate with external APIs during the submission process.

Hooks

Like all things in Wordpress, Contact Form 7 is built around a series of hooks. These hooks are exposed to us and grant access to seemingly every lifecycle event of a form from admin initialization to submission, tag rendering to validation triggers, and more.

A list of all provided hooks can be found over on hookr.io

add_action( string $tag, callable $function_to_add, int $priority = 10, int $accepted_args = 1 )

If you're unfamiliar with hooks, I'll briefly explain what's happening here. add_action is how we can register a listener for specific events that get emitted by plugins or Wordpress itself. It takes up to 4 arguments:

tag—the event we wish to listen for
function_to_add—a reference to the function that will be invoked for the event. This can a function name, inline function, or class method
priority—when the function shold be called
accepted_args—the number of arguments to pass to the function

More information about actions can be found in the Codex.

Register listener

The hook we're currently interested in is wpcf7_before_send_mail as this represents the last step in the process before mail is actually sent to the recipient. We'll start by registering our listener for this hook:

function on_submit( $form, &$abort, $submission )
{
    // TODO
}

add_action( 'wpcf7_before_send_mail', 'on_submit', 10, 3 );

You may have noticed that we've specified that our callback should receive 3 arguments: the form that was submitted, a flag representing failed submission, and the submission itself. Note that abort is actually passed by reference so that the calling class can use it to cancel the submission if we indicate it should do so.

Now that we've got the setup out of the way we can start integrating with whichever systems we need to.

Integrate all the things

You may have multiple forms (like in my contrived scenario above) and only want to run the integration on a specific form. The form object passed to our callback function is an instance of WPCF7_ContactForm, which means we can examine it to make sure it's the form we're interested in. The simplest way is to compare against the form's ID:

if ( $form->ID() !== 999 ) {
    return;
}

Next we can perform the actual integration. Let's assume all we need is a simple POST request to some endpoint that accepts some fields. Like the form above, the submission object is an instance of WPCF7_Submission and we can use it to retrieve the data submitted to the form.

$data = $submission->get_posted_data();

$data is now an array that contains all of the form information we need, including some additional meta data:

array(15) {
    ["_wpcf7"] => string(3) "999"
    ["_wpcf7_version"] => string(5) "5.1.3"
    ["_wpcf7_locale"] => string(5) "en_US"
    ["_wpcf7_unit_tag"] = > string(13) "wpcf7-f761-o1"
    ["_wpcf7_container_post"] => string(1) "0"
    ["email"] => string(12) "jane@doe.com"
    ["name"] => string(8) "Jane Doe"
}

We can now extract the information we need and pass it to our API:

$email = sanitize_text_field($data['email']);
$name = sanitize_text_field($data['name']);

$response = wp_safe_remote_post(/* your API endpoint */, [
    'body' => json_encode([
        'email' => $email,
        'name' => $name,
    ]),
]);

For the sake of this example, we're going to assume that when there is an issue with the request it returns an error (along with a status code other than 2XX). This should then return an error object that we can check for. If we do encounter an error, we can signal for submission to be aborted.

if ( is_wp_error($response) ) {
    $abort = TRUE;
}

Gotcha

Flagging to abort the submission will only cancel the default CF7 submission processing. If you have other hooks registered they will continue to fire so you need to check if abort has been set in each.

if ( $abort === TRUE || $form->ID() !== 999 ) {
    return;
}

A bit of polish

We now have the basic framework in place but we're lacking a bit of that user experience as the user is not properly notified of any issues. If your API returns user-friendly error messages then you can pass those along to the user with set_response, which will render your message on the form.

$body = wp_remote_retrieve_body($response);
$result = json_decode($body);

$submission->set_response($result->message);

You may also wish to style your form based on its current state. For example, the form could shake momentarily when marked invalid or transition to a confirmation message upon success. To do this, we can set the submission's status property. By default CF7 sets its own statuses and applies classes to the form accordingly: if validation fails then the status is set to validation_failed with the class of invalid.

<form action="..." method="..." class="wpcf7-form invalid">

You can view all of builtin statuses and their classes on the Plugin Directory

You can apply your own classes by setting a custom status along with your message. This will then be applied to the form with a custom- prefix and non-alphanumeric characters replaced with hyphens.

$submission->set_status('api_failed'); // custom-api-failed

Wrapping it all up

For the sake of completeness, here is a look at what all of this looks like put together:

function on_submit( $form, &$abort, $submission )
{
    if ( $abort === TRUE || $form->ID() !== 999 ) {
        return;
    }

    $data = $submission->get_posted_data();

    $email = sanitize_text_field($data['email']);
    $name = sanitize_text_field($data['name']);

    $response = wp_safe_remote_post(/* your API endpoint */, [
        'body' => json_encode([
            'email' => $email,
            'name' => $name,
        ]),
    ]);

    if ( is_wp_error($response) ) {
        $abort = TRUE;

        $body = wp_remote_retrieve_body($response);
        $result = json_decode($body);

        $submission->set_response($result->error);
        $submission->set_status('api_failed');
    }
}

add_action('wpcf7_before_send_mail', 'on_submit', 10, 3);

Final thoughts

Custom integrations may not be common with a plugin as feature-rich as Contact Form 7 but there is occasionally a need for them in real world projects. Hopefully this provides a decent jumping off point for writing your own. If you have to incorporate many solutions then I would recommend registering multiple functions and incrementing their priority to have them fire one after another.

Thank you for taking the time to join me on this adventure! I've recently been delving into Wordpress development and I've found there are some areas which could use more long-form content to really dig in. If there's something you'd like me to cover, or if you have any feedback on this article, leave a comment here or hit me up on Twitter.

Creating Spelunky-style level transitions in Phaser

Chris Wright — Tue, 03 Sep 2019 22:37:04 +0000

My last article turned out to be a bit of a niche topic, so I decided to try my hand at something a little more mainstream. Though we'll still be discussing Phaser (gotta monopolize that niche!), you don't need to read the previous article to follow along with this one.

Today we're going to take a look at how we can implement Spelunky-inspired level transitions in Phaser. You can see the finished product in the live demo and you can find the source code over on Github. We'll start by reviewing the effect and learning a bit about scene events and transitions, then jumping in to the implementation.

The concept

Before we get into the weeds, let's review the effect that we're looking to achieve. If you haven't played Spelunky before (you really should), I've included a video for reference:

Each level starts with a completely blank, black screen, which immediately reveals the entire screen using a pinhole transition. The transition doesn't start from the centre of the screen; instead, the transition is positioned on the player's character to centre your attention there. Exit transitions do the same in reverse — fillingthe screen with darkness around the player.

Let's dig into how we can replicate this effect.

Update Nov 26, 2020 — Here is a preview of the final result:

Scene events

There are many events built into Phaser triggered during the lifecycle of a Scene that give you a lot of control. For example, if you're a plugin author you might use the boot event to hook into the boot sequence of a Scene; or, you may want to do some cleanup when your scene is destroyed or put to sleep. For our purposes, we'll be using the create event to know when our level is ready to be played.

You can listen to events from within your scene like this:

this.events.on('create', fn);

I prefer to use the provided namespaced constants:

this.events.on(Phaser.Scenes.Events.CREATE_EVENT, fn);

Refer to the documentation for more information on Scene events.

Scene transitions

For this effect, we're going to use Scene transitions, which allow us to smoothly move from one scene to another. We can control exactly how this transition behaves by specifying a configuration object. If you've ever worked with tweens then you'll feel right at home as there are similarities between them.

Transitions can be started by invoking the Scene plugin:

this.scene.transition({
    // Configuration options
});

Similar to Scene events, there are corresponding events for the transition lifecycle. These events can be subscribed to directly on the scene. We'll be using the out event to know when a transition is taking place.

this.events.on(Phaser.Scenes.Events.TRANSITION_OUT, fn);

The arguments for transition event handlers subtly change from event to event. Refer to the documentation for details.

Putting it all together

The first step is to create an empty base class. It is not strictly necessary to create a separate class but doing so will help isolate the code and make reusing it across levels easier. For now, just extend this bare scene; we'll flesh it out as we go along.

class SceneTransition extends Phaser.Scene {
    // TODO
}

class LevelScene extends SceneTransition {}

All your base (class)

Now that we have our classes in place, we can begin filling them out. Start by using the Graphics object to create a circle and centre it in the scene. The circle should be as large as possible while still being contained within the scene, otherwise the graphic will be cropped later on. This also helps minimize artifacts from appearing along the edges during scaling.

const maskShape = new Phaser.Geom.Circle(
    this.sys.game.config.width / 2,
    this.sys.game.config.height / 2,
    this.sys.game.config.height / 2
);
const maskGfx = this.add.graphics()
    .setDefaultStyles({
        fillStyle: {
            color: 0xffffff,
        }
    })
    .fillCircleShape(maskShape)
;

You should end up with the following:

Next we're going to convert the mask graphic to a texture and add that to the scene as an image. We don't want the mask graphic itself to be visible in the final result, so make sure to remove the fill.

// ...

const maskGfx = this.add.graphics()
    .fillCircleShape(maskShape)
    .generateTexture('mask')
;
this.mask = this.add.image(0, 0, 'mask')
    .setPosition(
        this.sys.game.config.width / 2,
        this.sys.game.config.height / 2,
    )
;

You should now be back to a blank scene. Finally, we apply the mask to the camera.

this.cameras.main.setMask(
    new Phaser.Display.Masks.BitmapMask(this, this.mask)
);

Creating the level

We're not going to spend much time setting up the level itself. The only requirement is that you extend the base class we created and include a key. Get creative!

import SceneTransition from './SceneTransition';

export default class LevelOne extends SceneTransition {

    constructor () {
        super({
            key: 'ONE',
        });
    }

    preload () {
        this.load.image('background_one', 'https://labs.phaser.io/assets/demoscene/birdy-nam-nam-bg1.png');
    }

    create() {
        super.create();

        this.add.image(0, 0, 'background_one')
            .setOrigin(0, 0)
            .setDisplaySize(
                this.sys.game.config.width,
                this.sys.game.config.height
            )
        ;
    }

}

You should now see something similar to this:

Setting up the events

Returning to the base class, we need to record two values. The first will be the minimum scale that the mask will be; the second is the maximum.

const MASK_MIN_SCALE = 0;
const MASK_MAX_SCALE = 2;

The minimum value is fairly straightforward: to create a seamless transition, we need the mask to shrink completely. The maximum is a little more tricky and will depend on the aspect ratio of your game and what shape you use for your mask. Play around with this value until you're confident it does the job. In my case, my mask needs to be twice its initial scale to completely clear the outside of the scene.

Next we can (finally) leverage those events from earlier. When a transition is started, we want to animate the mask from its maximum scale to its minimum. It would also be a nice touch to have the action paused to prevent enemies from attacking the player, so let's add that in.

this.events.on(Phaser.Scenes.Events.TRANSITION_OUT, () => {
    this.scene.pause();

    const propertyConfig = {
        ease: 'Expo.easeInOut',
        from: MASK_MAX_SCALE,
        start: MASK_MAX_SCALE,
        to: MASK_MIN_SCALE,
    };

    this.tweens.add({
        duration: 2500,
        scaleX: propertyConfig,
        scaleY: propertyConfig,
        targets: this.mask,
    });
});

Once the next scene is ready we want to run the animation in reverse to complete the loop. There are a few changes between this animation and the last that are worth discussing, primarily around timing. The first change is the duration of the animation; it has been roughly halved in order to get the player back into the action faster. You may have also noticed the addition of the delay property. In my testing, I found that the animation can look a bit off if it reverses too quickly. So a small pause has been added to create a sense of anticipation.

this.events.on(Phaser.Scenes.Events.CREATE, () => {
    const propertyConfig = {
        ease: 'Expo.easeInOut',
        from: MASK_MIN_SCALE,
        start: MASK_MIN_SCALE,
        to: MASK_MAX_SCALE,
    };

    this.tweens.add({
        delay: 2750,
        duration: 1500,
        scaleX: propertyConfig,
        scaleY: propertyConfig,
        targets: this.mask,
    });
});

Triggering a transition

So far we have very little to show for all of this setup that we've done. Let's add a trigger to start a transition. Here we're using a pointer event in our level but this could be triggered by anything in your game (e.g., collision with a tile, the result of a timer counting down, etc.).

this.input.on('pointerdown', () => {
    this.scene.transition({
        duration: 2500,
        target: 'ONE',
    });
});

If you tried to trigger the transition, you may have noticed that nothing happens. This is because you cannot transition to a scene from itself. For the sake of this example, you can duplicate your level (be sure to give it a unique key) and then transition to that.

And that's it! You should now have your very own Spelunky-inspired level transition.

Conclusion

Level transitions are a great way to add a level of immersion and polish to your game that doesn't take a whole lot of effort. Since the effect is entirely created by applying a mask to the Camera, it could easily be modified to use, say, Mario's head to replicate the effect found in New Super Mario Bros. Or if you're feeling more adventurous (and less copyright-infringy) you could create a wholly unique sequence with subtle animation flourishes. The only limit really is your imagination.

Thank you for taking the time to join me on this adventure! I've been having a lot of fun working on these articles and I hope they come in handy for someone. If you end up using this technique in one of your games or just want to let me know what you think, leave a comment here or hit me up on Twitter.

Loading server-generated Tilemaps with Phaser

Chris Wright — Sat, 29 Jun 2019 21:56:42 +0000

Phaser is a fantastic framework for creating games with web technologies. There are many features built in that make creating games a breeze. One of my favourites is Tilemaps. Whether you're developing a side-scrolling platformer or an epic turn-based RPG, you'll likely need to take advantage of Tilemaps to render your level. I'd like to touch briefly on how to work with them and then demonstrate how to leverage an API to dynamically serve level information.

Note: This article contains a brief primer for working with Loaders and Tilemaps in Phaser. If you're already familiar with these concepts, feel free to jump to the good stuff.

File Loaders

Phaser makes it incredibly easy to load a variety of file types into your game using Loaders. There are many built-in Loaders for primitive file types like images and audio, as well as for custom Phaser objects like Spritesheets, Plugins, and Tilemaps. We'll be focusing on the Tilemap Loader for our purposes, but feel free to check out all of the possible Loaders in the Labs.

Each time you invoke a Loader, you are required to pass in a key and a path to the file (there are exceptions to this but let's pretend that's not the case right now). The key must be unique as it will be used to reference the loaded asset later on. Below is an example of what this may look like (using a map exported from Tiled):

function preload () {
    this.load.tilemapTiledJSON('map', 'data/map.json');
}

You can load as many assets as required by your game, though this will impact your load time. Be sure to optimize your assets as much as possible so you don't keep your players waiting.

Note: Although it is technically possible to load assets anywhere in your game, it is recommended that you load all of your assets in your Scene's preload method as the loading process will be automatically started for you. If you choose to do so elsewhere, be sure to call the Loader.start method. For more information, check out the LoaderPlugin docs.

Creating a static Tilemap

Before we're ready to create our first Tilemap, we'll first need to load in a Tileset. We can expand our preload method to include our Tileset asset:

function preload () {
    this.load.image('tiles', 'assets/tileset.png');
    this.load.tilemapTiledJSON('map', 'data/map.json');
}

Now we're ready to go!

Once again, Phaser is looking out for us with its amazing built-in support for working with Tilemaps. The possibilities are endless but let's concentrate on the basics for the time being. Don't blink while reviewing the following snippet; you might miss it:

function create () {
    const map = this.make.tilemap({
        key: 'map',
    });
    const tileset = map.addTilesetImage('tileset', 'tiles');
    const layer = map.createStaticLayer(0, tileset);
}

And that's really all it takes to create a basic Tilemap in Phaser. First, we make a new Tilemap (note the key corresponding to our JSON file), add a tileset using our image, and create a static layer. You should now see your map in your Scene.

We've glossed over many aspects of working with Tilemaps in order to get to the real meat of this article. I definitely recommend you check out the comprehensive list of demos over in the Labs, including examples of how to handle things like collision and multiple layers. If you're feeling particularly adventurous, try your hand at Dynamic Tilemaps.

Loading server data

Sometimes you may not want to use a single map in your game. Maybe you want the user to be able to select from a large pool of available maps but don't want to bloat your bundle size. Or maybe you want to cycle maps out on a regular interval but don't want to force the user to download constant updates every time. We can solve these problems by having maps downloaded from a server on demand.

Remember the exception earlier where we noted that you must provide a file path to the Loader? As it turns out, you're not limited to just linking to static files. You could, for example, build an API that returns the required JSON. Let's explore that now.

Note: I'll be using micro to quickly bootstrap an API but you can use anything you'd like.

We'll need the most barebones project you've ever seen. Create a new project and include a copy of your static map JSON. You should end up with a structure similar to this:

|- index.js
|- map.json
|- package.json

Your index.js should look like the following snippet. If you're using a different setup then be sure to do the equivalent. The idea at this point is just to read in the static file and return its contents with the request.

const map = require('./map.json');

module.exports = (req, res) => {
    res.setHeader('Access-Control-Allow-Origin', '*'); // You should probably change this

    return map;
}

Finally, start the engines:

npx micro

If all is well, you should be able to visit your API and have the map data be returned to you. Next, we'll need to update our preload method:

function preload () {
    this.load.image('tiles', 'assets/tileset.png');
    this.load.tilemapTiledJSON('map', 'http://localhost:3000'); // Be sure to update the URL with your own
}

You should still see your map, exactly as you had before. Let's spice it up a little bit.

Choose your own adventure

The next logical step is to be able to load different levels depending on user action (e.g., selecting a level from a menu, progressing to the next after beating a level). Updating the API to support this will be trivial with our current setup. Let's update our API to accept a level selection as part of the query string.

const qs = require('qs');
const url = require('url');

const level1 = require('./level1.json');
const level2 = require('./level2.json');

module.exports = (req, res) => {
    res.setHeader('Access-Control-Allow-Origin', '*');

    const {
        level = 1,
    } = qs.parse(url.parse(req.url).search, {
        ignoreQueryPrefix: true,
    });

    if (level === 2) {
        return require('./level2.json');
    }

    return require('./level1.json');
}

Admittedly, this continues to be a rather naive implementation, but it demonstrates the basic concept. Our API now accepts a level to load. At the moment, the only level we can request is level 2, as everything else will default to the first level. Now, how can we use this in our game?

Scenes in Phaser can be initialized with data when they're started. We can then store that data for later use. In the example below, I've opted to use the registry to store the data, but you can use whichever approach you prefer.

function init ({ level }) {
    this.registry.set('level', level);
}

function preload () {
    // ...

    const level = this.registry.get('level');
    this.load.tilemapTiledJSON('map', `http://localhost:3000?level=${level}`);
}

Note: No default is required here; the API will take care of that.

The last piece of the puzzle is to trigger the level load. The first time our game is run, the level stored in the registry will be undefined so the API will know to return the first level for us. In our hypothetical situation, let's assume the user has completed the level and is now shown a prompt to continue to the next level.

this.input.keyboard.once('keyup_SPACE', () => {
    const level = this.registry.get('level');

    this.scene.restart('level', {
        level: level + 1,
    });
});

The Scene will now restart with the next level set. Alternatively you could set level to 1 in the case of a game over scenario, or even transition to a random bonus level on item pickup.

Conclusion

Traditionally you would have to ship your game with all of its level data bundled in. With this technique, that doesn't always have to be the case. I don't think every game should be architected this way, but it could be useful for those that have a level editor, utilize procedural generation in some way, or offer cross-device play.

Thank you for taking the time to join me on this adventure! I've been wanting to try my hand at writing an article for years and it's never quite worked out until now. Let me know what you think in the comments or over on Twitter.