Last publication:23/02/2018at 2:43 PMCédricDamioli
Introduction
This document explains how to develop a control (such as a button) for the ribbon
Declaration
You first need to declare the button as an extension to the RibbonControlsManager extension point.
You have to use the ContextualClientSideElement interface to do so. See the ClientSideElement page for more information.
Javascript
The js class must inherit org.ametys.ribbon.control.RibbonControl.
The constructor will receive
the id used during the declaration
the parameters
the plugin name where the declaration was made
A method createControl will be called to make you create the control you want to design.
Implementations
UniqueInstanceToolButton
This implementation creates a button that toggle when then associated tool is opened.
The parameters are :
role : The role name of the factory of the tool
label : The button label
default-description : The default button tooltip
footer : The tooltip footer
icon-small : The path to the icon 16x16 (relative to the resources of the plugin)
icon-medium : The path to the icon 32x32 (relative to the resources of the plugin)
icon-large : The path to the icon 48x48 (relative to the resources of the plugin)
ActionButton
This implementation creates a simple button that call a js function when pressed.
The parameters are :
action : The name of a JS function (arguments are : id, configuration and plugin name) called when clicking the button
initialize : The name of a JS function (arguments are : id, configuration and plugin name) called during the creation of the button
label : The button label
default-description : The default button tooltip
footer : The tooltip footer
icon-small : The path to the icon 16x16 (relative to the resources of the plugin)
icon-medium : The path to the icon 32x32 (relative to the resources of the plugin)
icon-large : The path to the icon 48x48 (relative to the resources of the plugin)
WorkflowMenu
Introduction
This implementation allows to create workflow button menus.
These are buttons that are disabled when not reflecting the current workflow state and enabled/toggled if they do. Moreover the button has a menu refleting actions of workflow that can be done.
Note that if no actions are available, the button is still toggle but grayed.
What you can do easly
choose the state of workflow to represent
have a menu with all possible actions of workflow
have a menu with only determined actions of workflow (that may be no actions)
override anything such as
the icon/label/description of the button
the button action
an action label/description or handler : for example that allows you to ask for a comment before sending the request to the workflow
...
Configuration
Here is the minimal configuration, of a button that display the state "1" of the worflow with a menu with all actions relative to that state.
Oops !
Copy to clipboard failed. Open the code and copy it manually.
This minimalist configuration imply some conventions to use in the workflow file.
Label of workflow states are i18n keys using the convention "CATALOGUE:KEY" where the default catalogue is "application".
Description of workflow states are i18n keys using the convention "CATALOGUE:KEY" + "_DESCRIPTION" where the default catalogue is "application".
Images of workflow states are taken
if "application" catalogue is chosen, in WEB-INF/param/worfklow_resources/KEY_SIZE.png where KEY is the i18n key of the label and SIZE a size between "small" (16x16), "medium" (32x32) and "large" (48x48)
if the catalogue of a plugin is chosen, in the plugin resources folder /img/workflow/KEY_SIZE.png where KEY is the i18n key of the label and SIZE a size between "small" (16x16), "medium" (32x32) and "large" (48x48)
The same is done for workflow actions, but currently onlu label is working (description and images will be soon)
Options
Choose actions
You can limit available actions using
Oops !
Copy to clipboard failed. Open the code and copy it manually.
By default, during the selection event (in message bus) target type matched are only the "content" target
You can change configuration to look for others selection events.
The parameter name is selection-type
Oops !
Copy to clipboard failed. Open the code and copy it manually.
<param i18n="selection-type">odf-content</param>
<param i18n="selection-type">odf-content</param>
<param i18n="selection-type">odf-content</param>
Multi selection
By default multi selection is enabled
Set true or false in enable-multiselection
Other parameters
label : default label. (see convention for default value)
default-description : main description that is always visible. (see convention for default value)
footer : tooltip footer
action : the js action when button is pressed. Default is empty since it opens the menu.
icon-small : image path relative to the plugin resources.
icon-medium : image path relative to the plugin resources.
icon-large : image path relative to the plugin resources.
noselection-description : the message when selection is empty (and the button grayed)
refreshing-description : the message when the button is refreshing.
nomatch-description : the message when selection type is wrong
multiselection-disabled-descruotion : the message when a multiselection occured when disabled
contentselected-description-begin : the begin of the message part representing selection
contentselected-description-end : the end of the message part representing selection
menu-ACTIONID-label : replace ACTIONID by the id of the action, to override the label of the action in the menu
menu-ACTIONID-description : replace ACTIONID by the id of the action, to override the description of the action in the menu
menu-ACTIONID-action : replace ACTIONID by the id of the action, to override the js called of the action in the menu. When you do this, you have this.ribbonControl._lastParams to get the last hot configuration ; selected contents are in this.contents)
editing-description : the message when the button cannot be used because the current content is in edition mode
Static Menu
TODO
Class name : org.ametys.cms.clientsideelement.StaticMenu
Dynamic buttons
Buttons may need server information at any time. See the ClientSideElement page for information on how to dynamise elements.
Please remember that buttons are already registrered to the messagebus.