Swing Live Editor extensions

Custom Swing Live Editor area

It is possible to add a custom area on top of the liveblog editor timelime. The behaviour and the registration is similar to Object Panel and custom lateral panels extension.

Registration of custom area

To register the liveblog custom area, use the following namespace

eidosmedia.webclient.extensions.liveblog

and its function

registerCustomArea(customArea)

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

The following is a very simple example of a working custom area.

eidosmedia.webclient.extensions.liveblog.registerCustomArea({
    template: 'custom-area.html',
	init: function(ctx, $container) {
		console.log('Initializing Liveblog CustomArea', ctx, $container);

		$container
			.text(`Liveblog Custom Area for ${ctx.activeObject.getInfo().name}`);
	},
	isActive: function(ctx) {
		return ctx.activeObject.getInfo().name === 'LiveNews.emlive';
	},
	onClose: function(ctx, $container) {
		console.log('Closing Liveblog CustomArea', ctx, $container);
	}
});

Properties and methods of the custom area

The following paragraphs describe the available properties or methods for the custom area.

template

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

{SWING-APP}/config/templates/liveblog/customarea/

Swing supports Tomcat 9.x, so custom panels can be configured outside {SWING-APP}. See the paragraph How to configure custom extension 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 /customarea/ folder.

Example

{
    // ...
    template: 'custom-area.html',
    // ...
}

isActive( ctx )

[Optional] {Function} isActive determines whether the custom area is visible or not. If not specified, the area 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.getInfo().name === 'LiveNews.emlive';
    },
    // ...
}

init( ctx, $container )

[Optional] {Function} init is called after the area template has been loaded. It has the following parameters:

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

Example

{
    // ...
    init: function( ctx, $container ) {
        console.log('Initializing Liveblog CustomArea', ctx, $container);

        $container
            .text(`Liveblog Custom Area for ${ctx.activeObject.getInfo().name}`);
    },
    // ...
}

onClose

[Optional] Method called when the custom area is removed from the page. This happens when a document is closed or main content tab is opened.

The syntax is the following:

onClose( ctx, $container );

Table 3. Method information
Method	`onClose`
Parameter	`{object} ctx` - The context object. See Context Object (ctx parameter) for further information.
`$container`	The jQuery reference to the area container node with the loaded template.
Returns	`undefined`.

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

Custom Live Blog Post templates

It is possible to configure custom templates to be used when rendering live blog posts in the timeline view.

Editor configuration

In Swing Live editor configuration (see Swing Live editor specific configuration) can be specified which HTML template should be used to render live blog posts.

<WebClientConfiguration>
    ...
    <editor>
        ...
        <liveblog>
            ...
            <liveBlogPostTemplate>
                <template>liveblogpost.html</template>
                <readMetadata>true</readMetadata>
            </liveBlogPostTemplate>
        </liveblog>
    </editor>
<WebClientConfiguration>

Configuration tag template specifies the template filename to use to every live blog post in the timeline.

Configured template files will be retrieved from

{SWING-APP}/config/templates/liveblog/templates/{TEMPLATE-NAME}

and can be configured outside {SWING-APP}, see the paragraph How to configure custom extension in external folder.

Setting readMetadata to true will enable the template to receive live blog post metadata, otherwise they would not be available.

Templating system

Underscore.JS templating system is used to define templates.

The template is rendered with a main object item, which contains all the information about the item.

// item
{
    "id": "ce75a8f8-ef4e-11e9-9afc-4cf1959a10d6",
    // system informations
    "sys": {
        "kind": "content",
        "baseType": "liveblogpost",
        "type": "text",
        "creationTime": "2019-10-15T13:22:16.000Z",
        "createdBy": {
          "userName": "john.doe"
        },
        "updateTime": "2019-10-21T12:52:11.000Z",
        "updatedBy": {
            "userName": "john.doe"
        }
    },
    "fileName": "20191018131100720.emlivepost",
    "content": "<article><h1>Title</h1><p>Main content</p></article>",
    "type": "text",
    "timestamp": 1571404260720,
    // Live Blog Post status ("APPROVED", "PENDING", "DELETED", "REJECTED")
    "status": "PENDING",
    // attributes and attributes_json data will be available only if
    // readMetadata setting is "true"
    attributes: 'metadata XML string',
    attributes_json: {
        // metadata as json object
    },

}

Following, a very simple example of a custom template:

<h2>Custom template</h2>
<h3><%=item.fileName%></h3>
<div><%=item.content%></div>

How to configure custom extension 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 area 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/liveblog/customarea" readOnly="true"
            webAppMount="/config/templates/liveblog/customarea" />
    </Resources>
</Context>