How To Use Kentico Custom Module Help Topics
Recently I was having a conversation with BizStream founder, Mark Schmidt, on how we could simplify the learning curve for using some of the custom functionality that we had created in one of our projects. Mark was on the side of adding custom labels into the pages where needed. I was on the side of trying to leverage the excellent help system that Kentico comes built with. The argument actually got quite heated, as it tends to do around the office, and we finally ended the argument without a real agreement.
The fact is that we frequently create custom modules in Kentico to handle any large customization need. Building your own modules is actually the preferred choice and Kentico best practice when it comes to adding in functionality to a site built with Kentico or the actual Kentico admin interface itself. But neither Mark nor I had actually taken the time to sit down and browse through the lesser known aspect of module development.
This morning I had a chance to do that, and it turns out there is a really simple solution to linking any helpful information or documentation to a custom module. The best part is that the solution was just a few clicks away.
Custom Modules in Kentico are your Friend
As I have mentioned before modules are one the most power tools a developer has in the toolbox for Kentico development needs. I have a few custom modules published here on my blog if you haven't seen one before. For this post though, I am assuming you have some experience with making your own module.
Using a module you can expand, customize, or integrate your Kentico website in all sorts of fun and exciting ways. The official documentation runs you through how to create the module, attach your custom code to it, create a UI Element (the admin interface for it), add the module to the site, and eventually export the module for use in another instance. All good stuff.
But the documentation stops there, and for most uses that is totally fine. However, what if you are creating a module that you want to share with your co-workers, or another organization, the development community, or the whole internet? You might just want to include some documentation on how to actually use the functionality, or more importantly, have some documentation ready for what to do if something goes wrong and/or breaks.
Help Topics to the Rescue
As usual, Kentico is already one step ahead of Mark and I. While we continued to argue over the solution to our problem, we had talked about jamming in some jQuery to hack a solution that may or may not work, or we talked about coming up with our own solution from the ground up. We failed to notice the most obvious choice. That obvious choice being the Help Topics tab on top of the actual User Interface page when configuring any of the UI Elements for our custom module.
Kentico has the ability to add in Help Topics to the context sensitive help system for any UI Element you make in your custom module. Once you add in the topics to the list using the New Help Topic button the help system just works. It is so simple that I wanted to hit myself over the back of my own head for not realizing it before.
You can give each topic a name and a link. If the link is external, the system generates the name of the topic in the help bar, and clicking on the name takes you to the help page in a new window. If the link is no0t external, the system automatically creates a link to the official Kentico documentation with the name of your help topic as a query string value.
Once you have you help topics added to the module, the Kentico admin interface does the rest. That's it. Simply press the F1 key on your keyboard to open up the help, or click the question mark icon on the far right of the interface and you will see your custom help topics when you are on the correct user interface in your custom module.
As you can see the solution to creating a smart help system for your Kentico custom modules is incredibly simple. You are just using the built-in solution that the CMS already has. Next time Mark and I should spend less time arguing and more time just getting our modules completed. By the way if you are looking for answers to question of What Do You Want to do Tonight?, or Will the Lions Ever Win the SuperBowl?, feel free to click on the links.
Also if you got this far in the blog post, that probably means you are someone who is interested in developing Kentico custom modules, or you might be someone who is just generally interested in Kentico. If so, you might want to check out a new tool that my team and I are creating to make deployments easier for Kentico developers, Compare for Kentico. The tool is in open beta right now and free for anyone to use. We'd love to know your feedback on it.