How to Add Help Pages & Onboarding to Layers Themes or Extensions

Child Theming, Extension Development

Last Updated: for: 1.5 Time to Read: 5 minutes

Onboarding refers to the process your users go through to get started using your theme or plugin. In Layers and the official extensions, we do this via an activation redirect that sends users to a simple “setup wizard” that takes them through a few brief introductions with videos, and ends up in the Customizer where they can immediately begin using the tools.

In addition to the Oboarding process, you may wish to incorporate a static help page within the WordPress admin so users can easily access written documentation or links to your website and other resources.

In general, we do not allow the removal or modification of the Layers Dashboard from commercial child themes or extensions, but you can easily add your own onboarding and help page to the Layers menu.

If you’re just looking for a way to add your logo in the WordPress admin and hide some menu options for a client site, check out our tips on White-labelling the WordPress Admin.

The method is slightly different in how you inmplement these links from a Layers Extension or Child Theme, but both use add_submenu_page()

From within a plugin class:

Line 3: The menu slug of our Layers menu, which is

layers-dashboard

Line 4: The title of our page, encapsulated in __()

for translation. Our slug constant represents the textdomain value.

Line 5: The name of our menu link as we want it to appear, encapsulated in __()

for translation. Our slug constant represents the textdomain value. The shorter the better.

Line 6: The minimum capability the user must have to access this page. Refer to capabilities in WordPress or use the default edit_theme_options

Line 7: The slug of your page. Make sure this is unique, ie don’t name it “settings” or “get-started”. Slugs are lower-case and must use hypens to separate words.

Line 8: The callback, looking for the instance ($this ) of the load_onboarding function which comes next

Line 12: The load_onboarding  function simply grabs our onboarding page template.

Line 13: We’re using require_once so inside the partial we can use $this  to access the header and footer.

Our  constant LAYERS_DEMO_EXTENSION_DIRis used to path to the plugin directory. You would use your plugin’s constant here.

Now hook it to admin_menu from within your __construct() or __init()  and give it a priority of 60

From within a child theme’s functions.php:

The add_submenu_page()  function takes the following:

Line 4: The menu slug of our Layers menu, which is layers-dashboard

Line 5: The title of our page, encapsulated in __()  for translation. Our slug constant represents the textdomain value.

Line 6: The name of our menu link as we want it to appear, uses __()  for translation

Line 7: The minimum capability the user must have to access this page. Refer to capabilities in WordPress or use the default edit_theme_options

Line 8: The slug of your page. Make sure this is unique, ie don’t name it “settings” or “get-started”. Slugs are lower-case and must use hypens to separate words.

Line 9: The callback function that will hold our page template location

Line 14: Create the callback function using a unique name.

Line 15: Pull in the page template (located in our child theme’s includes folder) using get_stylesheet_directory()

Line 18: Hook your menu function into admin_menu and be sure to set a priority of 60 or higher.

For both onboarding or free-form admin pages, your template only requires one thing, which is the section  wrapper with the l_admin-area-wrapper   class:

What you put inside the wrapper is up to you. In general though, keep the following things in mind:

  1. Your admin page should not directly compete with the Layers Marketplace page (but you can certainly link/showcase your own products)
  2. Admin pages should not contain any Theme or Plugin Options that affect the front-end – put these in the Customizer using Customizer controls instead!
  3. Plugins with special plugin-specific settings (that are not linked to front-end display such as our DevKit options) should be linked from the Settings menu rather than the Layers menu.

In most cases, Layers Child Themes do not need additional onboarding and will be sent to the core setup wizard found under Layers Get Started, but you can use the get-started template as a way to add your own interactive help pages or introduction.

onboarding

Refer to the demo theme or extension files to see how they are put together and can be customized for your project, or use the browser inspector to see the HTML used on the Layers Setup page to produce the guided tour. Because core setup is implemented differently than you do it from a plugin or child theme, you cannot copy the core files to your project to make onboarding work!

Plugins

First we use set_transient() in a new function in our plugin class to create a transient we will reference to determine if the redirect needs to happen or not and give it a priority of 30 to ensure it fires after Layers has loaded.

Then we setup the redirect:

Line 3: We use current_user_can()  to set a minimum capability of manage_options for this page to be displayed, as it contains links you may not want authors or subscribers to access.

Line 4: Here we use get_transient() to check for our layers_demo_extension_activated    transient. This ensures the redirect only happens on activation.

Line 6: With wp_redirect we can use admin_url to set the path to our page by the slug we defined earlier in our add_submenu_page  function. Finally, hook it from inside your __contruct() or __init()

Child Themes

Child Themes will redirect to the Layers Getting Started by default. We really recommend keeping it this way for users who have never used Layers before and would benefit from the introduction. However, if you have customized the Layers onboarding, you can redirect to your page instead with
wp_safe_redirect()
inside a custom function in your theme functions.php

Line 2: This checks to see if the user has just activated the theme from the Themes page. If so:

Line 3: Set the layers_welcome  option to 1 (true) – this option is created by the Layers core.

Line 4: wp_safe_redirect to the admin_url using the page slug we defined earlier in our add_submenu_page function.

Line 7: Hook our function into after_setup_theme and give it a priority of 30 to ensure it runs after Layers.