Standard Plugins » Action Panel » Services

Action Panel Services

The Action Panel calls services with names based on the Element’s panel name and category. Your plugin implements them to add panel elements to the panels.

Builder services

To build the action panel, the Action Panel plugin will call a service named after the panel’s name, std:action_panel:[panel], where [panel] is the name from the Element definition.

It’s called with display and builder arguments, for example:

P.implementService("std:action_panel:person",
    function(display, builder) {
        // implementation here
    }
);

builder is a PanelBuilder object for building the user interface.

display is an object with the following properties:

key object

If the Action Panel Element is being rendered on an object page, the StoreObject.

key path

The path of the page being requested.

key options

The options from the Element definition. While not entirely recommended, you can include additional options there which are relevant to your plugins, but do use your own namespace.

Multiple panels

For clarity of user interface, remember to split the UI into logical groupings. Use the panel() function on the PanelBuilder.

Category service

In addition, if the Element has a category defined, a service named after the category, std:action_panel:category:[category] will be called with the same arguments.

Global service

There is also a global service, std:action_panel:*, called for every action panel. This should only be needed when the implementing plugin doesn’t know the name or category of the panel it should add to.

Be careful when using this service to ensure you only affect the panels you intend to. It should only be necessary very rarely.

Examples

With the definitions from the action panel elements examples, to add a link to the home page for Administrator users:

P.implementService("std:action_panel:home_links",
    function(display, builder) {
        // Use normal API for checking current user permissions
        if(O.currentUser.isMemberOf(Group.Administrators)) {
            // Use PanelBuilder functions to add UI
            builder.link("default",
                "/do/example/admin", "Example Admin");
        }
    }
);

To add a link to a per-person ‘overview’ page, shown to every user:

P.implementService("std:action_panel:person",
    function(display, builder) {
        builder.link("default",
            "/do/example/person-overview"+display.object.ref,
            "Overview")
        }
    }
);

Other services

The Action Panel plugin provides some utility services which may be needed occasionally.

std:action_panel_priorities

The PanelBuilder uses numeric and named priorities for ordering. You can use the std:action_panel_priorities service to add additional named priorities.

P.implementService("std:action_panel_priorities",
    function(priorities) {
        priorities["example:special"] = 150;
        priorities["example:boring"]  = 5000;
    }
);

Use this sparingly. It’s often just as easy to use numbers.

Your names should be namespaced to your organisation or plugin, as they’re shared between all plugins in the application.

std_action_panel:build_panel

The std_action_panel:build_panel service will create a PanelBuilder, call the various services to populate it, and return it.

It takes two arguments, the panel name and a display object. The display object will be filled out with display.options.panel if you don’t specify it.

For example, to build a PanelBuilder for a person object:

var personRef = /* obtain ref to object somehow */
var person = personRef.load();
var builder = O.service("std_action_panel:build_panel", "person", {
    object: person
});
// builder is a populated PanelBuilder for that person