quick links
Module development guide (v. 1.2, 2.0)
date added: 2009-11-02
Kooboo Module is a real ASP.NET MVC mini site, which can run as a standalone application as well as install into Kooboo as a module. You are free to use any .NET class or controls. Module runs within the context of Kooboo, so Module can access to all API methods of Kooboo.
You can choose to write your own backend admin section with SQL database table, or use Kooboo CMS for content management. The only two requirements we have for developing Kooboo modules are:
1. use routes.config to define your MVC routing instead of defined in global.ascx, because Kooboo module will not have access to global.ascx file.
2. use Partial view, see below Development section for more detail.
Modules can be attached to a Page smoothly in the exact same way as a content template. Before we start, you better have the basic knowledge of ASP.NET MVC model, understand the URL routing table and linking concept. URL does not link to a physical file as in ASP.NET Web Form. MVC URL contains information about controller, action and parameters.
Kooboo includes a Visual Studio template for Module development. Download "Kooboo.ModuleTemplate.vsi" from kooboo.codeplex.com and double click to install it. During installation, you may see a publisher name other than Kooboo, please ignore that. After installation, you will be able to find a project template to create an Kooboo Module under VS.NET Visual C# --> Web
Be sure to use a unique name for your module.
Now you have created a Kooboo module solution, it is a standard ASP.NET MVC site. We have some sample code there just to get your familar with it. By default, the HomeController and "Configuration.cs" are responsible for Kooboo module installation and uninstallation, please keep these two files. You may modify them to meet your needs.
After a project is created, you are free to use all Kooboo API methods and ASP.NET MVC class library to write your module almost without any limitation except below two points.
Routing table: In Kooboo Module, we use a configuration file for URL routing table. The ASP.NET MVC sample site uses global.ascx to define routing table. One system can only has one Global file and Module should not have rights to access that. Under the project folder, find a file named "routes.config". That is the routing table of Kooboo Module. Below is a sample route table.
Please change the default controller to your own controller. DataToken namespace is used by Kooboo. It should be created automatically according to the project name your entered. If you change your project namespace, you need to update it here as well. To change your namespace, right click on project name within VS.NET, select property, you will see below screen.
Partial view: For view, you have to use partial view in Kooboo Module. See below screen when adding a view
You can use Kooboo CMS for data/content management or create own your database and datamodel. When using Kooboo CMS, you can use ContentHelper API to access and update content, please refer to other documents regarding how Kooboo manage content, most important are the concept of Text Schema and content Folder. Below is an example of our API method.
Using VS.NET, you will have the benefit of intellisense and able to see name of parameters.
To debug your module in VS.NET, do the following steps.
1. Change the web.config settings
There are 4 connection strings in web.config, same as the Kooboo main site, make sure it connects to a valid instance of Kooboo application database. You may copy them from your Kooboo main site.
By default, Kooboo Module will use the context of "Root" application for debug. You may create an application inside the Kooboo instance and config to develop your module under that application context. You can modify below configuration value in the web.config.
You can also create a mock page in the Kooboo instance. Before Kooboo 2.0, you need to initialize the Kooboo Mock page from the "index" view of homeController. From Kooboo 2.0, you can define it in the web.config like below.
2. Install Schemas and Folders in the development Kooboo instance.
In the project files, you will find a home controller. It is very important to keep this HomeController also the Index view of this controller. The index view will initialize the Kooboo environment, The HomeController contains three important action methods there.
Generate: Generate the Module.config module installation file.
Install: Install Module environment to the root application of Kooboo instance as defined in the connection string. Kooboo module always need to install under Root application. Module schema and folder will be created under root as well. Note that this method does not really install the Module, it only install the module folder and schema environment. Module code and dlls are not copied.
Uninstall: Uninstall module.
Generate method is to generate Schema definition files and folders creation config values. The output will be the module.config file. You can create Schema definition file by modifying XML directly, However we recommend using our APIs to create schema files, at least for new users. In the module template, you will find some code examples.
To create a Schema, you need to create a Schema object and use the SerializeSchema method to write the Schema definition to a XML file. Definition of Schema is very similar as when you are doing it within the CMS. Below is a completed example of a blog text schema with a Tag category schema and a Child schema of comment
In above example, Constants is a class with some predefined property values. Please note in above example, at the end, you need to add those schema file to the moduleConfiguration object. That is done by below code in above example.
To Create folders in your development Kooboo instance. Use below code example.
Execute related controller action to execute the code.
For example:
http://localhost/home/generate generate module config file for manually installation or deployment
http://localhost/home/install install Schemas and create Folders in the mock application.
http://localhost/home/uninstall delete Schemas and Folders in mock application.
Important Note: A schema has a unique UUID. Schema with the same UUID can only be created once within one Kooboo instance unless you change the UUID. If you install twice or install a module on a Kooboo instance which already has that module or schema, it will trigger a conflict. After finishing development, if you want to install module on the mock application, you need to run uninstall first or manually remove Schemas and Folders.
After Schemas and Folders are created, you can start entering data to the Folder and query data using our ContentHelper API. Visual Studio.NET full debug function is available for your development.
You can also design your own database table and build the backend CMS yourself. In the Configuration.cs file, you see example code like below.
That will add config value to module.config to run the SQL script during instalation. Alternative, you can go directly to module.config, and modify the values there.
You can get the connection string value from web.config or define your own database connectionstring. When you read from Kooboo web.config, you should use the connection string key of "ModuleDDL" (Note: starting from Kooboo 2.0, we are no longer using the ModuleDDL connection string).
Your module may contain backend data management and front end presentation.
The start page of module front end is defined at routes.config
The backend start page is defined in the "module.config" file using standard MVC controller/action URL.
You can generate this setting in the "generate" action or modify the "Module.config" directly. In the "generate" action, you can find sample code like: moduleConfiguration.AdminUrl = "ExampleBlog/admin".In Kooboo CMS, select a module at Application --> Extension --> Module, click "admin" will open a popup window with the <AdminUrl> as start page.
Important note: If you want every application/website can use your module and has its own set of data, you need to include an ApplicationId(Guid) in your table and query data based on that ID. You can access ApplicationId from your module via:
Of course, you can also include a page uuid in your table so that every page has its own set of data. That is completely up to you.
Key: setting key
Value: default value
Items: predefined items values for selection separated by "|". For example: settings.AddSetting("PageMenuType", "Top", "Top|Sub|Sibling|CrumbPath");
Settings are some key value pair you can define in the module.config. When you are adding a module to a page, you will be able to see the setting key/value show as parameters which you can assign value or choose from predefined item values. Predefined values are separated by "|" as in above example.
To access those values in module code:
There are some common settings we provide additional API methods to define and access them. See below.
EntryUrl: the start controller/action page URL, one module can define several start URL or use other settings to select the entry controller/action.
EnabledPageTitle: when checked, you will be able to use API method "SetPageTitle(string title);" to change the page Title. The other related API method is the "SetHtmlMeta" API.
Theme:Similar as the Kooboo theme. You can define theme for module or overwrite module theme from the site theme.
You may want to control access to certain controllers or actions. Permission can be defined in backend CMS with combination of the ASP.NET membership role. In your module code, you only need to define the function name of a controller action using attribute, Kooboo will list all function names you coded and make them available for permission configuration in the module detail page.
? and * are ASP.NET membership symbol. ? match all anonymous users and * match everyone.
For unauthorized access, default is an error message, you can also define an unauthorized redirect URL in the function attribute like above example or write your own implementation by inheriting from IUnauthorizedHandler.
To deploy Kooboo module, you only need to zip everything and upload it to server. You must execute the "Generate" or "Install" action as mentioned above first before you can zip the package, or you have to check to make sure that your module.config contains all correct information. If you are uploading to the same Kooboo instance you used for development, make sure you already clean the created Schemas and Folders before uploading.
Open module.config file and verify that it contains right information. This is the instruction file the Module installer will use to install the module. You may remove sections which you do NOT use.
A sample Module config can look like below.
Go to module project folder in Windows explorer, you can zip everything in that folder into a modulename.zip. That will work. However we recommend you throwing away the "lib" folder and most of the files in "bin" folder except files as defined in module config. Those files are necessary for development, but not needed for deployment.
You have made a Kooboo module package, go to Root --> Extension --> module, you will be able to upload and install modules there. A module always needs to be installed under root and can be made available to applications.
After a module is installed, you can add modules to a page in the exactly same way as a content template.
You can choose to write your own backend admin section with SQL database table, or use Kooboo CMS for content management. The only two requirements we have for developing Kooboo modules are:
1. use routes.config to define your MVC routing instead of defined in global.ascx, because Kooboo module will not have access to global.ascx file.
2. use Partial view, see below Development section for more detail.
Modules can be attached to a Page smoothly in the exact same way as a content template. Before we start, you better have the basic knowledge of ASP.NET MVC model, understand the URL routing table and linking concept. URL does not link to a physical file as in ASP.NET Web Form. MVC URL contains information about controller, action and parameters.
Setup
Kooboo includes a Visual Studio template for Module development. Download "Kooboo.ModuleTemplate.vsi" from kooboo.codeplex.com and double click to install it. During installation, you may see a publisher name other than Kooboo, please ignore that. After installation, you will be able to find a project template to create an Kooboo Module under VS.NET Visual C# --> Web
Be sure to use a unique name for your module.
Now you have created a Kooboo module solution, it is a standard ASP.NET MVC site. We have some sample code there just to get your familar with it. By default, the HomeController and "Configuration.cs" are responsible for Kooboo module installation and uninstallation, please keep these two files. You may modify them to meet your needs.
Development
After a project is created, you are free to use all Kooboo API methods and ASP.NET MVC class library to write your module almost without any limitation except below two points.
Routing table: In Kooboo Module, we use a configuration file for URL routing table. The ASP.NET MVC sample site uses global.ascx to define routing table. One system can only has one Global file and Module should not have rights to access that. Under the project folder, find a file named "routes.config". That is the routing table of Kooboo Module. Below is a sample route table.
Please change the default controller to your own controller. DataToken namespace is used by Kooboo. It should be created automatically according to the project name your entered. If you change your project namespace, you need to update it here as well. To change your namespace, right click on project name within VS.NET, select property, you will see below screen.
Partial view: For view, you have to use partial view in Kooboo Module. See below screen when adding a view
Use Kooboo CMS for data management
You can use Kooboo CMS for data/content management or create own your database and datamodel. When using Kooboo CMS, you can use ContentHelper API to access and update content, please refer to other documents regarding how Kooboo manage content, most important are the concept of Text Schema and content Folder. Below is an example of our API method.
var blog = CmsContext.ContentService.GetContentByUserKey(userKey, null); return View(blog);
Using VS.NET, you will have the benefit of intellisense and able to see name of parameters.
To debug your module in VS.NET, do the following steps.
1. Change the web.config settings
There are 4 connection strings in web.config, same as the Kooboo main site, make sure it connects to a valid instance of Kooboo application database. You may copy them from your Kooboo main site.
By default, Kooboo Module will use the context of "Root" application for debug. You may create an application inside the Kooboo instance and config to develop your module under that application context. You can modify below configuration value in the web.config.
You can also create a mock page in the Kooboo instance. Before Kooboo 2.0, you need to initialize the Kooboo Mock page from the "index" view of homeController. From Kooboo 2.0, you can define it in the web.config like below.
Initialization of Kooboo Context is done by the HomeController index page, this file can be found at "/Views/Home/Index.aspx"
2. Install Schemas and Folders in the development Kooboo instance.
In the project files, you will find a home controller. It is very important to keep this HomeController also the Index view of this controller. The index view will initialize the Kooboo environment, The HomeController contains three important action methods there.
Generate: Generate the Module.config module installation file.
Install: Install Module environment to the root application of Kooboo instance as defined in the connection string. Kooboo module always need to install under Root application. Module schema and folder will be created under root as well. Note that this method does not really install the Module, it only install the module folder and schema environment. Module code and dlls are not copied.
Uninstall: Uninstall module.
Generate method is to generate Schema definition files and folders creation config values. The output will be the module.config file. You can create Schema definition file by modifying XML directly, However we recommend using our APIs to create schema files, at least for new users. In the module template, you will find some code examples.
To create a Schema, you need to create a Schema object and use the SerializeSchema method to write the Schema definition to a XML file. Definition of Schema is very similar as when you are doing it within the CMS. Below is a completed example of a blog text schema with a Tag category schema and a Child schema of comment
In above example, Constants is a class with some predefined property values. Please note in above example, at the end, you need to add those schema file to the moduleConfiguration object. That is done by below code in above example.
To Create folders in your development Kooboo instance. Use below code example.
Execute related controller action to execute the code.
For example:
http://localhost/home/generate generate module config file for manually installation or deployment
http://localhost/home/install install Schemas and create Folders in the mock application.
http://localhost/home/uninstall delete Schemas and Folders in mock application.
Important Note: A schema has a unique UUID. Schema with the same UUID can only be created once within one Kooboo instance unless you change the UUID. If you install twice or install a module on a Kooboo instance which already has that module or schema, it will trigger a conflict. After finishing development, if you want to install module on the mock application, you need to run uninstall first or manually remove Schemas and Folders.
After Schemas and Folders are created, you can start entering data to the Folder and query data using our ContentHelper API. Visual Studio.NET full debug function is available for your development.
Create your own database table
You can also design your own database table and build the backend CMS yourself. In the Configuration.cs file, you see example code like below.
That will add config value to module.config to run the SQL script during instalation. Alternative, you can go directly to module.config, and modify the values there.
You can get the connection string value from web.config or define your own database connectionstring. When you read from Kooboo web.config, you should use the connection string key of "ModuleDDL" (Note: starting from Kooboo 2.0, we are no longer using the ModuleDDL connection string).
Your module may contain backend data management and front end presentation.
The start page of module front end is defined at routes.config
The backend start page is defined in the "module.config" file using standard MVC controller/action URL.
You can generate this setting in the "generate" action or modify the "Module.config" directly. In the "generate" action, you can find sample code like: moduleConfiguration.AdminUrl = "ExampleBlog/admin".In Kooboo CMS, select a module at Application --> Extension --> Module, click "admin" will open a popup window with the <AdminUrl> as start page.
Important note: If you want every application/website can use your module and has its own set of data, you need to include an ApplicationId(Guid) in your table and query data based on that ID. You can access ApplicationId from your module via:
CmsContext.Cms_Application.ApplicationId
Of course, you can also include a page uuid in your table so that every page has its own set of data. That is completely up to you.
Settings
In the Configuration.cs and in the module.config, you already see the setting of a module.
Key: setting key
Value: default value
Items: predefined items values for selection separated by "|". For example: settings.AddSetting("PageMenuType", "Top", "Top|Sub|Sibling|CrumbPath");
Settings are some key value pair you can define in the module.config. When you are adding a module to a page, you will be able to see the setting key/value show as parameters which you can assign value or choose from predefined item values. Predefined values are separated by "|" as in above example.
To access those values in module code:
String Keyvalue = ModuleInfo.ModuleSettings["Key1"].Value.ToString();
There are some common settings we provide additional API methods to define and access them. See below.
EntryUrl: the start controller/action page URL, one module can define several start URL or use other settings to select the entry controller/action.
EnabledPageTitle: when checked, you will be able to use API method "SetPageTitle(string title);" to change the page Title. The other related API method is the "SetHtmlMeta" API.
Theme:Similar as the Kooboo theme. You can define theme for module or overwrite module theme from the site theme.
Permission
You may want to control access to certain controllers or actions. Permission can be defined in backend CMS with combination of the ASP.NET membership role. In your module code, you only need to define the function name of a controller action using attribute, Kooboo will list all function names you coded and make them available for permission configuration in the module detail page.
? and * are ASP.NET membership symbol. ? match all anonymous users and * match everyone.
For unauthorized access, default is an error message, you can also define an unauthorized redirect URL in the function attribute like above example or write your own implementation by inheriting from IUnauthorizedHandler.
Deployment
To deploy Kooboo module, you only need to zip everything and upload it to server. You must execute the "Generate" or "Install" action as mentioned above first before you can zip the package, or you have to check to make sure that your module.config contains all correct information. If you are uploading to the same Kooboo instance you used for development, make sure you already clean the created Schemas and Folders before uploading.
Open module.config file and verify that it contains right information. This is the instruction file the Module installer will use to install the module. You may remove sections which you do NOT use.
A sample Module config can look like below.
Go to module project folder in Windows explorer, you can zip everything in that folder into a modulename.zip. That will work. However we recommend you throwing away the "lib" folder and most of the files in "bin" folder except files as defined in module config. Those files are necessary for development, but not needed for deployment.
You have made a Kooboo module package, go to Root --> Extension --> module, you will be able to upload and install modules there. A module always needs to be installed under root and can be made available to applications.
After a module is installed, you can add modules to a page in the exactly same way as a content template.