Méthode Swing allows to add custom commands. Such commands can be launched in different situations, such as external DAM searches, custom Object Panels and widgets. Furthermore, M´thode Swing allows to configure such commands in specific parts of the User Interface (UI) such as, for example, the Toolbar inside the Explorer tab or the Explorer Grid (via Column Catalog).

Prepare the plugin to add commands

In general, all the extensions of Méthode Swing are places under

{SWING-APP}/plugins

So, all the Javascript described in the following sections should be placed under

{SWING-APP}/app/plugins/{EXTENSION-FOLDER}/{EXTENSION-NAME}.js

Do not use the word libs as an extension folder. The libs folder is reserved for loading external libs. See the proper documentation to obtain further info on the topic.

DEBUG MODE: by default, all plugins are aggregated into a single plugins.js file at the Tomcat startup. When creating a plugin, it may be frustrating to restart the Tomcat Server every time a change is made.

To avoid this, set the configuration property debugEnabled to true.

Then, that extension will be loaded on every refresh of the page.

Format of a command

A command is represented by a JSON object which should contain at least the following properties:

// Command options
{
    name: "" ,// commandName
    methodeContext: [],
    isActive: function( ctx ) { /* ... */ },
    isEnabled: function( ctx ) { /* ... */ },
    action: function( ctx, params, callback ) { /* ... */ },
    icon: 'icon-compass',
    label: 'My label'
}

name

The unique command name. Please note that the name parameter will be also used for the action label localization. The key toolbar.name will be to be used in order to retrieve a translated string from Swing translation files.

The command name is mandatory.

methodeContext

The list of applications (JSON Array) where this command should be available, allowed values: swing, desktop (Prime Dashboard), mobile and all.

isActive

The isActive method is used to determine whether a command must be added to the context of reference. That is, for example, whether a custom button should be added to a toolbar.

The isActive method has the Context Object as the only parameters. See Basic structure of the Context Object for further details on the Context Object.

This is the best place to check for particular privileges.
Each default Swing context calls the isActive method with different parameters. See Swing default contexts to see the different parameters used by the different Swing contexts.

isEnabled

The isEnabled method is used to determine whether a command must be enabled and disabled according to the current situation. That is, for enable, whether a custom button in a toolbar should be enabled according to the current selection.

The isEnabled method has the Context Object as the only parameters. See Basic structure of the Context Object for further details on the Context Object.

This is the best place to check for the current selection ( selected items, text selection, etc. according to the context)
Each default Swing context calls the isEnabled method with different parameters. See Swing default contexts to see the different parameters used by the different Swing contexts.

action( ctx, params, callback )

The action property is a Javascript function which is called when a command is executed.

The parameters are the following:

  • ctx: the Context. See Basic structure of the Context Object for further details on the Context Object.

  • params: a list of params to be passed to the action.

  • callbacks: if available, it is an object containing the success and the error functions.

Every context inside Méthode Swing calls the commands with different values for the params and the callback arguments. See Swing default contexts to see the different parameters used by the different Swing contexts.

icon

Describes the icon associated with the command. See here for a list of available icons.

The icon property is optional.

label

Describes the label associated with the command.

The label property is optional.

Register, obtain and execute commands

Commands are, basically, functions that can be called in particular cases. The commands can be associated with specific Swing contexts (such as the Toolbars, or the Grid rows), or can be executed freely from inside the user plugins.

While the basic command format is equal for any case, the command registration is different according to the context of reference. The following paragraphs describe this concept in details.

"Free" command registration and execution

In this case, the user registers a command without associating it with a particular context. For this, all the methods to add, get and execute commands are within the following namespace:

eidosmedia.webclient.commands

Available methods are add, get, exec, defined as follows:

// Add a new command
eidosmedia.webclient.commands.add( command );

// Get the command object
eidosmedia.webclient.commands.get( commandName );

// Execute a command
eidosmedia.webclient.commands.exec( commandName, ... );

add( command )

Adds a command to Méthode Swing. It needs one parameter:

It is recommended not to use standard names such as edit, save, etc. because there is the risk to override standard Swing commands.
Example
eidosmedia.webclient.commands.add({
    name: 'myCustomCommand',
    icon: 'icon-compass',
    label: 'Perform some complex operation...',
    isActive: function( ctx ) {
        // check privileges...
        return true;
    },
    isEnabled: function( ctx ) {
        // check current selected items...
        return true;
    },
    action: function( ctx, params, callbacks ) {
        if ( ctx.component.getType() === 'toolbar') {
            // perform same difficult operations...
            if (callbacks && callbacks.success) {
                callbacks.success( /*...*/ );
            }
        }

    }
});

get( commandName )

Return a Javascript Object containing all the properties of the command, as defined in the previous set method.

Example
var cmd = eidosmedia.webclient.commands.get( 'myCustomCommand' );

/*
Now cmd is: {
    icon: 'icon-compass',
    label: 'Perform some complex operation...',
    isActive: function( ctx ) {
        // check privileges...
        return true;
    },
    isEnabled: function( ctx ) {
        // check current selected items...
        return true;
    },
    action: function( ctx, params, callback ) {
        if ( ctx.component.getType() === 'toolbar') {
            // perform same difficult operations...
            if (callbacks && callbacks.success) {
                callbacks.success( /*...*/ );
            }
        }

    }
*/

exec( commandName, …​ )

It is the method to execute a particular command.

var result = eidosemdia.webclient.commands.exec('myCustomCommand', ctx, params, callbacks );

The only mandatory param is commandName, which is the name of the command to execute. All the other parameters are passed as-is to the command.

As said above, Méthode Swing calls the custom commands with three parameters: ctx, params and callback. The nature of these parameters changes according to which context is using the command. See Swing default contexts to see the different parameters used by the different Swing contexts.

Of course, if the custom commands are used only within your extensions ( and not by default Swing contexts ), it is possible to use any parameter of choice.
Sample
/** in a custom widget, for example */

var btn = document.getElementById('myButton');

$(btn).on('click', function() {
    eidosmedia.webclient.commands.exec('myCustomCommand', 'all', 'my', 'parameters', 'here', true, [ { everything: 'ok' } ]);
});

Registration of a command to a context

See Swing default contexts for further info on how to register and work with different Swing contexts.

Basic structure of the Context Object

The Context object is made of a specific list of properties, and a number of publicly available methods.

{
    application: {
        getId: function()
    },
    area: {
        getType: function(),
        getName: function(),
        getContext: function()
    },
    component: {
        getType: function()
    },
    activeObject: {
        // Methods of the single object.
    },
    activeObjects: [{activeObject}] // An array of activeObject
    selection: [ ] // Array of objects. See below.
}
Table 1. Parameters list
Parameter Value type Description Values

application.getId()

String

Returns the application Id.

"swing", …​

area.getType()

String

Returns the area type.

"main" (for the main views), "editor"

area.getName()

String

Returns the area name.

"explorer", "dashboard", "myarea", "liveblogmanagement" (for "main" areas). "story" (for editors).

area.getContext()

String

Returns the area context.

"story-editor", "report-editor", "dwp-editor", "topic@editor", "topic@search", "topic@binder", "topicplan@editor", "topicplan@search", "topicplan@binder", "topicitem", "upload", "diagram-workflow", "search", "planning-calendar"

component.getType()

String

Returns the component type.

"toolbar", "grid", "objectpanel"…​

activeObject

Object

Returns an object with a set of methods. Refer to : Methods of the single object for the list of methods.

activeObjects

Array

Returns an array of activeObject(s). In bulk selection mode all selected items are returned here as array. In single selection mode array length is 1. Each activeObject is coupled with one selected item. Methods of the single object operate to that item.

selection

Array of Object

Returns an array with the currently selected items. Each item has the same set of methods available. Refer to : Methods of the single object for the list of methods.

Each context has a different value for these properties.

Methods available in the Context Object

Further details on the methods available in the Context Object can be found in the Context Object Methods reference.

Swing default contexts

Explorer Toolbar

Context Object properties for the Explorer Toolbar

The Object Panel context has the following values:

Table 2. Parameters list
Parameter Values Description

area.getType()

"main"

area.getName()

"explorer"

component.getType()

"toolbar"

activeObject.getId()

String

Return the ID of the current folder / query opened in the Explorer.

activeObject.getInfo()

JSON

Return the info of the current folder / query opened in the Explorer.

activeObject.getType()

JSON

Return the type of the current folder / query opened in the Explorer.

activeObject.invalidate() (additional)

(void)

Invalidates all the changes and refresh the content of the current folder / query.

selection

JSON Array

Returns an array with the currently selected items in the folder/query. Each item has the same set of methods available. Refer to : Methods of the single object for the list of methods.

Associate commands to the toolbar

It is possible to register the command with the commands.add method ( see add( command ) for futher details ).

Then the commands must be associated to the toolbar as follows:

eidosmedia.webclient.actions.explorer.toolbar.addButton({
    action: "COMMAND NAME",
    label: "Label",
    icon: "Icon"
});

or, it is possible to pass directly the command object to the same function, e.g. :

eidosmedia.webclient.actions.explorer.toolbar.addButton({
    name: "cox.resetPriority",
    isActive: function( ctx ) { /* ... */ },
    isEnabled: function( ctx ) { /* ... */ },
    action: function( ctx, params, callbacks ) { /* ... */ },
    icon: 'icon-compass',
    label: 'My label'
});

The toolbar actions are called without a params and a callbacks parameter.

Grid Items

These values are valid for any grid. At the moment, only the Explorer grid is managed.

Context Object properties for the Grid Item

The Object Panel context has the following values:

Table 3. Parameters list
Parameter Values Description

component.getType()

"grid-item"

component.getId()

String

Not available

activeObject.getId()

String

Return the ID of the current item (grid row).

activeObject.getInfo()

JSON

Return the info of the current item (grid row).

activeObject.getType()

JSON

Return the type of the current item (grid row).

selection

JSON Array

Not available (empty array)

It is possible to register the command with the commands.add method ( see add( command ) for futher details ).

Then the commands must be associated to the grid item as follows:

eidosmedia.webclient.actions.explorer.grid.addEditor({
    action: "COMMAND NAME",
    label: "Label",
    icon: "Icon"
});

or, it is possible to pass directly the command object to the same function, e.g. :

eidosmedia.webclient.actions.explorer.grid.addEditor({
    name: "cox.resetPriority",
    isActive: function( ctx ) { /* ... */ },
    isEnabled: function( ctx ) { /* ... */ },
    action: function( ctx, params, callbacks ) { /* ... */ },
    icon: 'icon-compass',
    label: 'My label'
});

Object panel

Context Object properties for the ObjectPanel

The Object Panel context has the following values:

Table 4. Parameters list
Parameter Values Description

component.getType()

"objectpanel"

component.getId()

String

The id of the ObjectPanel DOM Element ( e.g. '#em-metadata-area' )

activeObject.getId()

String

Return the ID of the current object

activeObject.getInfo()

JSON

Return the info of the current object

activeObject.getType()

JSON

Return the type of the current object

selection

JSON Array

Not available (empty array)
Additional methods in the Context Object for Object Panel.
Table 5. Parameters list
Method Available in

activeObject.getUniqueMetadataId()

preFillForm - postFillForm - preSave - postSave - onClose

activeObject.setReadonly()

preFillForm - postFillForm - preSave - postSave - onClose

activeObject.showLoading()

preFillForm - postFillForm - preSave - postSave - onClose

activeObject.hideLoading()

preFillForm - postFillForm - preSave - postSave - onClose

activeObject.getMetadataXML()

preFillForm - postFillForm - preSave - validate - postSave - onClose

activeObject.setMetadataXML()

preFillForm - onClose

activeObject.getImage()

onImageProcessing

activeObject.setFieldValue()

postFillForm - preSave

activeObject.getFieldValue()

postFillForm - preSave

activeObject.refreshMetadata()

postFillForm - postSave - onClose

activeObject.saveMetadata()

preFillForm - postFillForm - onClose

activeObject.notifyMetadataChange()

postFillForm

activeObject.refreshPanel()

onUpdatesAvailable - onEvent
getUniqueMetadataId()

Return the same unique id used in the HTML panel whenever a -<%=uniqueMetadataId%> has been used to generate a unique Id.

The syntax is the following:

var uniqueId = ctx.activeObject.getUniqueMetadataId(); // e.g "5";
var uniqueId = ctx.activeObject.getUniqueMetadataId(); // e.g "5";
// In this way we ensure that the only the current custom panel is referenced
$('#myCustomPanel-' + uniqueId) // ...
setReadonly()

Creates a readonly layer over the object Panel. The syntax is the following:

ctx.activeObject.setReadonly( [value] );

Value can be true (default) or false.

showLoading(), hideLoading()

Shows or hides a loading element. The syntax is the following:

ctx.activeObject.showLoading( options);
{object} options - An object containing an optional message to display during the loading process, a color and backgroundColor of the text message.

ctx.activeObject.hideLoading( );

getMetadataXML()

Return the current metadata XML as a document object.

setMetadataXML( metadataXML )

Sets the the new metadata XML ( only in the preFillForm and onClose method ).

getImage()

Returs a Promise resolved with the current active object image raw data

setFieldValue( data-id, value)

Sets programmatically a value to the field having the data-id provided. Value MUST be in the format expected by DTD.

Use always this method to set programmatically a value to be compatible with bulk mode.

getFieldValue( data-id )

Get the current value from the field having data-id. The returned field value is in the format expected by DTD.

Use always this method to get programmatically a value to be compatible with bulk mode.

refreshMetadata()

Refresh the current Metadata.

This will cause a reload of the objectPanel, and consequently a call to "preFillForm" and "postFillFrom" methods.
refreshPanel()

Refresh the current Object panel.

saveMetadata()

Saves the current Metadata. Before saving, the "preSave" method is called. After saving, the "postSave" method is called. In bulk mode this method saves metadata for all selected objects even if called from a particular activeObject.

notifyMetadataChange()

This method allows to notify that a metadata has changed.