Building a Killer Custom FAQ Section for Your Plugin

Building a Killer Custom FAQ Section for Your Plugin

Providing a solid user experience is a key aspect of creating any plugin.

This includes intuitive navigation, ease of use, and clarity of features, but even the best plugins have some sub-systems, which may be more complex, or at least raise some questions.

Documentation and FAQ sections are great tools for handling these situations. They don’t just serve to inform the user, but to take the burden of answering these questions off you.

Plugin FAQ
The results of our work – a searchable FAQ section.

In this tutorial we’ll take a look at how we can add a FAQ section into a plugin. We’ll be using admin pages coupled with some jQuery UI magic to create a Q&A section that is instantly searchable from an input box – and no loading times.

Our Plugin Architecture

For the purposes of this tutorial I’ll assume that you have a plugin in place, which creates a top-level navigation menu. I’m pretty much against doing this unless there’s a good reason, but it will serve the purposes of this tutorial better.

For simple plugins I recommend creating a sub-menu item under the settings menu. The admin page created can have a tabbed interface with a FAQ section. This ensures that our plugin gets out of the way when it isn’t needed.

If you don’t have a plugin yet or you need some help, you can use the code below to get started. Make sure to create a folder in the wp-content/plugins directory first. I named mine my-plugin and I pasted the code below into a file named my-plugin.php:

If you activate your plugin you should see a top level menu with a FAQ entry underneath. Don’t forget to create faq.php in your plugin folder. This file is pulled in as the content of the FAQ page.

Plugin Starter

The FAQ Structure

Inside the faq.php file we can create the HTML that will show our questions and answers. See the basic code below for the structure I used:

As you can see, I’ve created a search box at the top and some HTML for questions and answers. I actually used the WordPress FAQ in my example. You can grab the full code from Github.

Styling the FAQ

To style this page we’ll need to add our own stylesheet. In WordPress we do this by enqueueing our CSS file and making sure it is only applied to the admin page(s) we want to use it on.

All styles and scripts used in the admin must be added via a function hooked to admin_enqueue_scripts. The first parameter of this function allows us to target the CSS file to our specific page. This parameter will display the page’s menu slug – which we defined as the 5th parameter in the add_submenu_page() function.

Make sure to create the faq.css file so we can start adding our rules. To make the FAQ items look nice I added the following rules:

Here’s what it looks like after applying the styling rules:

FAQ Item
A FAQ item after we’ve applied our rules.

Let’s make the search section nice and bold as well. Adding a couple of lines to our stylesheet allows us to make a friendly interface for our users to search.

And here’s what it looks like:

Plugin FAQ
The final styling of our FAQ section.

Searching In-Place

We have almost everything we need to make this a searchable FAQ – the missing piece is some JavaScript. The plan is that whenever the user types something into the search box, the answers are narrowed down to relevant ones instantly. Since all FAQ items are loaded on the page this should be easily doable.

First thing’s first, we need to enqueue the script. We’ve already added a style so this will be as simple as adding a wp_enqueue_script() call into our existing my_plugin_assets() function.

Note that I used the last parameter of the function to force the file to load in the footer. It isn’t needed before and would only bloat the site in the header. Once you create the faq.js in the plugin folder you can paste the code below and it will all come together, explanation ensues.

I wrapped everything in an anonymous function to make sure we can use $ sign instead of jQuery throughout. I detect keyup events which fire once the user presses and releases a key. When this happens we grab the currently typed query.

We then go through all tags and see if the query exists within the question. If it does we show that section, if it doesn’t we hode that section – it’s that easy.

At this stage you should be able to type “feature” to narrow the list down to the question about WordPress features. As you press backspace to delete your query all the questions will pop back into existence.

Adding Keywords

One small addition I like to make is adding keywords. The second question is titled “Why Choose WordPress?” but users may well ask “Reasons for choosing WordPress.” If you start typing “reasons,” nothing will come up. Let’s fix this by adding a data attribute to our element which contains a number of key phrases. I added the data attribute data-keywords to the mpf-faq-element element.

Instead of just looking for matches in the title, we’ll add the keywords as well to our Javascript. This is a very simple modification. We grab our keywords using var keywords = $this.data('keywords'); and add the keywords.indexOf( term ) == -1 check to our if clause. Here’s the full JS code.

Conclusion

As you can see, adding a dash of helpfulness to your plugin is not all that difficult. A usable FAQ system will make your users happier and can take a load off the plugin author’s back as well.

If you would like the fully working packaged plugin you can grab it here. Just install and activate it to see the example in your WordPress installation.

If you’ve seen some particularly great FAQ sections or have any tips on how to make them better, do let us know in the comments below.