Function Friday #14: include website documentation within the admin area
Every Friday, I’m sharing code snippets that I use to customize WordPress. Feedback/suggestions are always welcome! For more information, check out the first post in the series.
There’s a lot of documentation available for the core WordPress software, but every website’s setup is different, and sometimes additional information is required. When a project’s deliverables include a how-to manual, it’s often done as a PDF that’s totally separate from the website.
I started including the documentation I write in the same place that people will be working on the website: within the admin area itself. This way it never gets lost as a result of staff turnover or file purges.
For custom themes, I’ll add a Theme Options page as its own parent menu item, with a Website Documentation subpage. In this example I wanted to show another use case for this function – adding a “how-to” page to a custom post type called Team Members:
Writing the documentation can take a while, but it’s quick to add to the menu!
The code
The first step is to create a callback function, which contains the content for your new page:
function drollic_team_subpage_callback() { ?>
<div class="wrap">
<h1>Team How-To</h1>
<p>The team members added in this section will display on the <a href="<?php echo get_home_url(); ?>/team/">main Team page</a>. They will appear in alphabetical order.</p>
<h2>Adding a new team member</h2>
<ol>
<li>Go to Team → Add New.</li>
<li>Fill out all relevant fields. Only the Photo and Name fields are required.</li>
<li>To add a team member for internal use only, above the "Publish" button, click Edit next to "Visibility: Public" and change it to Private.</li>
<li>Click the "Update" button.</li>
</ol>
</div>
<style>
.wrap ol ol {
list-style: lower-alpha;
margin-top: 6px;
}
.wrap ol ol ol {
list-style: lower-roman;
}
</style>
<?php }Between the first and last lines, you can add whatever HTML and PHP you’d like to display on the page. <div class="wrap"> should enclose all of your page content to match other admin area pages.
Bonus tip: don’t hard-code domain names in here! Instead, use functions like get_home_url in case the site’s URL changes in future (and your page comes with it).
I’ve also added a <style> block to override some of the default admin styles in WordPress. Because documentation often contains a lot of lists, I’ll use this to clean up list item spacing, add bullets back to unordered lists, and avoid nested ordered lists saying “1, 2, 3…” at every level.
The next step is pulling the contents of your callback function into an actual page:
function drollic_team_subpage() {
add_submenu_page(
'edit.php?post_type=team',
'Team How-To',
'How-To',
'edit_posts',
'team-how-to',
'drollic_team_subpage_callback'
);
}
I’ll break this down one parameter at a time.
'edit.php?post_type=team',The first parameter determines what this new page should be a subpage of. Go to the parent page and note the end of the URL. If you want your subpage to appear under Posts, use edit.php; for Settings, use options-general.php; and so on.
'Team How-To',
'How-To',The next two parameters are the title of the page as it appears in the <title> tag of the page (not on the actual page – you have to include that in your callback function above), and then the title of the page as it appears in the sidebar menu. These can be the same, or you can make the second one shorter to fit in the sidebar.
'edit_posts',Then you have to decide who will be able to see this page, both in the menu and by navigating directly to the URL. For documentation pages, I figure everyone that’s going to be editing content on the site should see it, so I’ve chosen edit_posts. If you only want the page to display for Administrators, use manage_options instead. You can browse the full list of capabilities from the Codex and choose the most appropriate one.
'team-how-to',Next you get to decide what the slug for this page should be. It’ll be appended to the parent page, so in this case the full URL is wp-admin/edit.php?post_type=team&page=team-how-to.
'drollic_team_subpage_callback'Finally the callback function you created earlier comes in to display the page content.
The last step is hooking this function into the admin_menu:
add_action( 'admin_menu', 'drollic_team_subpage' );Remember to start all function names with a unique prefix (e.g. drollic) to avoid plugin/core conflicts, and to make your subpage slug unique as well.
Where does it go?
If you’re adding a post type or other functionality with a plugin, you can include this code in the plugin too. If you’re adding a subpage to explain some functionality in your theme, the code belongs in that theme’s functions file. More thoughts on where your code should go is in the first Function Friday post.
Resources
- add_submenu_page in the WordPress Code Reference
- Roles and Capabilities: Capabilities in the WordPress Codex
- admin_menu hook in the WordPress Code Reference
Leave a Reply