Creating Custom Element Control Panels

Turn your custom element CX into a control panel using a simple configuration change...

So this is just a quick post inspired by an answer my friend Evan Thibodeau posted to a Liferay Community Slack question:

Hi, how to develop admin applications (i.e. the ones that can be added and accessed in control panel or applications menu) without using osgi modules?

I didn't think this was possible and replied as such...

But Evan knew this was possible, so he shared the secret sauce on the thread, and I wanted to share it with everyone...

All you need to do is update your client-extension.yaml file with some extra properties:

instanceable: false
name: Liferay AI Content Wizard Settings
panelAppOrder: 700
panelCategoryKey: applications_menu.applications.custom.apps

He shared this from a public repo, https://github.com/liferay/liferay-portal/blob/b272b539aac99f3bc0ccfd1ac6606d44e3e4ac4d/workspaces/liferay-aicontentwizard-workspace/client-extensions/liferay-aicontentwizard-custom-element/client-extension.yaml#L23-L26, and it's a technique that the AI Content Wizard team used to add to the control panel.

Let's review the additions so their usage is clear...

instanceable - This is a required flag to notify Liferay that the custom element can only appear on the page once. It is necessary for the control panel usage.
name - This is the display name for the page that will host the control panel.
panelAppOrder - This is a numerical value to define the order position for the page in the control panel. All of the entries in the same panelCategoryKey will be sorted by this value and then by name, so pick a value that places where you expect your control panel to be.
panelCategoryKey - So the value itself is an internal Liferay format for the control panel hierarchy. In the example given, it will be placed in the Applications page, under the CUSTOM APPS section. The values for the key you want to use will come from various sources, starting with PanelCategoryKeys.java where we can find the APPLICATIONS_MENU, COMMERCE, and CONTROL_PANEL keys, but you can find some other constants defined for the full names of various locations such as APPLICATIONS_MENU_APPLICATIONS_CUSTOM_APPS.

Unfortunately you won't find keys for every possible section for the panelCategoryKey, but hopefully the one(s) you need are there. In case they aren't, you're likely going to be chasing the values down using the entries in the control panel in the portal source. If the one you need is missing, you'll have to find the control panel portlet, find it's PanelApp configuration for the key and category, then use those values to reconstruct the string that you need to use.

With this in place, when you build and deploy your custom element, Liferay should render your custom element as a new control panel where you've specified.

The great part about this is that it is totally using a CX, which means you can use this in SaaS, PaaS as well as Self-Hosted deployments.

Hopefully you find this post to be useful, if only to show you the kind of help you too can receive by joining the Liferay Community Slack!