How to add a toolbar to an APEX page

First of all, take a look at this demo.

The goal

Display page buttons as part of a toolbar. These could be top-level toolbar buttons or buttons inside a (sub)menu.

How?

1. By creating an apex.actions function for each button
2. Adding these region templates to our theme to create a hierarchical toolbar structure
   • Toolbar region template
   • Toolbar group region template
   • (Sub)menu region template

Page buttons which are part of the toolbar can be placed in:

• the toolbar group region
• the (sub)menu region

An example of the template structure

Why?

About two months ago I tweeted the following.

Working on the #orclapex toolbar widget with @Stevil02 to show page buttons in a toolbar pic.twitter.com/aW9lffbJrr

— Menno Hoogendijk (@mennooo) July 28, 2017

Instead of having the regular create, save and delete buttons as part of a region, we chose to place all actions in a toolbar. This has the following advantages:

• The same user interface on all pages
• Save space because we eliminate button lists
• The toolbar is always visible, even on vertical scrolling
• Possibility to add keyboard shortcuts to execute items in the toolbar

There is no declarative way to add a toolbar to a page in APEX (besides the Interactive Grid) by default. But re-usability and low code development are very important in our applications. I’m proud to say to:

We have always found a way to encapsulate advanced functionality in plugins and custom templates.

At the time, the development was still in progress. But now, as promised, an explanation about how it works.

Difference with the Menu Bar List

You can also check out the Menu Bar List. It looks fairly the same and works out of the box. The difference is that the list uses links for all items and my toolbar uses page buttons. This way you are able to work with Dynamic Actions.

About widget.toolbar.js

This widget was introduced along with the Interactive Grid. As shown, it supports several item types like menus, buttons, and toggle items.

The toolbar widget supports showing content from the actions namespace and the menu widget. It’s important to understand the architecture. The JSON object to create a new instance has the same structure.

The full toolbar structure

The apex.actions namespace

An action can be:

• A function
• A toggle
• A radio group

In my toolbar, I’m only using the function type and assigning it to a toolbar button.  An example is the Save button in the Interactive Grid toolbar.

Don’t get too confused about the word action here. There are Dynamic Actions, Dynamic Action actions, and apex.actions actions.

The menu widget

An example of a menu in the toolbar is the action menu in the Interactive Grid.

The action menu in the Interactive Grid toolbar.

Creating the toolbar

For now, I only use this subset of the structure for my page level toolbar.

A subset of the toolbar structure

In our toolbar, both the toolbar buttons and menu items are apex.actions functions in the end. Each apex.action function does the same: Clicking an item in the toolbar will trigger a click on a button defined in the Page Builder inside APEX.

This way we ensure we don’t need to write a JavaScript function to perform an action.

The trick is to:

• Create a JSON object from this region structure
• Hide the original regions
• Show the toolbar instead

Here is an example of the JSON object.

How does it work?

You can see for yourself in the sample application.

In the toolbar region template, there is one line of JavaScript code which executes on page load.

mho.toolbar.init("#REGION_STATIC_ID#")

The template also loads additional JavaScript static files:

#IMAGE_PREFIX#libraries/apex/#MIN_DIRECTORY#widget.toolbar#MIN#.js
#APP_IMAGES#mho/utils.js?version=#APP_VERSION#
#APP_IMAGES#mho/page.js?version=#APP_VERSION#
#APP_IMAGES#mho/keyboardShortcuts.js?version=#APP_VERSION#
#APP_IMAGES#mho/button.js?version=#APP_VERSION#
#APP_IMAGES#mho/toolbar.js?version=#APP_VERSION#

And one CSS file:

#APP_IMAGES#mho/toolbar.css

Since I’m using custom templates, I can’t simply create a plugin for the toolbar. If you want to use it in your application, download the sample application and make sure to add all the static files and extra templates to your application.

Some cool features

• It’s responsive
• A save button in the toolbar will become hot when you change the value of a page item

And finally…

I am still extending this functionality by:

• Improving responsiveness
• Enable/ disable buttons and menus (requires other plugins)