Module development ( v. 4.2 or earlier)

Modularity is the degree to which a system's components may be separated and recombined, for example forums, blogs and social updates.  You can use the Kooboo module for this purpose. Or you need to develop the custom data management interface beside using the default content management.

In Kooboo CMS that is V3.1 or above, module is based on ASP.NET MVC Area. One module contains Controllers, Views, Styles, Scripts, Route settings, Menu items, Module settings, etc. In short, module is a mini site that contains all elements required at runtime.

Similar to the common web site, Module contains the back-end side (for administrator to manage site data) and the front-end side(for user to browse the site). Kooboo CMS module also has these two parts. The difference between a common web site and a Module is that users can access the back-end controllers directly, and Module will be run on the MVC Area. The front-end controllers must be added to the position of Kooboo CMS Page.

Development enviornment

You need Visual Studio.NET to develop a Kooboo CMS module. 

1. Download Kooboo.CMS.ModuleArea.vsi from
http://codeplex.com. Double click it to install the Module project templates into Visual Studio.

Create a Module project using the project template under "Visual C# -> Web", and name the project as MyModule1. The project will be built successfully by default and will be available for browsing.

  1.     Rename the "SampleModule" area to whatever name you want. In this tutorial case, we also call it "MyModule1". The area name also uses the name of the Module. This name cannot be changed after the project is published, because it will take effect in the area URL.
  2.     Open file "ModuleAreaRegistration.cs"( If you used older project template at step 2, then you are supposed to open file "SampleAreaRegistration.cs"), and then rename the word "SampleModule". In this tutorial case, we rename it as "MyModule1".


An empty template will be included in a future version of Kooboo CMS to help you to create your own module quickly.



Add Module to Page

1. if you restart the Module site, you may get the error "The module does not exist.Module name:SampleModule". The cause of the error is that we added the Module front-end controller into site Pages to test if the Module could run on the Pages or not. However, we have changed the Module name(Area name) to "MyModule1", so this error can be corrected by changhing the Module name on the Kooboo CMS Page editing form.
       

- Type the {url}+"/admin" in the address bar to go to the Site's admin page.
        Edit the "Articles" page and remove all the Modules on the positions of the Page. Then re-add those Modules to the position by following the steps below:

- Add "MyModule1" while selecting the "ArticleCategories" entry on the "sidebar" position. - Add "MyModule1" while selecting the "ArticleList" entry on the "main" position. - Preview the "Articles" page now; you will find that the page is available.

2. When you click the "News" link on the site's navigation, you will get a similar error. To fix it, you can edit the Page as you did on the "Articles" page. There are two entry options: "NewsCategories" will be added to the "sidebar" position on "News" page; "NewsList" will be added to the "main" position on the "News" page. NOTE: To know Modules use which entry controller/action, you can edit the existing Module on the page. You will see the default values on the "Entry controller" and "Entry action". They are the default entries on that position.

 

Create the back-end controllers/views

The back-end controllers are the regular area controllers. In Kooboo CMS Module, the controller is inherited from "ModuleAreaControllerBase" or from "AreaControllerBase" directly. The controller inherited from "ModuleAreaControllerBase" will be added with "ModuleName" property, which is used to get the area name from the URL route, to help you easily use it in the controller actions.

The back-end views are all the same as area views. The back-end controllers have the same graphic as the Kooboo CMS admin panel, so there is a layout called "Shared\Site.cshtml" which has a similar code to the layout in Kooboo CMS. You are free to change the back-end controller graphic if you do not want it to be the same as the Kooboo CMS admin panel.

The pop page is a regular user experience in Kooboo CMS. There is a sample action/view in NewsAdminController to show you how to create pop views. Pop views require the "Shared\Blank.cshtml" layout.

 

Controller

There are two sample back-end controllers in the project template:

  • AdminController.cs It has two special actions: InitializeModule and GenerateModuleInfo.

                 -  InitializeModule is used to do the Module initialization, e.g. initializing DB tables, on the site. This Module can be used in multiple sites, so you cannot do the initialization during the installation process. However, you can do the initialization on different sites individually. 

                  -  GenerateModuleInfo is used to generate the "module.config" file by code.

  • NewsAdminController.cs is a sample controller that demonstrates how to create custom data management instead of using the general content management.

 

Url route

All the back-end URL routes are added into the "ModuleAreaRegistration.cs", which is the same as many MVC areas.

Menu setting

The back-end Module menu can be integrated into the Kooboo CMS main menu. The menu items can be customized in "Menu.config".

Create the front-end controller/views

The front-end controllers run on Kooboo CMS Page positions rather than on MVC area. They cannot be inherited from "AreaController", but can be inherited from "ModuleControllerBase" or "Controller" directly.

  • If the front-end controllers are inherited from "ModuleControllerBase", you will get settings that are more convenient to be used.

 public class ModuleControllerBase : Controller
    {
        public virtual bool EnableScript { get; set; }
        public virtual bool EnableTheming { get; set; }
        public ModuleContext ModuleContext { get; }
        public ControllerContext PageControllerContext { get; }
    }
 

  •      If the front-end controllers are inherited from "Controller", you can make its existing MVC site as Kooboo CMS module more flexibly.


When the front-end controller returns a JsonResult/FileResult/ContentResult, it will clear the rendered content, output the result, and return it to the request. The front-end controllers can be added into different Page positions. When you add a front-end controller into a Page position, you will have to define an entry controller/action to specify the action that will be executed when the Page is loaded the first time, or you can just simply select corresponding entry options on "moduleInfo.EntryOptions".

You cannot use the regular Master Layout because all the front-end view will only render part of HTML string at the position, and the HTML will not be validated.

You can use "Html.FrontHtml()" and "Url.FrontUrl()" on the front-end view if you are sure about the target site structure. You can generate the Page link from Module, and other practices on the Kooboo CMS Views. Otherwise, if you want to do redirect to different pages in the same module, you have to use "Html.ModuleHtml()" and "Url.ModuleUrl()". The other module helpers have:

public static class ModuleViewHelperExtension
    {
        public static AjaxHelper<TModel> ModuleAjax<TModel>(this AjaxHelper<TModel> ajaxHelper);
        public static AjaxHelper ModuleAjax(this AjaxHelper ajaxHelper);
        public static ModuleHtmlHelper<TModel> ModuleHtml<TModel>(this HtmlHelper<TModel> htmlHelper);
        public static HtmlHelper ModuleHtml(this HtmlHelper htmlHelper);
        public static UrlHelper ModuleUrl(this UrlHelper urlHelper);
    }

 

Configuration

module.config

The module.config is the module configurations generated by "Admin/GenerateModuleInfo". It is serialized from Class ModuleInfo.

 [DataContract]
    public class ModuleInfo
    {
        public static string ModuleInfoFileName;
 
        public ModuleInfo();
 
        [DataMember(Order = 7)]
        public ModuleSettings DefaultSettings { get; set; }
        [DataMember(Order = 9)]
        public EntryOption[] EntryOptions { get; set; }
        [DataMember(Order = 3)]
        public string KoobooCMSVersion { get; set; }
        public string ModuleName { get; set; }
        [DataMember(Order = 1)]
        public string Version { get; set; }
 
        public static ModuleInfo Get(string moduleName);
        public static ModuleEntryPath GetModuleInfoPath(string moduleName);
        public static ModuleSettings GetSiteModuleSettings(string moduleName, string siteName);
        public static void Save(ModuleInfo moduleInfo);
        public static void SaveModuleSetting(string moduleName, string siteName, ModuleSettings moduleSettings);
    }
 

 Menu.config

The back-end menu items can be modified by developers manually. The default content is as below:

 
<?xml version="1.0"?>
<menu>
  <items>
    <add name="Settings" text="Settings" action="Index" controller="Admin" visible="true" role="administrators" >
      <items>
        <add name="Initialize" text="Initialize" action="InitializeModule" controller="Admin" visible="true" ></add>
      </items>
    </add>
    <add name="News" text="News" action="Index" controller="NewsAdmin" role="content manager"></add>
  </items>
</menu>
 

Note: The "role" attribute indicates which user role has the permission to view this item.

 routes.config

The routes.config is front-end routes settings, with which you can create some friendly front-end URLs.

WebResources.config

The WebResources.config has the same content with "Sites\WebResources.config". It is used in the "Shared\Site.cshtml".

Publishing

You can publish Kooboo CMS Module in the same way as publishing regular ASP.NET MVC Application.

1. Right click the module project, select "Publish".

    

2. Locate to the publishing path, copy the "bin" folder into "Areas\MyModule1".

3. Remove files under "Areas\MyModule1\Bin", except "Kooboo.CMS.MyModule1.dll", and its dependent assemblies.

4. Compress the folder "Areas\MyModule1" into a zip file named "MyModule1.zip". Note: The zip file name needs to be the same as the module name.

Using Module

Installation

     1. Click the "Modules" link on the top menu to entry the module management.

    2. Click the "Install" button on the toolbar to install the Module.

    3. Pick the published module package: "MyModule1.zip".

    4. Click "Next" to upload and deploy the module. The step will spend a bit longer, because it need to copy the module assemblies to BIN folder then restart the Kooboo CMS Site.

    5. Finish.

 Using Module

    1. Go to the Site menu.

    2. Click "Extension=>Modules" to enter into the module list. In the grid, you can "Include" and "Exclude" the module from this site.

    3. After the module is included, the module menu items will be included into the site menu.

    4. See Adding Module to Page to learn how to add module front-end views into Kooboo CMS Page.

Execution sequence of Module

 

Modules Communication

You can share data among different position modules via Page controller ViewData object.

 
 this.PageControllerContext.Controller.ViewBag.SharedData = "message1";
 

All views on the Page can access this data.

FAQ

  • How to integrate Kooboo CMS into an MVC 3 project?
  • Where can I find the free modules?


We encourage developers to publish more free modules. We are planning to create a module community. Right now, we will publish some free modules in http://koobootoolkit.codeplex.com. You can get the free modules by downloading the source code.