CONTENTSTART

Creating a Module

Creating a module, with custom classes, custom UI, etc becomes more and more common the more customization you do.  Custom modules are required to do simple things like add Custom Settings, but the power behind them really lies in being able to create your own Custom Classes, UI Pages to manage these or extend other Kentico classes, and of course handle permissions for these resources.

This article is related to the July 2017 post on Module Permissions, but you really can use this information to create your own Modules.  But just be aware, some steps in here are unneccesary depending on your module needs, and are set up in such as way to demonstrate the Permissions aspect of modules.

You can import in a Kentico 10 instance all the below objects if you wish through this Exported file.

Step 1: Create a new Module

In your Kentico instance, bring up the Modules tool, and click "New Module," and configure as below.

Creating a Test Permissions Module

Once saved, on the left click on "Sites" and assign the module to the current site.

Step 2: Create your Classes

In my example, I created 4 classes:

  1. DefaultPermissionClassLocal
  2. DefaultPermissionClassGlobal
  3. CustomPermissionClassLocal
  4. CustomPermissionClassGlobal

Each had a Text field "SomeValue" of type Text, required.

The 2 Local classes also had a SiteID column:

  • Field Name: SiteID
  • Data type: Integer number
  • Required: True (Checked)
  • Reference to: Site
  • Reference Type: Required

Creating all of these, I also generated the code for each of them (clicking on the "Code" tab on the left) and saved them.

For the 2 local ones, I removed the SiteID “DependsON” references as it is already set in the TypeInfo, this step is only needed for references to the Site.

Don't need DependsOn for Site reference

Step 3: Create Your Permissions

Under permissions, we're going to create 4 Permissions and check "Display In Matrix" on all of these.  See below:

Note: Technically there are 5 types of permissions in Kentico.  Create, Read, Modify, Delete, and Destroy.  If you do not specify a Create, Delete, or Destroy, the Modify covers all of them.  This is why Kentico recommends you create a Read and Modify permission on your module, as this will cover all operations (if not customizing further).

Also the "Except Custom Local" in the display names of the Read and Modify are becuase in the Blog article I demonstrate 2 methods of altering Class Permissions, one is altering the Permission name, and for the Custom Local the Read is changed to Read_Custom, and the Modify is changed to Modify_Custom, so the normal Read and Modify will not work for the Custom Local class.

Step 4: Create the Basic User Interfaces

Kentico is awesome in that you can create your basic CRUD management of your objects without having to build your own user interfaces (although you could if you wanted to).  Below are the User Interfaces i created for this module, with their configurations.  Follow below to set up yours.

UI Creation

Couple Sub Notes:

  1. If "Check Module 'Read' permission" is checked, then the user must be in a role that has the generic "Read" permission for the module to see this page.  Since the Custom Test Permission Local class is having its permissions named changed from Read to Read_Custom in my example, this needs to be unchecked for the Test Permissions, Local Classes and Local Classes’s children so those with the Custom_Read can access it.
  2.  For the Vertical Tabs with Site Selector, it’s not documented but you need the custom property "showsiteselector" to be True for the drop down to show.  The Site Selector passes the SiteID through the querystring "SiteID."
  3. Normally for "Global" UI elements, you would limit access to only Global Administrators through the "Is  Global Application" checkbox on the bottom of the UI Element’s General tab.  However in our case, I’m making it so Administrators can see (READ) the classes, but I’ll be making it to where they cannot modify unless they are a Global Administrator, so I am not going to check "Is Global Application."
  4. For the New / Edit Object templates, how it works is it looks for the keyword "New" and "Edit" in the names of the pages, so although they both have the same Page Template, they know which is which based purely upon that keyword.

Step 5: Create the UniGrid XML

The Object Listings require you to define a UniGrid xml.  It will look to the default path of /App_Data/CMSModules/{ModuleCodeName}/UI/Grids/{ObjectType}/default.xml, so we will create these.

Tip: Borrow from other module’s unigrid xml file content to help give you a head start.  Use Kentico’s Documentation for UniGrid xml.

Step 6: Create Roles and Assign Permissions

The next step is to create some roles and then assign the permissions we have provided.  We’ll create a user "TestSiteEditor" (setting the user type to Editor), and create the Roles "Test Permission Full" and "Test Permissions Custom," Configured as below:

Test Permissions Custom Permissions

Test Permissions Full Permissions

For the UI Personlization for each role, make sure they can access the Test Permission UI and its children.  You can use this to also limit access based on role.

Set what UI Page Editors can see

Conclusion

At this point, you now have a Custom Module, permissions created, UI Pages created, etc.  If you imported these objects, you can take a look at the CustomPermissionClassLocalInfo.cs and CustomPermissionClassGlobalInfo.cs and see the two methods of overwriting the permission names outlined in the blog article, if not then please visit the blog article to finish the final steps for this particular module.

CONTENTEND