Blog

Gavin Pickin

August 11, 2016

Spread the word


Share your thoughts

Ready for part 4? Yes, part 4. We continue our small walkthrough of building your own Admin Module in ContentBox 3. The last few blog posts we learned the minimum requirements for a new module, to be controlled from inside of ContentBox. Then we learned how to add a handler and a view, and how to access the module from the front end entry point, and through the ContentBox admin entrypoint. In the last blog post in this mini series, we looked at adding a Submenu for your module, to an existing top level Menu item inside of the ContentBox admin. This blog post is going to show you how to add your very own top level Menu item, give it an icon, set permissions, and then add Submenu items to access your module.

Existing code to add a submenu item

As we learned in the previous posts, we need to add code to the onLoad and onUnload functions inside your ModuleConfig.cfc file. 
To add a submenu item to an existing menu, we used the following code.

/**
* Fired when the module is registered and activated.
*/
function onLoad(){
     // Let's add ourselves to the main menu in the Modules section
     var menuService = controller.getWireBox().getInstance( "AdminMenuService@cb" );
     // Add Menu Contribution
     menuService.addSubMenu(
          topMenu=menuService.MODULES,
          name="mySecretsSubMenu",
          label="Find My Secrets",
          href="#menuService.buildModuleLink('mysecrets','home')#"
     );
}

Adding our own top level menu item

This code is a great start, we just need to insert another line between getting the MenuService, and adding the subMenu. This is where we create the topMenu Item.

// Add Menu Contribution
menuService.addTopMenu(
     name         = "MY_SECRET_MODULES_MENU",
     label        = "<i class='fa fa-user-secret'></i> My Secret Modules",
     permissions = "PAGES_EDITOR"
);
  • name - this is the programmatic reference to the top menu item. Its an internal ContentBox convention to make it capitalized with underscores. 
  • label - this is the top menu label itself. You can use Font Awesome Icons to make your menu stand out, just prepend the icon like we have here. You can use icons for the submenus as well, but space is limited, so they look better only being used at the top level menu items.
  • permissions - this is where you can set permissions to view this menu item. I have just used PAGES_EDITOR in this case, because most users could access this. We recommend that you add permissions to ContentBox, assign them to roles, and then you can restrict your menus based on who is logged in.

Note: the permissions listed here only determine whether the user logged in can see the top level menu item. If the user does not have permission to see the top level menu item, that does not stop them from accessing the module itself through the admin. I think we should cover securing Custom Modules in a future post.

Add submenu to our new top level menu

Now we have added our top menu item, we need to change the code we used to add the Submenu item. We need to update the submenu to be added to our new top level menu item "MY_SECRET_MODULES_MENU", instead of the MenuService.MODULES, just switch them out and your file onLoad() should look like this

/**
* Fired when the module is registered and activated.
*/
function onLoad(){
     // Let's add ourselves to the main menu in the Modules section
     var menuService = controller.getWireBox().getInstance( "AdminMenuService@cb" );
   
     // Add Top Menu Contribution
     menuService.addTopMenu(
          name         = "MY_SECRET_MODULES_MENU",
          label        = "<i class='fa fa-user-secret'></i> My Secret Modules",
          permissions = "PAGES_EDITOR"
     );
     // Add Sub Menu Contribution
     menuService.addSubMenu(
          topMenu="MY_SECRET_MODULES_MENU",
          name="mySecretsSubMenu",
          label="Find My Secrets",
          href="#menuService.buildModuleLink('mysecrets','home')#"
     );
}

Removing the Submenu and TopMenu onUnload()

We need to update the removeSubMenu to reference our new top menu. We can remove MenuService.MODULES and replace it with "MY_SECRET_MODULES_MENU". After that line, we have successfully removed the Submenu item, we can remove the TopMenu iteam as well, with one line. You can see it all below.

/**
* Fired when the module is unregistered and unloaded
*/
function onUnload(){
     // Let's remove ourselves to the main menu in the Modules section
     var menuService = controller.getWireBox().getInstance( "AdminMenuService@cb" );
     // Remove Menu Contribution
     menuService.removeSubMenu(topMenu= "MY_SECRET_MODULES_MENU",name="mySecretsSubMenu" );
     menuService.removeTopMenu( topMenu= "MY_SECRET_MODULES_MENU" );
}

Note: when adding top level menu items, if not sub menus exist, the top menu will not show.
https://gist.github.com/gpickin/24df5491a332853c416a6159ef4608f0

Lets have a look?

Now when you activate, it added the Top Menu and the Sub Menu items as well. Now you can group several of your modules into a single Top level menu item.
Next blog post we'll look at adding permissions to roles, and assigning to users, to show and hide the menu items, and learn how to lock down your custom module incase the user can remember the URL to access it.
 

Add Your Comment

Recent Entries

BoxLang 1.0.0 RC1 Launched

BoxLang 1.0.0 RC1 Launched

After nearly a year of relentless iteration, rigorous testing, blood, sweat, lots of praying, tears, and over 1,000 resolved tickets, we proudly announce the first Release Candidate (RC1) of BoxLang! With 27 beta versions behind us, we are now on the final stretch toward the official 1.0 release.

Luis Majano
Luis Majano
February 18, 2025
Exploring BoxLang: A Modern Scripting Language for the JVM!

Exploring BoxLang: A Modern Scripting Language for the JVM!

The amazing CFML community leader Ray Camden recently shared his thoughts on BoxLang, a dynamic scripting language that runs on the Java Virtual Machine (JVM). BoxLang is lightweight (only 6 MB) and doesn’t require Java knowledge, making it accessible to developers from all backgrounds. Whether you're building CLI scriptsweb applications, or experimenting with serverless architecture, BoxLang has you covered.

Maria Jose Herrera
Maria Jose Herrera
February 14, 2025
Get a Free BoxLang+ License with Your ITB 2025 Ticket!

Get a Free BoxLang+ License with Your ITB 2025 Ticket!

At Ortus Solutions, we are dedicated to delivering the best experience for our Into the Box attendees. This year’s event will be an exciting opportunity to explore BoxLang and modern CFML development, and we want to ensure that attending in person is even more rewarding.

Maria Jose Herrera
Maria Jose Herrera
February 07, 2025