Module development (for v 4.3 or up)

 

Download and install VS.NET template

First download the KoobooModule.vsi from Kooboo.codeplex.com and double click to install it on your local pc. This will install the Kooboo Module development vs.net template on your PC.

Install_module_template.jpg

Create your Kooboo module project

Create a new VS.Net project using the installed template and give your module a name.

create_new_module.jpg

You have created the Kooboo module. The VS.NET template contains a standard Kooboo CMS and a MVC area. The Kooboo CMS is used to simulate the Kooboo environment in order for you to debug your module easily. Kooboo module is an ASP.NET MVC area, you should write your module code inside that area.


Develop your Kooboo Module

In the new created VS.NET project, you should find your MVC area as below. 

 module_area.jpg

 You can start developing your Kooboo Module the same as developing a regular ASP.NET MVC area with a few changes.
We requires to make those changes due to the fact that a Kooboo module will be rendered within a Kooboo page that contains a Kooboo razor layout already. We need to change how ASP.NET MVC generates Page Url and insert our Kooboo page URL around it.

- Routing
In your module area, you should find a file called routes.config, this is where you should define your MVC routing instead of using the standard way to register routings.


- Html and URL namespace
The ASP.NET MVC URL and HTML namespace contains some functions you need to generate your page URLS. Again, because of a Module is rendered within a Kooboo page, the original Html & Url namespaces should not be used any more, instead Kooboo Module provide below two namespace with very similar functions.
@Url.ModuleUrl()
@Html.ModuleHtml()

- View
you should use a partial view without the defined layout.


There are a few files that you may find it useful.
- CMSMenu.config
this is to define your Module menu that will appear within the Kooboo CMS backend left sidebar.


- Module.config
This config file most of time is used to define two things. 1. The Entry route (controller/action) of your module. There are multiple entry options possible, multiple pages with the same module can have different entry url. This config file also contains settings for the views that available during “install/uninstall”


- ModuleEvents.cs
Those are the events that you can write code during module management. There are 5 events now.
- OnInstalling. When module is being installed
- OnUninstalling. When module is being uninstalled
- OnExcluded. When module is being excluded from one website
- OnIncluded. When module is being included into one website
- OnReinstalling. When module is being reinstalled.

You can now start developing your Kooboo module using your previous skills now. 

Debug your module

You debug your module the same way as you debug other applications using VS.NET. The only difference is that your module must be inserted into a Kooboo webpage, so you hit your break point inside VS.NET by previewing the Kooboo page. 

When you preview the Kooboo module template, it is a standard Kooboo CMS instance, your module area is automatically available as a module inside that instance. 

Deploy Kooboo Module

To deploy a Kooboo module, you can use the VS.NET publish web application function or just build the solution.

module_publish.jpg

Open the published folder or the project build folder, in the folder, find a file called “packmodule.bat”, and double click to pack your project as a Kooboo module installation file.

pack_module.png

The PackModule function will generate a zip that contains your Kooboo module.

Module management

Kooboo CMS provide management interface to install, uninstall and reinstall a Kooboo module.  Login to Kooboo CMS and go to Module menu, you will find menu to install and uninstall Kooboo modules.

module_management.png

Click Install and follow the instruction to install a Kooboo module. Click “Uninstall” to uninstall a module, Click “Reinstall” to upgrade or downgrade a module.

module_installation.png


Module Version control
Kooboo extend version control to module management, it keeps all the module installation history. In above module management screen, select one module and then click “Versions” to view the version history of that module. Select the version you want to restore, and click “Reinstall” to revert to that version.

module_revision.png

Use the module

Two very simple steps to use Kooboo module. 

- Go to the website that needs this module, in the extension/module menu, click “include” to include this module into the website. 

- In the website page, open the page designer and insert the module into the right position