Ribbon Control

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.

<extension id="MYID"
           point="org.ametys.cms.workspace.ribbon.RibbonControlsManager"
           class="org.ametys.cms.clientsideelement.WorkflowMenu">
    <workflow name="content">
        <step>1</step>
    </workflow>
</extension>
Conventions

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

<workflow name="content">
   <step>1</step>
   <actions mode="include">
       <action>1</action>
       <action>2</action>
   </actions>
</workflow>

To take only action 1 and 2.

Please note that these actions will never appears if action 1 and 2 are not actions for the state 1

You can also choose all possible actions but 1 and 2 by choosing mode="exclude".
If the <actions> tag is missing it is like it is

   <actions mode="exclude"/>

If you want no actions to be available, you can write

   <actions mode="include"/>
Overriding the JS class

You may wan to inherit the WorkflowMenu js class. Add

<action class="MyJSClass.js"/>
<script>
    <file>js/myjsfile.js</file>
</script>
Other options

Other options are available using the classical param

<action>
   <param i18n="true|false">value</param>
</action>
Target type

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

  <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.