{"id":136843,"date":"2015-02-04T08:00:31","date_gmt":"2015-02-04T13:00:31","guid":{"rendered":"http:\/\/premium.wpmudev.org\/blog\/?p=136843"},"modified":"2015-02-04T17:58:11","modified_gmt":"2015-02-04T22:58:11","slug":"plugin-welcome-screen","status":"publish","type":"post","link":"https:\/\/wpmudev.com\/blog\/plugin-welcome-screen\/","title":{"rendered":"Creating a Welcome Screen For Your WordPress Plugin"},"content":{"rendered":"

If you’ve ever updated WordPress\u00a0a major version, or you’ve used a popular plugin like BuddyPress, chances are you’ve seen a plugin welcome screen.<\/h2>\n

The purpose of this screen is to get you oriented within the plugin, notify you of changes between versions and to point you to useful and relevant links.<\/p>\n

Creating\u00a0a\u00a0welcome screen is easier than you\u00a0may\u00a0think and provides a great platform to introduce a better\u00a0user experience to your product.<\/p>\n

In this article I’ll show you how to put a welcome screen in place for your plugin. Let’s dig in!<\/p>\n

Welcome Screen Examples<\/h2>\n

I thought it would be a good idea to show you what we’ll be doing first. Take a look at the screenshots below for welcome screens from the most recent versions of popular plugins and WordPress.<\/p>\n

\"WordPress
The WordPress welcome screen after updating to 4.1<\/figcaption><\/figure>\n
\"bbPress
The bbPress welcome screen<\/figcaption><\/figure>\n
\"The
The BuddyPress welcome screen<\/figcaption><\/figure>\n

Creating Your Own Welcome Page<\/h2>\n

Most welcome screens are shown when the user clicks the activate link after installing a\u00a0plugin. Since there is no mechanism to modify where that link takes the user we’ll need to resort to some cleverness. Here’s the action plan for our code:<\/p>\n

    \n
  1. Create a dashboard page<\/li>\n
  2. Fill it with content<\/li>\n
  3. Upon activation we’ll add an option to the database<\/li>\n
  4. On each admin page load we check if this option exists<\/li>\n
  5. If it does we’ll redirect the user to a custom page<\/li>\n
  6. Remove the dashboard page menu entry (optional)<\/li>\n<\/ol>\n

    I think seeing the full code for this will be more helpful. I’ll go through all the bits and pieces after the code block below:<\/p>\n

    Loading gist 5c5577dd3fd160da5568<\/a>

    Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n

    The dashboard page is created on lines 26-36. The last parameter defines the function used to display the content: welcome_screen_content<\/code>. Within this function I added some HTML. If you plan on adding a whole lot of stuff in here it may be best to include a separate file.<\/p>\n

    On lines 1-4 I defined an activation hook. This runs only when a plugin is activated. It adds a transient to the database, which indicates that we should redirect to the welcome page. Why a transient? We could well have used a simple option using the add_option()<\/code> function but we want to make sure that everything is air-tight. Transients have a timeout value, I have used 30 seconds. After this time the transient is deleted \u2013 it cleans up after itself.<\/p>\n

    On lines 6-24 we add a function to admin_init<\/code>. This checks if the transient we set exists. If it does exist (and we’re not activating in bulk or from the network admin) the transient is deleted (to make sure the welcome screen is only shown once) and the user is redirected.<\/p>\n

    Finally, on lines 50-54 we remove the menu page entry from view. What this means is that even if the welcome screen is removed, the user will not see a menu entry for it under the dashboard. This is usually done since the welcome screen is not important in day-to-day usage it can safely be removed to declutter the interface.<\/p>\n

    And here’s what the welcome screen looks like:<\/p>\n

    \"Welcome
    A basic welcome screen using the code above.<\/figcaption><\/figure>\n

    Of course, you’ll need to add your own text and styling if you want your welcome screen to look anything like what the developers of WordPress or BuddyPress put together for their products.<\/p>\n

    Wrapping Up<\/h2>\n

    That’s all you need to know\u00a0for creating a customized welcome screen. I’ve packaged the code above into an actual plugin which you can download here<\/a>. Take a look at the source code for the same code as you see in this article.<\/p>\n

    Once done you should make your welcome screen appealing to users by enqueueing scripts and styles. Make sure to add relevant and useful information that orients your viewers, and don’t add flashy sliders and other eye-candy just because you can.<\/p>\n

    Do you know of a plugin with an especially cool welcome screen? Did you manage to use this tutorial in your own product? Let us know in the comments below.<\/strong><\/p>\n","protected":false},"excerpt":{"rendered":"

    If you’ve ever updated WordPress (of course you have!) or installed any number of popular plugins, chances are you’ve come across a welcome screen. We show you how to create your own in today’s post.<\/p>\n","protected":false},"author":344049,"featured_media":137098,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"blog_reading_time":"","wds_primary_category":0,"wds_primary_tutorials_categories":0,"footnotes":""},"categories":[4,263],"tags":[131],"tutorials_categories":[],"class_list":["post-136843","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-plugins","category-tutorials","tag-developers"],"_links":{"self":[{"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/posts\/136843","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/users\/344049"}],"replies":[{"embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/comments?post=136843"}],"version-history":[{"count":1,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/posts\/136843\/revisions"}],"predecessor-version":[{"id":215678,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/posts\/136843\/revisions\/215678"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/media\/137098"}],"wp:attachment":[{"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/media?parent=136843"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/categories?post=136843"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/tags?post=136843"},{"taxonomy":"tutorials_categories","embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/tutorials_categories?post=136843"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}