Pre-General Availability: 2018-5-8

Interface: actions

QuickNav

Properties

Methods

actions

The actions interface manages a collection of actions.action objects. An action encapsulates the identity, state and behavior of a named operation or procedure that the user initiates via a user interface element. Actions are most useful when an operation can be initiated in multiple ways such as with a button or toolbar button, menu, or keyboard shortcut. The operation should be labeled consistently and if it can be enabled and disabled that state must be kept consistent. By using an action and then associating a button and/or menu item with that action all aspects of the action are centralized and kept in sync. This avoids duplicating labels, icons etc.

Actions Contexts

The apex.actions singleton (which is also the apex.actions namespace) manages all the global (page level) actions. For components that can have multiple instances on a page the global actions will not work because it is not clear which instance of the component the action applies to. To support components the apex.actions.createContext function is used to create an actions interface that is scoped to a specific component instance (the context). Typically the component (e.g. widget) would call apex.actions.createContext when it is created and apex.actions.removeContext when it is destroyed.

For global actions and any other created actions contexts the methods on the actions object are used to add, remove, lookup, and invoke actions. There are also methods to manage keyboard shortcuts. Additional state can be stored in the action if desired. If any of the action properties change then apex.actions.update must be called.

Actions are associated with other controls that invoke the action. It is also possible to invoke the action explicitly with the actions#invoke method. To toggle actions the actions#toggle method is used and for radio group actions the actions#set method is used to change the value. The following sections describes how to associate actions with various controls.

Buttons

To associate a button element with an action give it a class of js-actionButton and a data-action attribute with the name of the action as its value. The button icon, label text, title, aria-label, hide/show, and disabled state are all updated automatically.

For this automatic updating to work buttons should use the following classes:

  • t-Button-label if a button has a text label this class should be on an element that wraps the text. This is useful when the button also has an icon or other non text label content. This class does not go on the button element. If this class is not used then the content of the button element will be the label text.
  • t-Button--icon if a button has an icon this class should be on the button element. If the action has an icon and the button has this class then any elements with the icon type class will be updated with the icon. Any classes on the icon element that are not the icon, the icon type or start with "t-" will get removed.
  • t-Button--noLabel if a button has no visible label this class should be on the button element. A button with no visible label text will have the button's aria-label attribute set to the button label. Also if there is no title the label will be used as the title.

If the action label or title are null they will be initialized with the text and title attribute value respectively from the first button (in document order) associated with the action. This is useful if the server has already rendered a localized button for the action. The title comes from the button title attribute. The label comes from the first found of; aria-label attribute, title attribute if button has class t-Button--noLabel, content of the descendant element with class t-Button-label, and finally the button element content. If disabled is null it will be taken from the button disabled property. If you don't want the label, title, or icon to be updated add attribute data-no-update="true".

Example:

    <button class="js-actionButton" data-action="undo">Undo</button>

Checkboxes

A checkbox can be associated with a toggle action by giving the input element (or a wrapping parent element) a class of js-actionCheckbox and a data-action attribute with the name of the action as its value. The checkbox should have a label element. The icon, label text, title, hide/show, disabled state, and checked state are all updated automatically. For hide to work correctly use a wrapping element.

If the label has the class t-Button then it should be marked up like a button and the same classes described for a button are used to update the label and icon (except a visually hidden child element is used for the label in place of aria-label). Otherwise the label element content will be updated with the label and the icon is not used. If the action label or title are null they will be initialized from the markup. If the checkbox label is marked up like a button then the label comes from the text of a child element with class t-Button-label or if the label has class t-Button--noLabel then from a child element with class u-VisuallyHidden. If you don't want the label, title, or icon to be updated add attribute data-no-update="true".

Example:

    <input id="abc" type="checkbox" class="js-actionButton" data-action="optionA"><label for="abc">Option A</label>
   or
    <div class="js-actionButton" data-action="optionA">
        <input id="abc" type="checkbox"><label for="abc">Option A</label>
    </div>

Radio groups:

A radio group is a set of input elements of type radio and sharing the same name value. A radio group can be associated with a radio group action by giving the element that wraps the radio group a class of js-actionRadioGroup and a data-action attribute with the name of the action as its value. The wrapper element aria label is kept in sync with the action label. The radio group as a whole does not have a disabled state, icon or title. When the radio action value changes (or when update is called) the checked state (and disabled state) of each radio input is updated.

The element with class js-actionRadioGroup can also have attributes: data-item-start, data-item, data-item-end, data-item-wrap to override action properties labelStartClasses, labelClasses, labelEndClasses, and itemWrapClasses respectively.

If the action label is null it will be initialized from the wrapper element aria-label. If the wrapping element has no children when the action is added or when updateChoices is called (after the choices have been changed) then the choices are rendered as radio input, label pairs elements. The action labelStartClasses, labelClasses, labelEndClasses values are used for the classes of the label elements. If there is an icon it will be used as the label. The label will be included as a hidden but accessible label. The label element will have a title if there is a title property or if the choice has an icon. The title comes from the label property if the title property isn't given.

Example:

    <div class="js-actionRadioGroup" data-action="itemSize">
      <input id="lc1" type="radio" name="RG1" value="s"><label for="lc1">Small</label>
      <input id="lc2" type="radio" name="RG1" value="m"><label for="lc2">Medium</label>
      <input id="lc3" type="radio" name="RG1" value="l"><label for="lc3">Large</label>
    </div>

Select List

To associate a select element with a radio group action give it a class of js-actionSelect and a data-action attribute with the name of the action as its value. Select lists used with actions are assumed to not have an associated label element. The select element aria label, title, value, and disabled state are kept in sync with the action. When the radio action value changes (or when update is called) the select element value is updated and also the disabled state of each option element.

If the action label or title are null they will be initialized from the select element aria-label and title attributes. If the select element has no children when the action is added or when updateChoices is called (after the choices have been changed) then the choices are rendered as option elements. The choice group property is used to put options in optgroup elements. The group property value is used as the optgroup label. The choices need to be sorted first by group value.

Example:

    <select class="js-actionSelect" data-action="itemSize">...</select>

Menu items

For menu widget menu items of type action, toggle, or radioGroup simply specify the action name as the value of the action property. Values for label, icon, iconType, disabled, hide, and accelerator are taken from the action (accelerator is taken from the action shortcut property). It is possible to override action values such as label and icon by specifying them in the menu item.

Examples: 
    { type: "action", action: "undo" },
    { type: "toggle", action: "myToggleAction" },
    { type: "radioGroup", action: "myRadioAction" }

Shortcuts:

Shortcuts are not an actual widget or a DOM Element. The keyboard event handler for invoking actions in response to shortcut keys is in this module and is registered on the context element (body for the global context).

Associating actions with custom UI controls

To integrate actions with other UI controls:

  • Devise a way to specify the action name. For example using a class such as js-actionRadioGroup and an attribute such as data-action attribute on an appropriate element. For widgets the action name could be passed as an option to the initialization function.
  • Register an observer call back using actions#observe to get notified when the action is added, removed, or updated. Use this callback to update the state of the UI control such as enabling or disabling it or changing the label or icon.
  • Call the invoke method when it is time to invoke the action.
Since:
  • 5.0

Properties

context

This is the Element context that actions are scoped within as given in the apex.actions.createContext call.

type {Element}

typeName :string

This is type name of the actions context as given in the apex.actions.createContext call. The typeName of the global context apex.actions is "global".

Type:
  • string

Methods

add(pActions) → {boolean}

Add an actions.action object or an array of actions.action objects to this actions context. The action name must be unique within the context and the shortcut if any must be unique within the context and valid. Debug warnings are logged if any of these conditions are not met.

Parameters:
Name Type Description
pActions actions.action | Array.<actions.action> The action or an array of actions to add.
Returns:
true if all the actions and shortcuts are added without errors or warnings, false otherwise.
Type
boolean

addFromMarkup(pList$)

Add one or more actions.action objects from simple list markup. This is useful in cases where it is easier to render list markup than an array of action objects. This does not support adding actions with functions but action functions can be added either before or after.

The markup expected by this method overlaps with what the menu widget expects.

Expected markup:
An element with a ul child. The ul has one or more li elements each one representing an action. The li element can contain either an "a" or span element.

Action property Comes from
name li[data-id]
label a or span content
title a[title] or span[title]
href a[href]
disabled true if li[data-disabled=true] false otherwise
hide true if li[data-hide=true] false otherwise
shortcut li[data-shortcut]
icon li[data-icon] If the value has a space the icon is the word after the space otherwise it is the whole value
iconType li[data-icon] If the value has a space the type is the word before the space

If there is no name or label or the value of href equals "separator" then no action is created for that li. If the li has a ul child the ul is processed recursively.

Parameters:
Name Type Description
pList$ jQuery The jQuery object representing the parent of the actions list markup.

addShortcut(pShortcutName, pActionName, pChoiceValueopt) → {boolean}

Add a keyboard shortcut synonym for an action. Debug warnings are logged if there are problems.

Parameters:
Name Type Attributes Description
pShortcutName actions.shortcutName The keyboard shortcut synonym to add.
pActionName string {string} The name of the action to add a shortcut for.
pChoiceValue string <optional>
 Choice value only if the action is a radio group. The shortcut will select the given choice.
Returns:
true if successful and false if there is no such action or there is a duplicate shortcut.
Type
boolean

clear()

Remove all actions from this actions context.

disable(pActionName)

Disable UI elements associated with the action by setting disabled property to true. This is a convenience method to disable without having to call actions#lookup and actions#update.

Parameters:
Name Type Description
pActionName string The name of the action to disable.

disableShortcuts()

This is used to disable all shortcuts temporarily. Call at the start of a user interaction that should have shortcuts disabled for example a custom popup. Call enableShortcuts when finished. It is called automatically when modal dialogs or menus open. Calls can be nested. For each call to disableShortcuts there should be a corresponding call to actions#enableShortcuts.

enable(pActionName)

Enable UI elements associated with the action by setting disabled property to false. This is a convenience method to enable without having to call actions#lookup and actions#update.

Parameters:
Name Type Description
pActionName string The name of the action to enable.

enableShortcuts()

This is used to enable all shortcuts after they were disabled with actions#disableShortcuts. It is called automatically when modal dialogs or menus close. Calls can be nested. For each call to actions#disableShortcuts there should be a corresponding call to enableShortcuts.

get(pActionName) → (nullable) {string}

Return the current value of a radio group action.

Parameters:
Name Type Description
pActionName string The name of the action.
Returns:
The current value.
Type
string

hide(pActionName)

Hide UI elements associated with the action by setting the hide property to true. This is a convenience method to hide without having to call actions#lookup and actions#update.

Parameters:
Name Type Description
pActionName string The name of the action to hide.

invoke(pActionName, pEventopt, pFocusElement) → {boolean|undefined}

Invoke the named action.

Parameters:
Name Type Attributes Description
pActionName string Name of the action to invoke.
pEvent Event <optional>
 Browser event that caused the action to be invoked.
pFocusElement Element The element that will receive focus when the action is complete.
Returns:
false if there is no such action or action has no action method, true if action set the focus all other cases should return undefined.
Type
boolean | undefined

list() → {Array}

Return an array of actionName, label pairs for all actions in the context.

Returns:
An array of objects with name and label properties.
Type
Array

listShortcuts() → {Array.<actions.shortcutListItem>}

Return a list of all shortcuts in the context.

Returns:
An array of objects with information about the shortcut.
Type
Array.<actions.shortcutListItem>

lookup(pActionName) → {actions.action}

Lookup and return an action by name.

Parameters:
Name Type Description
pActionName string The name of the action to return.
Returns:
action or undefined if action doesn't exist
Type
actions.action

observe(pCallback)

Register a callback function to be notified when an action changes. This is used to update UI elements associated with an action when that action state changes. The most common elements including buttons, checkbox and radio group inputs, select lists, and menus are already handled.

Parameters:
Name Type Description
pCallback function function notifyObservers( action, operation ) operation is one of "add", "remove", "update", or "updateChoices"

remove(pActions)

Remove one or more actions.action objects from this actions context.

Parameters:
Name Type Description
pActions actions.action | string | Array.<actions.action> | Array.<string> The action or action name or an array of actions or an array of action names to remove.

removeShortcut(pShortcutName) → {boolean}

Remove a keyboard shortcut synonym for an action.

Parameters:
Name Type Description
pShortcutName actions.shortcutName The keyboard shortcut synonym to remove.
Returns:
true if successful false if the shortcut is the primary shortcut for an action.
Type
boolean

set(pActionName, pValue)

Set the value of a radio group action or toggle action.

Parameters:
Name Type Description
pActionName string The name of the action.
pValue string | boolean The value to set.

shortcutDisplay(pShortcutName) → {string}

Return the friendly display string for a keyboard shortcut name.

Parameters:
Name Type Description
pShortcutName actions.shortcutName Keyboard shortcut to get the display string for.
Returns:
A friendly version of the shortcut. The display string is sensitive to the operating system.
Type
string

show(pActionName)

Show UI elements associated with the action by setting the hide property to false. This is a convenience method to show without having to call actions#lookup and actions#update.

Parameters:
Name Type Description
pActionName string The name of the action to show.

toggle(pActionName) → {boolean|undefined}

Toggle the named action. This should only be used for toggle actions. Toggle actions have get and set methods and don't have a choices property.

Parameters:
Name Type Description
pActionName string Name of the action to toggle.
Returns:
false if there is no such action or action doesn't have get/set methods all other cases should return undefined
Type
boolean | undefined

unobserve(pCallback)

Remove callback.

Parameters:
Name Type Description
pCallback function The function that was added with actions#observe.

update(pActionName) → {boolean}

Update any UI elements associated with the action after it changes. Calling update will notify any observers that the action has changed. Debug warnings will be logged and the return value is false if the action has a problem with the shortcut.

Parameters:
Name Type Description
pActionName string The name of the action to update.
Returns:
false if the shortcut is invalid or a duplicate and true otherwise.
Type
boolean

updateChoices(pActionName) → {boolean}

Call this only if the set of choices for an action has changed. This will notify any observers that the set of action choices has changed.

Parameters:
Name Type Description
pActionName string The name of the action that has had its choices updated.
Returns:
false if the action has no choices and true otherwise
Type
boolean

Type Definitions

action

There are 3 kinds of actions:

  • action: This is typically associated with a button or action menu item. The action must have an action function or an href URL.
  • toggle: This is typically associated with a checkbox input, button, or toggle menu item. The action must have get and set functions and not have a choices property. Toggle actions update an external Boolean state variable by means of the get and set functions. It is also possible to keep the state in the action by using 'this' in the get and set functions.
  • radio group: This is typically associated with radio inputs, select list, or a radioGroup menu item. The action must have get and set functions and a choices property. Radio group actions update an external state variable with the currently selected value of the group by means of the get and set functions. It is also possible to keep the state in the action by using 'this' in the get and set functions.

Note: The disabled and hide properties cannot be functions. Menu widget can use actions and non-action based menu items allow hide and disabled to be functions. But when a menu uses an action that action still must not use functions for disabled and hide.

As an alternative to label (or onLabel, offLabel) you can specify labelKey (or onLabelKey, offLabelKey) and the apex.lang.getMessage function will be used to lookup the label text. The localized label text is then stored in the normal label/onLabel/offLabel property. This happens when the action is added. The same applies to titleKey groupKey, and labelKey of each object in the choices array.

Type:
  • object
Properties:
Name Type Attributes Description
name string A unique name for the action. By convention the style of names uses a dash to separate words as in "clear-log". Name must not contain spaces, ">", ":", quote, or double quote, or non-printing characters.
label string translatable label for action used in buttons, menus etc. Note: if this is a radio group action (action has choices property) the label is optional. It is used in results of the list and listShortcuts methods. Depending on what kind of UI control the action is bound to it may be used as a label for the whole group. For example using aria-label.
onLabel string <optional>
 Only for dynamic antonyms toggle actions. This is the label when the value is true.
offLabel string <optional>
 Only for dynamic antonyms toggle actions. This is the label when the value is false.
contextLabel string <optional>
 A more descriptive label used in place of label for use in listing actions and shortcuts.
icon string <optional>
 The icon for action may be used in buttons and menus
iconType string <optional>
 The icon type. Defaults to a-Icon. Updates to the iconType may not be supported by all control types that can be associated with actions.
disabled boolean <optional>
 Disabled state of action; true if the action is disabled and false if it is enabled. The default is enabled
hide boolean <optional>
 Hidden state of action; true if UI controls connected to this action should be hidden and false otherwise. The default is false (show).
title string <optional>
 The title to use as the title attribute when appropriate.
shortcut actions.shortcutName <optional>
 The keyboard shortcut to invoke action (not allowed for radio group actions).
href string <optional>
 For actions that navigate set href to the URL to navigate to and don't set an action function. An action of type action must have an href or action property set.
action function <optional>
 function(event, focusElement):boolean The function that is called when the action is invoked with actions#invoke. The action must return true if it sets focus. An action of type action must have an href or action property set.
get function <optional>
 For toggle actions this function should return true or false. For radio group actions this should return the current value.
set function <optional>
 For toggle actions this receives a boolean value. For radio group actions this function receives the new value.
choices Array <optional>
 This is only for radio group actions. Array of objects. Each object has properties: label, value, icon, iconType, shortcut, disabled, group (for select lists only)
labelClasses string <optional>
 This is only for radio group actions. Classes to add to all radio labels. This and the next two label properties are only used when rendering radio group choices.
labelStartClasses string <optional>
 Only for radio group actions. Classes to add to last radio label
labelEndClasses string <optional>
 Only for radio group actions. Classes to add to last radio label
itemWrapClasses string <optional>
 Only for radio group actions. Classes to add to a span wrapper element. Or to change the span use one of these prefixes: p:, li:, div:, span:
For example "li:myRadio"

shortcutListItem

Information about a shortcut.

Type:
  • Object
Properties:
Name Type Description
shortcut string The shortcut name.
shortcutDisplay string The shortcut display string.
actionName string The name of the action that the shortcut invokes.
actionLabel string The label of the action. For choice actions this includes the choice label.

shortcutName

This is the string name of a keyboard shortcut. It represents the key(s) to be typed by the user and can be a single key combination or a sequence of keys. The shortcut name must be given in the following format:


  [Ctrl+][Alt+][Meta+][Shift+]key

Where strings in square brackets ([]) are optional and represent a modifier key. The string key is the name of the key and may be one of: "0"-"9", "A"-"Z" or "Help", "Backspace", "Enter", "Escape", "Space", "Page Up", "Page Down", "End", "Home", "Left", "Up", "Right", "Down", "Insert", "Delete", "Keypad 0"-"Keypad 9", "Keypad *", "Keypad +", "Keypad -", "Keypad .", "Keypad /", "F1"-"F12", "Comma", "Period", "Semicolon", "Minus", "Quote", "Backtick", "=", "/", "[", "\", "]".

Order and case is important. Key names and modifiers are not localized.

The shortcut name can be a sequence of key combinations separated by commas. The user types the shortcut by typing the first key combination followed by the second and so on. It is possible to have a sequence of length one, which allows defining shortcuts as single letters without any modifier key. Letters can be in upper or lower case.

The primary shortcut for an action is specified in the shortcut property of the actions.action object. This is so that it can be shown in associated menu items. Additional shortcuts can be added with actions#addShortcut.

One limitation of shortcuts in the browser environment is that it is difficult to find keyboard combinations that are not already used for something else and are consistent across all browsers, operating systems and with all keyboard layouts. Key combinations used by the operating system or browser may not be passed on to the actions keydown handler or even if they are the browser or operating system function has also already happened. Many keyboard layouts use the Right side Alt key (known as AltGr) to enter additional characters. The AltGr key can be simulated by pressing Ctrl+Alt. This makes some Ctrl+Alt combinations unavailable. On Mac OS the Option/Alt key plus a letter or number is used to produce additional characters.

See apex.actions.shortcutSupport for information about what kinds of shortcuts if any the user can type. If shortcut support is "off" then no shortcuts are recognized. Shortcut sequences are only recognized if shortcut support is "sequence". Shortcuts can always be defined.

When focus is in a control that allows character input then shortcuts that would produce printable characters or are used for editing are ignored by actions. This includes controls such as text fields and text areas but also controls such as select lists that support type to select.

Type:
  • string
Examples

Example key combinations. Press the modifier keys in combination with the specified key: W, F7, Page Down.

  Ctrl+W
  Ctrl+Shift+F7
  Alt+Page Down

Example key sequence. Press the first key combination Ctrl+F2 and release then press the G key and then the H key. For the second example press the C key then the S key. In the third example press C then 6 (not Shift+6). In the last example simply press W. Although the letters must be in upper case in the shortcut name they can be typed with our without the Shift modifier. All but the first example will be ignored when focus is in a control that takes character input. 

  Ctrl+F2,G,H
  C,S
  C,6
  W