Kooboo CMS Module Creation and Development

Summary

This is a quick introduction to Module development for Kooboo CMS. I ran into a few issues while I was trying to follow the official guide so I thought I would document the process for future reference.

Pre-Requisites

You will need Visual Studio (2010 or 2012) installed with the most up to date version of the .NET Framework and ASP.NET MVC. If you haven't already please follow the Kooboo CMS Installation Guide to download the latest version of the code and install the templates for Visual Studio.

Create a Module

Open Visual Studio and start a new project using the "Kooboo.CMS.ModuleArea" template you installed, you can find it under Templates->Visual C#->Web. Choose whatever name you'd like as well as the usual options when starting a project and click OK. After your project is created and initialized go ahead and run a build (press F6) before changing anything. When I do this I see 4 errors in the "~/Areas/SampleModule/ModuleAction.cs" file so let's open that up first to fix these. The errors are just references that can't be resolved so go ahead and prefix "Sites.Models.Site site" with "Kooboo.CMS" to end up with "Kooboo.CMS.Sites.Models.Site site". Try your build again (F6) and then proceed with dealing with the same reference problems in the next file "~/Areas/Empty/ModuleAction.cs". Let's try building one more time and this time it should succeed. At this point you can build and run (press F5) to see the site working and play around with it if you want to familiarize yourself with it.
Let's try to customize a Module a little to see what the process is like, pick a name for your module keeping in mind once it's published and installed in the CMS it can't be changed. I will use "KBModule" for this example, open up the Areas folder in solution explorer and rename "SampleModule" to "KBModule". Next open up the "ModuleAreaRegistration.cs" file in the newly renamed folder and replace "SampleModule" with "KBModule" (there's a variable and also a namespace reference in here). If you were following along with the original instructions on the Kooboo site at this point you should be able to build and run again, the build will succeed but running is a different story. Let's try to figure out why we get a 500 internal server error while running the code.
If you take a look at the exceptions being thrown while running it's obvious that there's still references to "SampleModule" in the code, since we've renamed it we will need to track these down and replace them with "KBModule". Let's do a Find in Files (Ctrl+Shift+F) for "SampleModule" to see which files still need to be updated. You should find 8 matches in 7 files so go ahead and replace all instances of "SampleModule" with "KBModule". I find it's always a good idea to go in and look at the code instead of simply replacing all automatically to help understand the code and also make sure you're not changing something you shouldn't. In this instance however it's safe to go ahead and just run a Replace in Files (Ctrl+Shift+H). Once you're done you should be able to build and run the code again without any problems.

Testing the Module

Let's build and run the code now, hit F5 and after the site starts up click on the LogOn link in the top right corner. Use the default credentials Username:admin Password:admin and change the Redirect to: Admin page then click Login. Click the SampleSite link in the main area to open it up so you can edit and change settings. If you open up the Articles page for editing (click the right arrow to see the menu) and check the Module it's using it should already be set to KBModule in the 2 place holders. At this point you should check all the settings for the controller (Article) and action (Categories for the menu, List for the main area) used in order to figure out where you can play around to make changes and see them on the sample site.

Breaking down the pieces

Back-end (Admin) Controllers and Views

There are two sample back-end controllers included in the project template:
"AdminController.cs", which has two methods: InitializeModule and GenerateModuleInfo.
InitializeModule is used for exactly what it sounds like, after adding the module to Kooboo if you need to do any kind of initialization before using it here's where you'll add the code. Since the module can be used on multiple sites it's advised to do the initialization here rather than during the installation process. I would also recommend writing your code to ensure it can be run multiple times without any adverse affects. An example would be creating/modifying/populating a table in a database that is used by the Module.
GenerateModuleInfo is used to generate the "module.config" file which is the ModuleInfo Class serialized.
"NewsAdminController.cs", is just a sample controller to demonstrate how to create custom data management instead of using the general content management.
The Views for each of these controllers are located under the usual Views folder in the Admin and NewsAdmin folders.

Back-end (Admin) Menu

The back-end Module menu can be integrated into the Kooboo CMS main menu, to customize it edit the "Menu.config" file. The default items are "Settings", "Initialize" and "News", it's good to note that the permission is also set in this file using the "role" attribute.

Back-end (Admin) Routing

The back-end URL routes are added to the "ModuleAreaRegistration.cs" file which is the same as MVC Areas if you're already familiar with them.

Front-end Controllers and Views

There are two sample front-end controllers included in the project template: "ArticleController.cs", which inherits from ModuleControllerBase and "NewsController.cs", which inherits from Controller
The front-end controllers run on Kooboo CMS Page positions rather than MVC area so they cannot inherit from "AreaController", you can use either "ModuleControllerBase" or the generic "Controller". The difference between the two is "ModuleControllerBase" adds a couple flags and methods that are useful for Module development, if you're starting from scratch then inherit from this class although it's not necessary if you're trying to create a module from an existing codebase.
When you add a module to a Page Position you will have to specify the front-end controller in the entry controller and a method in the entry action. You can also specify this using the admin interface for the module after adding it to your site by changing the default settings. Another option is to specify these in the module.config that is generated from the GenerateModuleInfo method in the Admin Controller.
You can't use the regular Master layout because the module view is only rendered as a piece of the HTML page and it won't be validated. There are a couple helper methods "Html.FrontHtml()" and "Url.FrontUrl" you can use in your front-end views only if you have the necessary access and knowledge of the target site. Otherwise it's recommended to use "Html.ModuleHtml()" and "Url.ModuleUrl()". Take a look at the class "ModuleViewHelperExtension" to see the rest of the methods you can take advantage of (ModuleAjax, AjaxHelper, ModuleHtml, HtmlHelper and UrlHelper).

Front-end Routing

To add or modify the routing in the front-end open up the "routes.config" file. For anyone who's already worked with ASP.Net MVC before this should look pretty familiar. If you need more information on working with this file just use any existing samples you can find for a regular ASP.Net MVC project, there's more than enough information and samples available online.

Publishing a Module

Let's save publishing and using the module in Kooboo for it's own article.

References:

http://www.kooboo.com/docs/Kooboo-CMS/Module-development