Module development

From Kooboo document
(Redirected from Module development guide)
Jump to: navigation, search

Introduction of Module

Sometimes, you may want to share some common function related pages among different sites, for example: forum. Or you need to develop the custom data management interface beside using the default content management. In this case, you may use the Kooboo CMS Module. In Kooboo CMS that is V3.1 or above, module is base 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 with 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 ran on the MVC Area. The front-end controllers must be added on the position of Kooboo CMS Page.

Developing Module

Development

Setup the Module project

  1. Download Kooboo.CMS.ModuleArea.vsi. Double click it to install the Module project templates into Visual Studio.
  2. Create a Module project using the project template under "Visual C# -> Web", and name the project as MyModule1. The project will be built succeefully by default and available for browsing.
  3. Rename the "SampleModule" area as any name you want. In this tutorial case, we also call it "MyModule1". The area name is also using the name of Module. This name can not be changed after the project published, because it will take effect in the area URL.
  4. 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 into Kooboo CMS future version to help you to create your own module quickly.

Add Module to Page

  1. Now if you restart the Module site, you may get 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 can run on the Pages or not. However, we have changed the Module name(Area name) as "MyModule1", so the way to correct this error is to change the Module name on Kooboo CMS Page editing form.
    1. Type the {url}+"/admin" in the address bar to go to the Site's admin page.
    2. Edit the "Articles" page, remove the all Modules on the positions of the Page. Then re-add those Modules on the position by following steps below:

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

  1. 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 "Articles" page. The rest 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 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 with Kooboo CMS admin panel, so there is a layout called "Shared\Site.cshtml" which has the similar code with layout in Kooboo CMS. You are free to change the back-end controller graphic if you do not want it to be the same with 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 the pop views. The pop views needs 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 we can not do the initialization during the installation process.

This module can be used in multiple sites, so you are not supposed do initialization during the installation process, but you can do it in different site respectively.

    • GenerateModuleInfo is used to generate the "module.config" file by code.
  • NewsAdminController.cs is a sample controller which demonstrates you how to create a 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".

Module menu.PNG

Create the front-end controller/views

The front-end controllers run on Kooboo CMS Page positions other than on MVC area. They can not 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 return a JsonResult/FileResult/ContentResult, it will clear the rendered content and 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 loaded first time, or you can just simply select corresponding entry options on "moduleInfo.EntryOptions".

All the front-end view will only render part of HTML string at the position, the HTML is not validated . So you can not use the regular Master Layout.

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". Module publishing 1.PNG
  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

Kooboo CMS Request Flow.jpg

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 to 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.