Adding Custom Panel Categories

As you navigate the Product Menu, you can see that Panel Apps like Web Content and Settings are organized into Panel Categories such as Content & Data and Configuration. This article explains how to add new Panel Categories to the menu. Adding new Panel Apps is covered in the next section.

There are three steps to creating a new category:

  1. Create the OSGi structure and metadata.

  2. Implement Liferay’s Frameworks.

  3. Define the Panel Category.

Creating the OSGi Module

First you must create the project.

  1. Create an OSGi module using your favorite third party tool, or use Blade CLI. Blade CLI offers a Panel App template, which is for creating a Panel Category and Panel App.

  2. Create a unique package name in the module’s src directory and create a new Java class in that package. To follow naming conventions, give your class a unique name followed by PanelCategory (e.g., ControlPanelCategory).

Implementing Liferay’s Frameworks

Next, you must connect your OSGi module to Liferay’s frameworks and use those to define information about your entry. This takes only two steps:

  1. Insert the @Component annotation declaring the panel category keys directly above the class’s declaration:

        immediate = true,
        property = {
            "panel.category.key=" + [Panel Category Key],
        service = PanelCategory.class

    You can view an example of a similar @Component annotation for the UserPanelCategory class below:

        immediate = true,
        property = {
            "panel.category.key=" + PanelCategoryKeys.ROOT,
        service = PanelCategory.class

    The property element designates two properties that should be assigned for your category. The panel.category.key specifies the parent category for your custom category. You can find popular parent categories to assign in the PanelCategoryKeys class. For instance, if you wanted to create a child category in the Control Panel, you could assign PanelCategoryKeys.CONTROL_PANEL. Likewise, if you wanted to create a root category, like the Control Panel or Site Administration, you could assign PanelCategoryKeys.ROOT.

    The panel.category.order:Integer property specifies the order in which your category is displayed. The higher the number (integer), the lower your category is listed among other sibling categories assigned to a parent.

    Finally, your service element should specify the PanelCategory.class service.

  2. Implement the PanelCategory interface. See the PanelCategory Interface section for more details. Extending one of the provided base classes (BasePanelCategory or BaseJSPPanelCategory) is a popular way to implement the PanelCategory interface.

  3. If you elect to leverage JSPs, you must also specify the servlet context from where you are loading the JSP files. If this is inside an OSGi module, make sure your bnd.bnd file has defined a web context path:

    Web-ContextPath: /my-module-web

    Then reference the Servlet context using the symbolic name of your module like this:

        target = "(",
        unbind = "-"
    public void setServletContext(ServletContext servletContext) {

Excellent! You’ve successfully created a custom Panel Category to display in the Product Menu. In many cases, a Panel Category holds Panel Apps for users to access. You’ll learn how to add a Panel App to a Panel Category next.

« Customizing the Product MenuAdding Custom Panel Apps »