Building a Welcome Page for Your WordPress Product: Code Part 1

Building a Welcome Page for Your WordPress Product: Code Part 1

In the first two articles of this series, I wrote about what welcome pages are and how they are helping products improve user experience by connecting the dots, after which I wrote about the WordPress Transients API that I intend to use while building the welcome page.

Coding a welcome page for your WordPress plugin can be a tricky process. The entire concept revolves around redirecting users to a particular page via setting transients and finally deleting them. Let's start building the welcome page.

WP Welcome Page Boilerplate

I am going to build a welcome page boilerplate for WordPress in the form of a plugin that could be used within your WordPress product. The final form of this plugin is hosted at GitHub at WP-Welcome-Page-Boilerplate-For-TutsPlus.

At this point, I’m assuming that you have the following set up:

a local machine or a web server

a demo WordPress website dashboard

Plugin Architecture

I'm going to create a simple plugin that displays a welcome page when a user installs and activates the plugin. Let's discuss the plugin architecture:

wp-welcome-page-boilerplate.php: The main plugin file in the root. This file is responsible for defining the global constants and requiring the initializer file, i.e. welcome-init.php.

welcome-init.php: The initializer file which is responsible for three things: adding a transient when plugin gets activated, deleting it when the plugin gets deactivated, and finally adding the logic file, i.e. welcome-logic.php.

The PHPDoc header section of the plugin tells WordPress that a file is a plugin. The defined parameters tell how the data is handled. At a minimum, a header can contain just a Plugin Name, but several pieces can—and usually should—be included. You can read about the header requirements in the WordPress Plugin Developer Handbook.

The next set of code performs a security check. If anyone tries to access this file directly, it runs the ABSPATH check, which terminates the script if accessed from outside WordPress.

I have defined a few global constants which define details about the plugin's version, root folder, URL, and the plugin's main file.

Each of these contains an if( ! defined() ) statement, which helps avoid any errors due to the redefinition of a global constant. I recommend defining the global constants with your package name as a prefix. The package name in this plugin is WPW, i.e. WordPress Welcome. So, every constant has a prefix of WPW_.

The defined plugin constants are:

WPW_VERSION: Plugin Version

WPW_NAME: Plugin Folder Name

WPW_DIR: Plugin Directory

WPW_URL: Plugin URL

WPW_PLUGIN_FILE: Plugin Root File

Once all these constants are defined, we'll begin with the contents of our welcome file.

I like keeping my code minimal, precise, and well documented. So, instead of adding every code block in a single file, I prefer making individual files, each with one purpose only. That is why we have an initializer file which will initialize everything related to the welcome page.

The require_once() statement requires the welcome-init.php file, but before requiring a file, I always check it with the file_exists() PHP function to avoid any fatal errors in case the file gets deleted.

The same principles apply for the welcome logic, which we'll get to later in the next part of the series.

So, now we need to make use of these hooks. I created a transient for the welcome page. The set_transient() function is called inside the custom wpw_welcome_activate() function. In the previous article, we learned that the set operation takes a key, value and an expiration time as its parameters.

Therefore, the key _welcome_redirect_wpw is set to a value true for 60 seconds. This defines the maximum age after which the transient expires.

Next is the activation hook, and as we know this hook runs only when a plugin is activated. It adds our transient to the database. Once the transient is in the database, it means we can check it and redirect the user to our welcome page. How to redirect the user? That's what we will study in the next article.

After that, I wrote the code which runs upon deactivation of the plugin. We want a functionality where the transient gets deleted when a user deactivates the plugin. To do so, I called the delete_transient() function, which takes the key _welcome_redirect_wpw as its parameter. Then there is the wpw_welcome_deactivate() function, which is added to the plugin deactivation hook.

This part is optional, but I want my users to see the welcome page whenever they activate the plugin. If you don't, you can most definitely ignore the deletion of your transient.

So far, I have discussed the part of the code which is necessary to create and delete a transient. But the code for welcome logic is still missing, which would redirect the users to the welcome page. We'll tackle that next.

Conclusion

This is it for today. So, we are halfway through. The base file and the initializer for our welcome page are ready. Now we need to create the logic and view files, which is the plan for the next article.

Finally, you can catch all of my courses and tutorials on my profile page, and you can follow me on my blog and/or reach out on Twitter @mrahmadawais where I write about development workflows in the context of WordPress.

As usual, don't hesitate to leave any questions or comments below, and I'll aim to respond to each of them.