Module can be attached to a Page in the exact same way as a content template.
Before 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 for controller, action and parameters.
Setup
Kooboo Includes a Visual Studio template for Module development. You can download and install the template from Kooboo website. During the installation, you may see a "no signature found" alert, ignore it and click YES to continue. 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.
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 default ASP.NET MVC sample site uses global.ascx to define routing table. Global.ascx file is not working in Kooboo Module because one system can only has one Global file. Under the project folder, find a file named "routes.config". That is the routing table of Kooboo Module.
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 our ContentHelper API to access and update content. Below is an example of our API.
var allBlogs = CmsContext.ContentHelper.GetContents("Blogs", string.Empty, string.Empty, null, 0, 100);
ViewData["Blogs"] = allBlogs;
return View();
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 3 connection strings in web.config, same as the main Kooboo main site, make sure it connects to a valid instance of Kooboo application database.
Create a test application and a test page, and then change below values in the web.config.
This module will use the defined mock application and page for debug.
2. Install Schemas and Folders in the test application.
In the project files, you will find a home controller. There are three action methods there.
Generate: Generate the Module.config module installation file.
Install: Install Module to the mock application as defined in the <appSettings/>
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 directly use XML to create a Schema. 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 file, you need to create a Schema object and use the SerializeSchema method to write the Schema definition to XML file.
Cms_Schema categorySchema = new Cms_Schema("Category", SchemaType.Text);
var categorySchemaFile = SerializeSchema(categorySchema); //save to schema xml file
//articld schema
Cms_Schema articleSchema = new Cms_Schema("Article", SchemaType.Text) { CategorySchemasUUID = categorySchema.UUID.ToString() };
articleSchema.Cms_Column.Add(new Cms_Column("Body", "Body", ColumnDataType.String, ControlType.Htmleditorimage));
var articleSchemaFile = SerializeSchema(articleSchema);
After that, you need to attach them to the Module configuration object.
moduleInfo.Schemas = new IncludeFile[2]; //include in module definition file
moduleInfo.Schemas[0] = new IncludeFile() { Path = categorySchemaFile };
moduleInfo.Schemas[1] = new IncludeFile() { Path = articleSchemaFile };
To Create folders in your application.
moduleInfo.Folders = new FolderInfo[2];
moduleInfo.Folders[0] = new FolderInfo() { FolderName = "Category", SchemaName = "Category" };
moduleInfo.Folders[1] = new FolderInfo() { FolderName = "Article", SchemaName = "Article" };
Execute related controller action to execute the code.
For example:
http://localhost/home/generate generate moduel config file for manully 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 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 home controller, you see example code like below.
moduleInfo.InstallSqlFiles = new IncludeFile[1];
moduleInfo.InstallSqlFiles[0] = new IncludeFile() { Path = @"Schema\installSql.sql" };
moduleInfo.UnstallSqlFiles = new IncludeFile[1];
moduleInfo.UnstallSqlFiles[0] = new IncludeFile() { Path = @"Schema\unstallSql.sql" };
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.
Schema\installSql.sql Schema\unstallSql.sql
You can get the connection string value from web.config or define your own database connectionstring.
Your module may contains 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.
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 a ApplicationId(Guid) in your table and query data based on that ID. You can access ApplicationId from your module via
CmsContext.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 home controller and in the module.config, you already see the setting of a module.
Key1 Value1
Settings are some key value pair you can define in the module.config. In backend CMS, you can find the setting edit page at:
Application --> Extension --> Module, select your module name and click Detail. See below screen.
In the detail page, you will see the key you defined in the module config file.
To access those values in module code:
ModuleConfiguration moduleInfo = new ModuleConfiguration();
String Keyvalue = ModuleInfo.ModuleSettings["Key1"].ToString();
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.
[Function(Name="admin", Description="admin rights", UnauthorizedRedirectUrl="/blog/Unauthorized")]
public ActionResult Admin()
{
return View();
}
? 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.
In the action attribute, you can define which handler to use for unauthorized access.
[Function(Name = "ExampleBlog", Description = "List all blogs.", UnauthorizedHandlerType = typeof(ExampleBlogController))]
public ActionResult Index()
{
return View();
}
Deployment
To deploy Kooboo module, you only need to zip everything and upload it to server. If you are uploading to the same Kooboo instance you used for development, make sure you already clean the created Schmes and Folders before upload.
Open module.config file and verify that it contains right information. That is the instruction file Module installer will use to install the module. You may remove sections which you do use.
A sample Module config can look like below.
1.0.0 1.1.0 false Hello/admin Key1 Value1 Everest.Cms.HelloWorld bin\Everest.Cms.HelloWorld.dll true
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 "bin\Everest.Cms.HelloWorld.dll" as defined in module config in our example. Thosse files are necessary for development, but not needed for deployment.
We zip everything into "helloworld.zip". Open your Kooboo site, go to Application --> Extension --> module
Click "upload" button to upload the helloworld.zip file we just created.
When a module is uploaded, it is not installed by default. Select the module name and click "install" button to install the module.
After a module is installed, you can use it exactly the same way as a regular Content template. Go to helloworld --> page, left click a page to open page configuration.
Click "Visual Design" to open visual designer. You should find the "helloworld" module there. Drag and drop it to any positions you defined in the Layout template.
Click "save & close" to close visual designer, and then click "save & close" again to close page configuration.
Your module is successfully installed and used on your website now.