Create A Welcome Page For Your WordPress Plugin

in Plugin Development

Whenever you install WordPress or upgrade WordPress you get a nice welcome page that shows you some of the features that you've just installed. Some big WordPress plugins do the same thing when you install the plugin or upgrade the plugin you get a nice message to tell you what you've just installed.

This seems like a very nice feature to your user's and it's very easy to achieve.

In this tutorial we're going to learn how to create your own welcome page your WordPress plugins.

How It Needs To Work

The way this is going to work is on the event of when the plugin is activated, we need to store some data to show that the plugin has just been activated. Then when the user is redirected back to the admin area we check for the stored data, if this exists then display the welcome message to the user.

Create The Plugin

First we need to create our plugin, we do this the normal way by adding a new folder inside the plugin folder with a single PHP file with the normal plugin comments.

/**
 * Plugin Name:       Paulund Plugin Welcome Page
 * Plugin URI:        https://paulund.co.uk
 * Description:       Plugin to demo how to create a welcome page for your plugin
 * Version:           1.0
 * Author:            Paulund
 * Author URI:        https://paulund.co.uk
 * Text Domain:       paulund
 */

Plugin Activation Event

On plugin activation we need to store some short tern data we can refer to later so that we know the plugin has just been activated. To store short term data in WordPress it's best to use transients by using the function set_transient( $name, $data ).

To make code run when the plugin is activated you need to use the function register_activation_hook().

register_activation_hook( __FILE__, 'pu_plugin_install' );
function pu_plugin_install()
{
    set_transient( 'pu_plugin_activated', true, 30 );
}

We can now check to see if transient pu_plugin_activated exists in the admin area, if it does then redirect to the Welcome page and delete the transient.

Attach To Actions

There are 3 actions that we need to run code on

  • admin_init - To check for the transient and redirect to the welcome page
  • admin_menu - To register the welcome page
  • admin_head - Add additional styles to the page

All the code I write with WordPress is inside a class so let's create a PHP class to store the code, with the actions inside the constructor of the class.

/**
 * Paulund plugin welcome
 */
class Paulund_Plugin_Welcome
{
    /**
     * Add the min caps used for the plugin
     */
    const min_caps = 'manage_options';

    /**
     * Paulund_Plugin_Welcome constructor.
     */
    public function __construct()
    {
        add_action( 'admin_menu', array( $this, 'create_admin_menus') );
        add_action( 'admin_init', array( $this, 'welcome' ), 11 );
        add_action( 'admin_head', array( $this, 'admin_head' ) );
    }
}

Admin Init Welcome Redirect

On the admin init action it will run the welcome function.

This welcome function will need to check if the pu_plugin_activated transient exists, if it doesn't then we exit the file, if it does then we need to delete the transient then redirect to the welcome page.

/**
     * Check the plugin activated transient exists if does then redirect
     */
    public function welcome()
    {
        if (!get_transient( 'pu_plugin_activated' ))
        {
            return;
        }

        // Delete the plugin activated transient
        delete_transient( 'pu_plugin_activated' );

        // Redirect to the admin welcome page
        wp_safe_redirect( add_query_arg( array( 'page' => 'pu-welcome-page' ), admin_url( 'index.php' ) ) ); exit;
    }

Create And Register The Welcome Page

As we're using the admin area page querystring to display the welcome page we need to register this page in WordPress admin area. The easiest way to do this is to simply create a dashboard page using the function add_dashboard_page. This adds a menu item to the top level of your admin area, so we need to then remove the menu item that will hide the page.

Using the function add_dashboard_page it calls a callback function to display the HTML for the page, this is the HTML that will be displayed for your welcome message.

/**
     * Add the page to the admin area
     */
    public function create_admin_menus()
    {
        add_dashboard_page(
            'Welcome plugin page',
            'Welcome plugin page',
            self::min_caps,
            'pu-welcome-page',
            array( $this, 'welcome_message' )
        );

        // Remove the page from the menu
        remove_submenu_page( 'index.php', 'pu-welcome-page' );
    }

    /**
     * Display the plugin welcome message
     */
    public function welcome_message()
    {
        ?>
        <div id="plugin-header">
            <img class="plugin-logo" src="logo-url.png" alt="Plugin logo" / >
            <h1>Welcome to the plugin</h1>
            <p class="about-text">
                Thank you for downloading the plugin, I hope you enjoy the features it brings to your WordPress site.
            </p>
        </div>
        <?php
    }

Add Additional Styles To The Page

As you're creating your own welcome message you might want to style up the page however you want, this can be done by using the admin_head action and inject any styles you want to the page.

/**
     *
     */
    public function admin_head()
    {
        // Add custom styling to your page
    }

Full Plugin Code

That's all the code we need to display the plugin welcome message, as you can see it's quite easy to do just by using some admin area techniques like registering a new page and using transients to record a plugin activation.

Below is the full code I used in this example, please take it away and customise it for your projects.

<?php

/**
 * Plugin Name:       Paulund Plugin Welcome Page
 * Plugin URI:        https://paulund.co.uk
 * Description:       Plugin to demo how to create a welcome page for your plugin
 * Version:           1.0
 * Author:            Paulund
 * Author URI:        https://paulund.co.uk
 * Text Domain:       paulund
 */

register_activation_hook( __FILE__, 'pu_plugin_install' );
function pu_plugin_install()
{
    set_transient( 'pu_plugin_activated', true, 30 );
}

/**
 * Paulund plugin welcome
 */
class Paulund_Plugin_Welcome
{
    /**
     * Add the min caps used for the plugin
     */
    const min_caps = 'manage_options';

    /**
     * Paulund_Plugin_Welcome constructor.
     */
    public function __construct()
    {
        add_action( 'admin_menu', array( $this, 'create_admin_menus') );
        add_action( 'admin_init', array( $this, 'welcome' ), 11 );
        add_action( 'admin_head', array( $this, 'admin_head' ) );
    }

    /**
     * Add the page to the admin area
     */
    public function create_admin_menus()
    {
        add_dashboard_page(
            'Welcome plugin page',
            'Welcome plugin page',
            self::min_caps,
            'pu-welcome-page',
            array( $this, 'welcome_message' )
        );

        // Remove the page from the menu
        remove_submenu_page( 'index.php', 'pu-welcome-page' );
    }

    /**
     * Display the plugin welcome message
     */
    public function welcome_message()
    {
        ?>
        <div id="plugin-header">
            <img class="plugin-logo" src="logo-url.png" alt="Plugin logo" / >
            <h1>Welcome to the plugin</h1>
            <p class="about-text">
                Thank you for downloading the plugin, I hope you enjoy the features it brings to your WordPress site.
            </p>
        </div>
        <?php
    }

    /**
     * Check the plugin activated transient exists if does then redirect
     */
    public function welcome()
    {
        if (!get_transient( 'pu_plugin_activated' ))
        {
            return;
        }

        // Delete the plugin activated transient
        delete_transient( 'pu_plugin_activated' );

        wp_safe_redirect( add_query_arg( array( 'page' => 'pu-welcome-page' ), admin_url( 'index.php' ) ) ); exit;
    }

    /**
     *
     */
    public function admin_head()
    {
        // Add custom styling to your page
    }
}
new Paulund_Plugin_Welcome();

Upgrade to access all content on Paulund

Members unlock all tutorials and snippets

Access to all downloadable content

Access to code examples before others

Sign Up Now

Already a member? Login here

Subscribe To Newsletter

Get weekly updates to your email