Plugin for WordPress developers to provide easy "how to use" instructions to their clients.
WordPress developers: ever written awesome custom functions and script work for client’s site? Then you provide said client with instructions – either via printed manual, video tutorials, or even emails – but no matter how many ways you tell them how to use the site you just made for them, they keep asking you for instructions?
I’ve found this is typically because most clients want instructions that appear “in your face”. They like immediate answers to their questions – they don’t want to have to find that file, or search their email for the answers. It’s much faster for them to just call you and ask what to do.
This plugin solves the issue. Now there can be no more excuses for not finding the answers you’ve already supplied for them ad nauseum.
Features
- Version 3.0 now has the option of using a custom tab, or the ability to be integrated in the WordPress “Help” tab.
- Due to popular demand, I’ve added in a new feature where you can add a single instruction to multiple pages.
- Choose the tab (named by your post title), and the “instructable” displays the content.
- Content can be a written list of instructions, or some other form of media.
- Content can be anything you like, and you can use it just like you would any other post – the only difference is, this stuff shows up in the back-end.
- The options page will allow you to set what user level can add/edit/delete “instructables”, as well as allow you to choose whether or not to make the instructions viewable from the front end. You can also choose to make front-end “instructables” viewable to the public, or only to logged-in users. You can also give non-logged-in users “capabilities” to restrict what they see.
- You can set what end user level can view which instructions. For example, you don’t want an Author to see the same instructions for “Edit Posts” that an Administrator would see – it would confuse them. So you can also create content and serve up specific information based on the user level, if you so desire.
Note that upper levels will also see lower-level videos, so keep that in mind while preparing your instructions. I recommend making videos/content specific to the lowest level first, and then build onto that base as you go up the user-level chain of command.
6. Multi-Site capable.
If you have any questions, comments or suggestions for improvement, feel free to contact Shelly at Brass Blogs Web Design. If you prefer Twitter, I’m @brassblogs.
Given that this is free, I offer limited support. Pretty much if you have issues with the plugin working I will do whatever I can to help you fix the issue, but when it comes to customizations, I’m in limited supply. I’ll do what I can, but no guarantees. Pretty much your standard “as-is” application. In all honesty, ask customization questions in the forums – if I can’t help, perhaps someone else can. (If you want to hire me to customize it, that’s another story – feel free to contact me to do so!)
FAQ
The instructions aren’t showing when I use the custom instructions tab.
This actually has to do with jQuery and the character output. The plugin uses jQuery to add the custom tab, as well as pull in the content from the instruction post. If you use double quotation marks, brackets, and a few other types of characters, it will break the jQuery and cause the tab to not show. If you run into these issues, try using an HTML Character Entity to replace the questionable characters in your content. I currently do not have a running list of what characters cause the jQuery in this plugin to break – but I do know that “” and [] will do it if it’s in your content. Replace them with the appropriate HTML Entities (in this example, " for the double quotes and [ and ] for the brackets), and your problem is solved (and the display will be fine).
How do you pull these posts into the front end of the site?
As of version 2.0 – due to the numerous requests I’ve gotten, you can now show them on the front-end of the site if you so desire. Under “Settings > Back End Instructions”, you may now choose to display the instructions on the front end of the site, as well as choose to keep them private (i.e. open them up to the public, or make a user log in before viewing). See the “How to Use” section for further instructions.
PLEASE NOTE
This plugin was created to show these custom posts in the back end of the site, in the administrative area (thus the name of the plugin). The reason I did it this way is because when your client is logged in to the back end of the site, s/he can manage the site content and s/he will be in one single spot and can easily read their instructions without having to flip back and forth between an instructions page and what they are trying to do. The content pages of this plugin were not originally meant to be displayed on the front-end of the site. IMO, it negates the entire purpose of the plugin. If you are looking for a plugin that will create custom post types for you to use on your site, then you’re looking for a different plugin.
But due to numerous requests, I have enabled this capability. I would imagine it’s because you want to be able to see your instruction to see how it’s formatted, etc., for editing purposes. (Or perhaps you just want your clients to stay out of the back end, for whatever reason.) But know that the instructions you view on the front end of your site WILL NOT look like the instructions seen on the back-end, because the ones seen on the front end will use your theme’s styling, which the back-end uses the admin styling.
Again, I state: if you are simply looking for a plugin to set up a custom post type that you use on the front end of the site, this is NOT the plugin you want. It was not designed for that purpose, and frankly, it never will be.
Do you have any video content that is already created for the basic WordPress stuff?
I do not.
Believe me, I’ve thought about it. But there’s two reasons that I haven’t done it yet… 1) it takes up a lot of time that I don’t have at the moment, and I’d really have to soleley dedicate a few days to creating all of those videos. I deliver this plugin for free (because I love you all), but I do have to put food on the table, so client work takes precedence. 2) WordPress is upgraded quite often, and many times, the administrative area changes, so the videos are quickly outdated. So along with reason #1, I’d have to take off time every time WordPress is upgraded. Which I wouldn’t mind doing if I could!
Any other questions?
By all means, feel free to ask away. I’d also love input on features you’d like added or things you’d like to see to improve this plugin. See the “Credit” information on how to contact me.
Notes
-
This plugin uses custom post types to create the content for it. If you decide you no longer wish to use this plugin, you need to decide what you’d like to do with the content. If you want it completely removed from the database, then before you uninstall it, you need to go to “Instructions” and check the box to “Move to Trash”, and then “Apply.” Then you need to go the the trash and empty it to be sure the posts are completely removed from your database – THEN uninstall the plugin. If you want to keep the content as regular posts, then you will either manually have to edit your MySQL backup to change them from “instructions” to “post” (just open the database backup in a plain-text editor do a find/replace, save, and re-import), or use a plugin like Post Type Switcher to handle that for you before you uninstall. Otherwise, it’ll all just stay there and hang out, with no way to see it until you re-install the plugin again, or code your theme to pull the content out of the database to display it on the front end.
-
If you’re in the mood to translate, please feel free to do so. I’ve created a base .pot file in the “back-end-instructions/bei-languages” folder. You can use POEdit to create the new file – just be sure to keep the proper WordPress language file naming conventions in mind. (in other words, if you create a Spanish translation, the file name should be “back-end-instructions-es-ES.mo”
Known Issues
- Bug with swapping instructions that contain playing videos. So far, I can only get YouTube videos to stop on tab switch. .swf, Vimeo and other player versions are still buggy in this regard. If you change tabs, the video of the previously-opened tab will continue to play in the background. So you have to be sure to stop the video before you change tabs. If you’re a guru at jQuery, and feel like you might know the solution, have at it! In the meantime, I’ll still be plugging away, trying to sort this out.
ChangeLog
3.1.1
- Bugfix – search in the back end was messed up.
3.1
- Bugfix – renamed a variable that was causing a conflict with other plugins.
- Added German and Spanish translations. I don’t speak German or Spanish, so if I’m off, please feel free to edit 🙂
3.0
- made a few security fixes
- updated the options table
- removed the addition of the “first post” since it’s really unnecessary
- re-added the “Instructions” tab – but now it’s optional
- heavy rewrite of code to clean up and streamline
- added css admin files (for custom “Instructions” tab to match user settings admin colors)
- fixed the replacement brackets for shortcodes (“{{ }}”) so the front-end instructions no longer parse them
2.5.2
- Bugfix: swapped a custom loop for a custom query to fix a reported conflict with a WooThemes theme.
2.5.1
- Bugfix: missing variable.
2.5
- pluggable.php won’t load until after ALL plugins have loaded, and only if needed.
- removed the bei_query_vars function, as it was causing issues with filtering posts in the admin. (It was a function put in a long time ago to make sure the instructions ddn’t show up in search results – but the function is no longer necessary as it’s taken care of in the options page)
- Fixed a jQuery conflict that was causing the “+” fields to not work.
- Fixed issue with “xxxx characters of unexpected output” upon activation.
- Updated “How To” video to show the new features, etc. (the old one was causing confusion – pardon my laziness!)
- Fixed it so the initial “How To Use Back End Instructions” post isn’t indexed in the search engines, because no one wants that.
2.4
- Finally fixed the issue of the Instructions post type not showing up when WordPress SEO is installed and activated.
- Fixed issue where radio buttons don’t function in setting page when the Ultimate TinyMCE (by Josh Lobe – tested version 4.0.3, which was the only version I have access to) plugin is used.
2.3
- Discovered an issue where instructions that were created before version 2.2 would not show up anywhere after the upgrade. My bad. Variable misnaming. It’s now fixed.
2.2
- tested in WordPress 3.5-alpha, minor bug fixes and code cleanup for the upcoming WordPress release.
- tested in a Multi-Site environment, seems to work fine. (Please contact me if you find out otherwise, because my tests are only in a localhost environment.)
- removed stylesheets because they actually aren’t necessary anymore
2.1
- some commits didn’t take – partial upgrade. Trying again to get all the right files in there.
2.0
- Further streamlined and updated code, removed unnecessary stuff. This makes this version of the plugin unusable for WordPress versions below 3.1.
- Created options page for defaults
- Can now provide shortcode instructions without parsing the shortcode.
- Set up an option to allow you to display instructions on front end.
- Set up an secondary option to make instructions that are shown on the front-end visible to everyone (public) or only to logged-in users (private).
- Fixed the translation stuff by creating .pot file for easier translation, removed default .mo and .po files.
- added capability for popping in an instruction to a list of specified pages.
- edited the output in regards to the video: you can now show video AND text, instead of having the video replace the text.
- updated/cleaned up readme.txt file.
- created a banner for the plugins page (just for fun)
1.1
This is an “idiot’s release” – I committed changes before I was supposed to – and committing uncovered bugs I didn’t forsee. Totally my bad!
1.0
- updated code to streamline and make it more efficient.
- added an option to the database to check if the plugin is installed so the initial “How to Use” post isn’t created over and over again, even after deletion.
- updated/cleaned up the readme file.
- removed the CSS and embed_loader files and folders.
- updated the video embedding to use HTML5 Video.
- because I’m an idiot and forgot to add the mo-po files for translation, I’ve added the mo-po files for translation.
- it was pointed out to me that these items can be included in front-end search results. This issue is now fixed for both future and past installations.
- cleaned up CSS to make it better match the default styling (classic admin theme)
- fixed it so you don’t see the flash of expanded content on page load (before the stylesheet kicks in and hides it)
0.8
- further fixed “Notice” warnings – especially when adding a new one. *NOTE: there is some kind of bug with WordPress, custom fields, and auto-save. If your error-reporting is on, the AJAX responder in WP will show an error in a pink box. Don’t worry about the error – it’s just an annoyance for now, and only shows up when you add a brand-spankin’ new instruction, after you give it a title. Everything still works fine.
- Changed custom post type to reflect where you are (i.e. change “Add New Post” to “Add New Instruction”, etc.)
- removed the need for an additional plugin to hide the instructions menu option from lower-level users. Now anyone with “Editor” or “Administrator” level access will see the menu option, but anyone below that level will not.
- removed the extra “Summary” section, since it’s redundant. The Excerpt area works as the descriptions, and instead of having the post content replaced by video content, it’ll just add to the video content, if so desired.
- fixed it so you can specify a particular back-end page, or just a general area for an instruction to appear. (i.e. if you want soemthing to appear on “post-new.php” just enter that in the “Page Name” area, but if you want the instruciton to only appear on the “Add New Instruction” pagem, and not the regular “Add Post” pages, you put in “post-new.php?post_type=instructions”.
- added easier styling capability.
0.7
- fixed issue where people were receiving “Notice” information when they had error_reporting turned on. These warnings were due to empty variables. (Once information was put in, they would go away, but on initial acitvation they would show because no info had been put in yet.) A minor annoyance that didn’t affect the functionality of the plugin – now taken care of.
0.6
- fixed issue where instructions were not showing up on individual posts (post.php)
- repaired path to css and script files
0.5
- added video and inserted a default post to show an example of use
- double-checks and cleaning/fixing errors (mostly spelling and clarification) – finalizing for official release
0.4
- fixed issue with other plugins that call pluggable.php and cause a conflict
- added capability for targeting custom post types
- added capability to use vimeo
0.3
- tested for WordPress 3.1
- cleaned up/streamlined terminal code
0.2
- Fixed issue where instructions for the dashboard wouldn’t show up upon initial login (dashboard).
0.1
