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.
 

Recent Entries

Into the Box 2024 Last Early Bird Days!

Into the Box 2024 Last Early Bird Days!

Time is ticking, with less than 60 days remaining until the excitement of Into the Box 2024 unfolds! Don't let this golden opportunity slip away; our exclusive Early Bird Pricing is here for a limited time only, available until March 31st. Why wait? Secure your seat now and take advantage of this steal!

Maria Jose Herrera
Maria Jose Herrera
March 20, 2024
Ortus February Newsletter 2024

Ortus February Newsletter 2024

Welcome to Ortus Solutions’ monthly roundup, where we're thrilled to showcase cutting-edge advancements, product updates, and exciting events! Join us as we delve into the latest innovations shaping the future of technology.

Maria Jose Herrera
Maria Jose Herrera
March 06, 2024
Unveiling the Future of CFML Development - 3rd Round of Sessions

Unveiling the Future of CFML Development - 3rd Round of Sessions

Welcome back to our journey into the future of CFML development! As excitement continues to build for Into the Box 2024, we're thrilled to bring you the latest updates on what promises to be a transformative event. Continuing our blog post series, let's delve deeper into the third wave of session releases and discover the key surprises awaiting attendees. Learn More

Maria Jose Herrera
Maria Jose Herrera
March 01, 2024