Méthode Swing uploader can be extended with custom behaviour.

Location of the Uploader extensions

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.

Image data extractor

When uploading files to Swing it’s possible to define a image data extractor function which will be called before the load the default metadata from server.

Registration

Image data extractor implementation with eidosmedia.webclient.extensions.objectpanel.addImageDataExtractor method is not supported anymore.

Image data extractor extension was moved to object panel customizations.

Please refer to the onImageProcessing method on Object Panel documentation for further information.

Filename Validation

When uploading files to Swing it’s possible to define a filename validation function which will be called before the actual files are transfered to the server. To add a filename validator, it is necessary to register it inside Swing by calling the following Javascript function, inside your Javascript file:

eidosmedia.webclient.extensions.uploader.validateFilename = function( filename ){}

Parameters

  • "filename": The filename to validate.

The function must the return the new filename.

Implementation Example

eidosmedia.webclient.extensions.uploader.validateFilename = function( filename ) {
    return "VALIDATED_" + filename;
};

Metadata Validation

When uploading files to Swing it’s possible to define a validation function which will be called before the actual files are transfered to the server. To activate this function it’s important to first define the correct validation namespace.

Namespace

Create a javascript file inside the plugin folder defining extending the objectpanel object with a new function called validateMetadata:

eidosmedia.webclient.extensions.objectpanel.validateMetadata = function( ctx, items, callbacks ){}

Parameters

  • "ctx": The ctx is a JSON object which represents the object’s context. Available only in init method. See Context Object (ctx parameter) for further details.

  • "items": An array with the objects to be uploaded.

  • "callbacks": An object with success and error functions.

Validate data

Once the validateMetadata function is called it’s possible to cycle through the array of items and for each item work with its XML metadata document.

If all the checks on the XML documents are valid, call the callbacks.success function to proceed with the upload process; otherwise call the callbacks.error.

Callbacks and parameters

When calling the callbacks.error function it’s mandatory to pass two arguments.

callbacks.error(
    { msgError: 'General Error Message'},
    [{id: 'picId', msgError:'Specific Error Message'}]
 );

The first parameter is an object with the general error message to display after the validation. The second is the items array we received as input in the validateMetadata function but modified with a msgError property for those items (and only for those items) which failed validation.

Final Implementation Example

eidosmedia.webclient.extensions.objectpanel.validateMetadata = function(ctx, items, callbacks){

    var generalValidationOK = true;
    var itemsWithError = [];

    $(items).each(function(i, el){

        var xmlMetadataDoc = el.data.metadata;
        // call external validation method
        var validationOK = _callMyValidationMethod(xmlMetadataDoc);

        if ( !validationOK ){
            generalValidationOK = false;
            el.msgError = 'This item metadata is not valid!'
            itemsWithError.push( el );
        }
    });

    if ( generalValidationOK ){
        callbacks.success();

    } else {

        callbacks.error(
                {msgError: 'Error Message'},
                itemsWithError
        );
        generalValidationOK = true;
    }
};

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

Import URL: preview and import information.

With Swing it is possible to drag external URLd. Since there can’t be any control on the content of the URL, Swing tries to propose a generic preview, consisting in an iframe pointing to the specific URL.

Then, when trying to import the content, three standard cases may apply:

  • the content is recognized as an image. This will be imported as an image into the EOMDB.

  • the content is recognized as an HTML file. This will be imported as a URL into the EOMDB.

  • the content is not recognized as one of the above. This will be imported but its well-functioning is not guaranteed.

So, Swing allows to specify custom information to provide a more precise response according to the URL passed. It is possible to provide the preview information and the import information. A common use for this possibility is to perform regular expressions and provide additional information according to the url.

Specify preview information

Following the same guidelines of the other extensions, it is possible to specify a custom getPreviewInfoURL behaviour, registering a new uploader extension.

eidosmedia.webclient.extensions.uploader.add('getPreviewInfoURL', function( url, token, getConnectionURL ) { /* ... */ }

The parameters passed are:

  • the url.

  • the Swing application token.

  • the checkConnectionURL, an URL to be called to verify whether the token is valid.

The function must return a oEmbed-like json response, as the following example:

{
    //"version": "1.0",
    "type": "video",
    "importType": "video",
    //"provider_name": "YouTube",
    //"provider_url": "http://youtube.com/",
    //"width": 425,
    //"height": 344,
    //"title": "Amazing Nintendo Facts",
    //"author_name": "ZackScott",
    //"author_url": "http://www.youtube.com/user/ZackScott",
    "html":
        "<object width=\"425\" height=\"344\">
            <param name=\"movie\" value=\"http://www.youtube.com/v/M3r2XDceM6A&fs=1\"></param>
            <param name=\"allowFullScreen\" value=\"true\"></param>
            <param name=\"allowscriptaccess\" value=\"always\"></param>
            <embed src=\"http://www.youtube.com/v/M3r2XDceM6A&fs=1\"
                type=\"application/x-shockwave-flash\" width=\"425\" height=\"344\"
                allowscriptaccess=\"always\" allowfullscreen=\"true\"></embed>
        </object>"
}

What really matters here is the html attribute. This will be used by the Swing preview to show the content of the imported URL. Other parameters are, at the moment, ignored.

Another important attribute is the importType. It can specified either here or in the getImportInfoURL method. Please check the method in the following paragraph.

Specify import information

Following the same guidelines of the other extensions, it is possible to specify a custom getImportInfoURL behaviour, registering a new uploader extension.

eidosmedia.webclient.extensions.uploader.add('getImportInfoURL', function( url, token, getConnectionURL ) { /* ... */ }

The parameters passed are:

  • the url.

  • the Swing application token.

  • the checkConnectionURL, an URL to be called to verify whether the token is valid.

The function must return a Javascript, as the following example

{
    "importType": "picture",
    "filename": "someSpecificFilename"
}

If importType is specified, Swing will know better how to save the content. Otherwise, it will try to check the type attribute and, if no information is provided, the contentType of the url.

It is also possible to "force" a filename. This is especially useful in case of url without extension (e.g. services that return images). In that case, it would be better to specify a valid filename.

If the type is valued as text/html ( the basic contentType of an HTML page ), the content will be imported as URL. Available importTypes are: picture,story,gallery,dwp,dwc,video,audio. This will determine the corresponding workfolder in which the content will be saved.

getPreviewInfoURL and getImportInfoURL methods are optional. If not available, Swing will try to use the oEmbed protocol if available, and an internal preview system if the oEmbed protocol is missing. In that case, the importType will be guessed by the contentType of the URL response, and the preview will likely be an iframe pointing to the URL.

Final Implementation Example

eidosmedia.webclient.extensions.uploader.add('getPreviewInfoURL', function( url, token, checkConnectionURL ) {
    if ( url.match(/mycustomdamextension/ ) {
        return {
            "type": "image",
            "importType": "picture",
            "html":
            "<object width=\"425\" height=\"344\">
                <param name=\"movie\" value=\"http://www.youtube.com/v/M3r2XDceM6A&fs=1\"></param>
                <param name=\"allowFullScreen\" value=\"true\"></param>
                <param name=\"allowscriptaccess\" value=\"always\"></param>
                <embed src=\"http://www.youtube.com/v/M3r2XDceM6A&fs=1\"
                    type=\"application/x-shockwave-flash\" width=\"425\" height=\"344\"
                    allowscriptaccess=\"always\" allowfullscreen=\"true\"></embed>
            </object>"
        }
    } else {
        /* RETURNING NULL OR A FALSY VALUE OR AN OBJECT WITHOUT THE 'HTML' PROPERTY
           WILL RESULT IN SWING USING ITS STANDARD PREVIEW MECHANISM */
        return null;
    }
});

/* Please notice that, having specified the importType inside the
   getPreviewInfoURL method, the following method implementation is redundant */
eidosmedia.webclient.extensions.uploader.add('getImportInfoURL', function( url, token, checkConnectionURL ) {
    if ( url.match(/mycustomdamextension/ ) {
        return {
            "importType": "picture"
        }
    } else {
        /* RETURNING NULL OR A FALSY VALUE OR AN OBJECT WITHOUT THE 'HTML' PROPERTY
           WILL RESULT IN SWING USING ITS STANDARD MECHANISM */
        return null;
    }
});