Custom editor panels

With Méthode Swing it’s possible to add custom lateral panels to the Editor. The behaviour and the registration is similar to the Object Panel extension, and allows the user to interact with the Editor and the opened document through the use of the Editor Apis.

Registration of a custom panel

To register a new custom panel, use the following namespace

eidosmedia.webclient.extensions.binder

and its function

add( name, options )

Table 1. Method information
Method	`add`
Parameter	Required `{String} name` - The name of the custom panel Required `{object} options` - An object containing the options and the behaviour of the panel. See Properties and methods of the custom panel for details.
Returns	`{undefined}` undefined

The following is a very simple of a working custom panel.

eidosmedia.webclient.extensions.binder.add( "city-panel", {
    label: "City info",
    icon: 'fa fa-building-o',
    template: 'city-panel.html',
    isActive: function(ctx) {
        return true;
    },
    headerButtons: [{ name: 'refresh', icon: 'icon-refresh', title: 'toolbar.refresh' }],
    init: function(ctx, $container, panelMethods) {
        // Load external sources...
    },
    ready: function(ctx, $container, panelMethods) {
        alert("No man is an island, / Entire of itself. / Each is a piece of the continent, / A part of the main. ... / For whom the bell tolls, / It tolls for thee.");
    },
    closeOnHide: true,
    refreshOnShow: true,
    callReadyOnChangeItem: false,
    /**
     * Method called whenever the user clicks on the refresh button.
     */
    onRefresh: function(ctx, $container, panelMethods) {
        console.error('Clicked on refresh');
    },
    onClose: function(ctx, $container, panelMethods) {
        alert("Don't leave me, please!");
    },
    /**
     * Method called whenever the user changes selection. Available only inside
     * the story editor.
     */
    onChangedPath : function(ctx, $container, panelMethods, pathInfo) {
        console.log(pathInfo);
    }
});

Properties and methods of the custom panel

The following paragraphs describe each of the available properties or methods for the custom panel.

label

[Mandatory] {String} label defines the label visible on the top of the panel when it is selected.

Example

{
    // ...
    label: "For whom the bell tolls",
    // ...
}

icon

[Optional] {String} icon defines the icon of the custom panels. All the most recent Font Awesome icons are available.

Example

{
    // ...
    icon: "fa fa-bell",
    // ...
}

template

[Mandatory] {String} template defines the path of the custom panel HTML template. The templates must be put under the following folder:

{SWING-APP}/config/templates/panels/

Swing supports Tomcat 9.x, so custom panels can be configured outside {SWING-APP}. See the paragraph How to configure custom panels in external folder for some tips in how to take advantage of this configuration option.

the path specified in the template option is relative to the /panels/ folder.

Example

{
    // ...
    template: 'bell.html',
    // ...
}

offlineAvailable

[Optional] {Boolean} offlineAvailable determines whether the custom panel is visible or not when the application is offline.

Example

{
    // ...
    offlineAvailable: true,
    // ...
}

localStoryAvailable

[Optional] {Boolean} localStoryAvailable determines whether the custom panel is visible or not when editing a local story.

Example

{
    // ...
    localStoryAvailable: true,
    // ...
}

isActive( ctx )

[Optional] {Function} isActive determines whether the custom panel is visible or not. If not specified, the panel is always visible. This function must return a valid Boolean value to be used. The isActive method has the usual ctx parameter available.

Example

{
    // ...
    isActive: function( ctx ) {
        return ctx.activeObject.getType() === 'EOM::Story';
    },
    // ...
}

init( ctx, $container )

[Optional] {Function} init is called as soon as the panel is initialized, after the isActive method has passed. It has the following parameters:

Table 2. Method parameters
Name	Description
`ctx`	The usual Context Object
`$container`	The jQuery reference to the container node.

The init method is called before the template has been loaded, so the $container content is actually empty. Do not use it to add event listeners to DOM objects.

Example

{
    // ...
    init: function( ctx, $container ) {
        // For example, load external sources...
    },
    // ...
}

ready( ctx, $container )

[Optional] {Function} ready is called after the panel has been initialized and the template loaded. It has the following parameters:

Table 3. Method parameters
Name	Description
`ctx`	The usual Context Object
`$container`	The jQuery reference to the container node.
`panelMethods`	A small set of common methods to be used inside the panel. The only available method is setMessage( message, icon, element ).

This is the best place to add event listeners to DOM object and to actually implement the whole panel’s logic.

Example

{
    // ...
    ready: function( ctx, $container, panelMethods ) {
        var _ctx = ctx; // Remember to save the instance, otherwise inside the event it will not work
        $container.off('click', '.my-save-button').on('click', '.my-save-button', function() {
            _ctx.activeDocument.saveDocument();
        });
    },
    // ...
}

refreshOnShow

[Optional] If set to true, the custom panel will refresh ( and call all the subsequent methods, e.g. ready (not _init) ), any time the custom panel tab is selected by the user ( except for the first time ).

closeOnHide

[Optional] If set to true, the onClose method, if available, will be called any time the custom tab loses focus ( another tab is opened ).

callReadyOnChangeItem

[Optional] If set to true, the custom panel will call the ready method, any time the item selection changes.

onClose

[Optional] Method called when the custom panel is closed. This happens when a document is closed, when a different element is selected, or when the custom tab is hidden ( in case of closeOnHide set to true).

The syntax is the following:

onClose( ctx );

Table 4. Method information
Method	`onClose`
Parameter	`{object} ctx` - The context object. See Context Object (ctx parameter) for further information.
Returns	`undefined`.

onApplicationStatusChange

[Optional] Method called when the application status change from online to offline or vice versa (triggered only when using the offline functionality).

The syntax is the following:

onApplicationStatusChange(ctx, $container, panelMethods, status);

Table 5. Method information
Method	`onApplicationStatusChange`
Parameter	`{object} ctx` - The context object. See Context Object (ctx parameter) for further information.
`$container`	The jQuery reference to the container node.
`panelMethods`	A small set of common methods to be used inside the panel. The only available method is setMessage( message, icon, element ).
Parameter	`{object} status` - The application status. The status object is structured as below: applicationOnline: true if the application is in online mode, false otherwise. isOnline: true if the application reaches the server and the application is in online mode, false otherwise. offlineServer: enabled : true if the offline server is available, enabled: false otherwise. serverReachable: true if the server is reachable, false otherwise.
Returns	`undefined`.

Example

// options object...
{
    onApplicationStatusChange: function( ctx, $container, panelMethods, status ) {
       // For example, we can check the application status
       if (status.isOnline) {
        ....
       }
    }
}

onMessage

[Optional] Method called when the application status change from online to offline or vice versa (triggered only when using the offline functionality).

The syntax is the following:

onMessage(ctx, $container, panelMethods, key, message);

Table 6. Method information
Method	`onMessage`
Parameter	`{object} ctx` - The context object. See Context Object (ctx parameter) for further information.
`$container`	The jQuery reference to the container node.
`panelMethods`	A small set of common methods to be used inside the panel. The only available method is setMessage( message, icon, element ).
`key`	A string that represents the event notification form the editor instance. For example it can be refreshcurrentitem, when changing between one channel copy and another .
Parameter	`{object} message` - Contains additional info depending on the key value, in general contains the info about the current document.
Returns	`undefined`.

Example

// options object...
{
    onMessage(ctx, $container, panelMethods, key, message) {
        if ('key' === 'refreshcurrentitem') {
            console.log('message contains all the information about the current editing story');
        }
    }
}

Context Object (ctx parameter)

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

How to configure custom panels in external folder

Additional objects may be made available to Swing application by defining one or more nested components in Swing web context in server.xml. (for further details on Tomcat 9.x Resources configuration, please refer to Resources configuration).

This is an example of the external custom panels configuration.

<Context docBase="com.eidosmedia.webclient.web-app"
    path="/swing" reloadable="false">
    <Resources
        className="org.apache.catalina.webresources.StandardRoot">
        <PreResources
            className="org.apache.catalina.webresources.DirResourceSet"
            base="/methode/meth01/extension/custompanels" readOnly="true"
            webAppMount="/config/templates/panels" />
    </Resources>
</Context>