Book a demo
Developer portal JavaScript Mixin

JavaScript Mixin

Introduction

The main JavaScript file MUST contain the declaration of a variable with the same name as the plugin. If this variable is missing, the system won't be able to load the component correctly. This variable has to be a plain object that may contain anything with some requirements/limitations, which are listed below. Any time the system has to instantiate the plugin, it will make a copy of this object.

  • Mandatory functions have to be implemented. The lack of implementation will result in an error. See the Mandatory functions section for more information.
  • Optional functions are abstract. They don't exist unless you do implement them. See the Optional implementable functions section for more information.
  • Some functions are added directly onto the copy. Hence the name of those functions is restricted, and any member whose name collides will be overwritten, which can lead to unexpected behaviours. See the Accessible functions section for more information.
  • Due to the process, only direct members are copied. From there, the prototype of the original object will be dropped, and no function on it will be accessible by the copy.

Mandatory functions

These functions have to be implemented and be part of the component object.

buildComponent

The buildComponent() method is called any time the component has to be drawn on the layout.

 Syntax 

Example :


buildComponent() {
    // ... implementation goes here...
}

Parameters
None.

Expected return value
The return value can be of three types:

  • An ExtJs(4.3) component (ex. 1)
  • A DOM Element (ex. 2)
  • An HTML string (ex. 3)

 Examples 

Example 1: ExtJs Component


buildComponent() {
    return new Ext.form.TextField({
        value: 'My Plugin'
    });
}
}

Example 2: DOM Element


buildComponent() {
    var input = document.createElement('input');
    input.type = "text";
    input.value = "My Plugin";
    return input;
}
Centring the component
If your component is not correctly centred within its container, use CSS style margin : 'auto'

Example 3: HTML String


buildComponent() {
    return ''
}

update

The update() method is called any time a component's property gets updated.

 Syntax 


update() {
    // ... implementation goes here...
}

Parameters
None.
Expected return value
None.

Optional implementable properties

preloadESTranslation : array of ES translation keys (if known), directly usable without unwanted load traffic
multipleObjectModel : if true getModel() contains an array of "ids". For Component that supports multiple selections.


preloadESTranslation : [ 'ES/WidgetName', 'DDMSUi/Assign' ] ,
multipleObjectModel : true,

Optional implementable functions

These functions are optional and may be implemented at the user's convenience.

serverUpdate

When implemented, the serverUpdate() method is called anytime the server responds from an API or a custom service call.

 Syntax 


serverUpdate(response) {
    // ... implementation goes here...
}

Parameters
response any
The response from the server

Expected return value
None.

getConfigSetup

When implemented, the getConfigSetup() method is called by the system to define settings for the plugin editable in the Job Ticket Layout screen. This configuration (keys and values) is accessible for each plugin component by using this.getConfig().

 Syntax 


getConfigSetup() {
    return {
        'key1': {
            // define settings here.
        },
        'key2': {
            // define settings here.
        },
        // ...
    };
}


getConfigSetup() {
    return {
        customGui: true
        initFunction: function(configValues) {
            // ... implementation goes here...
        },
        okFunction: function() {
            // ... implementation goes here...
        }
    };
}

Parameters
None.
Expected return value
The return value can be of two kinds:

  • A plain object that contains the component settings.
  • An object that describes the configuration panel.

 Description 

Depending on the returned value, the plugin behaves differently.

Using the component settings
If the returned object contains different component settings, each is an object that contains a type property and may have other properties depending on the setting. The system will generate a UI based on the type allowing the user to generate a configuration panel quickly.
The different property values supported by the system are:

  • BooleanState
  • StringState
  • IntegerState
  • EnumerationState
  • MetadataState

See the Examples section for more information on each setting.

Using a custom configuration panel
It is also possible to define a more complex configuration panel. To do this, the returned configuration object must contain:

  • a customGui property set to true to allow the custom interface to be used.
  • a function property initFunction() which returns a DOM Element or an ExtJS component of type Ext.Panel.
  • a function property okFunction() which returns the dictionary of key/values (i.e. a JSON-like object) to save when the window is validated.

initFunction 
The initFunction() will be called whenever the configuration panel has to be displayed.

 Syntax 

Parameters
configValues

Object

A plain object that contains the stored configuration values.

Expected return value
An ExtJs component that will be displayed in a modal window.

okFunction
The okFunction() will be called each time the user clicks on the configuration panel's OK button.


 Syntax 
Parameters
None.
Expected return value
This function must return an object that will be returned by the getConfig() function and stored by the system.

 Examples 

Declaring a boolean setting
This code declares a boolean setting for the plugin. This setting is displayed, in the config screen, as a checkbox. The checkbox is checked when the value is true.


getConfigSetup() {
    return {
        myBoolean: {
            type: 'BooleanState',
            translation: this.getTranslation('myLabel', 'My label'),
            defaultValue: true
        }
    }
}

Declaring a string setting
This code declares a string setting for the plugin. In the config screen, this setting is displayed as a text input containing the configuration value.


getConfigSetup() {
    return {
        myString: {
            type: 'StringState',
            translation: this.getTranslation('myLabel', 'My label'),
            defaultValue: 'My default value'
        }
    }
}

Declaring an integer setting
This code declares an integer setting for the plugin. In the config screen, this setting is displayed as a text input (for integer only) containing the configuration value.


getConfigSetup() {
    return {
        myNumber: {
            type: 'IntegerState',
            translation: this.getTranslation('myLabel', 'My label'),
            defaultValue: 25,
            minValue: 0, // min value allowed (optional).
            maxValue: 100, // max value allowed (optional).
        }
    }
}

Declaring an enumeration setting

This code declares an enumeration setting for the plugin.


getConfigSetup() {
    return {
        myEnum: {
            type: 'EnumerationState',
            translation: this.getTranslation('myLabel', 'My label'),
            values: ['value_1', 'value_2', 'value_3'], // values of the enumeration.
            defaultValue: 'value_1', // default value of the enumeration, must be among the values of the 'values' property.
        }
    }
}

Using a dynamic metadata

This code display two combo-boxes to allow the user to define the property he wants to be used by the plugin.


getConfigSetup() {
    return {
        myMetadata: {
            type: 'MetadataState',
            translation: this.getTranslation('myMetadata', 'My Metadata'),
        }
    }
}

Filtering the list of usable metadata


getConfigSetup() {
    return {
        myMetadata: {
            type: 'MetadataState',
            translation: this.getTranslation('myMetadata', 'My Metadata'),
            metadataType: ['Float', 'AltLang'] // The combo-boxes will only show the metadata listed here.
        },
    };
}

Using a custom configuration panel


getConfigSetup: function() {
    var metadataX = new ES.PluginMetadataConfigComponent({
        fieldLabel: this.getTranslation('x', 'X'),
        metadataType: ['Float', 'AltLang'] //will show only the metadata listed here
    });
    var verticalCmp = new Ext.form.Checkbox({
        fieldLabel: this.getTranslation('vertical', 'Vertical')
    });
    var widthCmp = new Ext.form.NumberField({
        fieldLabel: this.getTranslation('width', 'Width')
    });
    var minvalueCmp = new Ext.form.NumberField({
        fieldLabel: this.getTranslation('minvalue', 'Min value')
    });
    var maxvalueCmp = new Ext.form.NumberField({
        fieldLabel: this.getTranslation('maxvalue', 'Max value')
    });
    var configPanel = new Ext.form.FormPanel({
        items: [metadataTiti, verticalCmp, widthCmp, minvalueCmp, maxvalueCmp]
    });
    var config = {};
    config.customGUI = true;
    config.initFunction = function(configValues) {
        metadataTiti.setValue(configValues.titi);
        verticalCmp.setValue(configValues.vertical);
        widthCmp.setValue(configValues.width);
        minvalueCmp.setValue(configValues.minvalue);
        maxvalueCmp.setValue(configValues.maxvalue);
        return configPanel;
    };
    config.okFunction = function() {
        var configValues = {};
        configValues.titi = metadataTiti.getValue();
        configValues.vertical = verticalCmp.getValue();
        configValues.width = widthCmp.getValue();
        configValues.minvalue = minvalueCmp.getValue();
        configValues.maxvalue = maxvalueCmp.getValue();
        return configValues;
    };
    return config;
}

getLoadModelMessage

The getLoadModelMessage() method is called before an API call to retrieve data from the server. If this function is implemented, it is triggered when the plugin makes an explicit call to the loadModel() method. Once the server answers the API call, the serverUpdate() method treats the response.

 Syntax 


getLoadModelMessage() {
    return {
        // ... API options or custom services parameters
    };
}

Parameters
None.
Expected return value
Parameters for an API call that retrieves data.

 Examples 

Getting a job from API


getLoadModelMessage: function() {
    var id = this.getModelProperty('ID');
    var params = {
        id: 1,
        method: 'job.get',
        params: {
            ID: id
        }
    };
    return params;
}

getStoreModelMessage

The getStoreModelMessage() method is called before an API or a custom service call, to store data onto the server. If this method is implemented, it is triggered when the user clicks on the Save button. Once the server answers the API call, the serverUpdate() method treats the response.

 Syntax 


getStoreModelMessage() {
    return {
        // ... API options or custom services parameters
    };
}

Parameters
None.
Expected return value
Parameters for an API call that retrieves data.

 Examples 

Saving a job with API


getStoreModelMessage: function() {
    var id = this.getModelProperty('ID');
    var params = {
        id: 1,
        method: 'job.edit',
        params: {
            ID: id,
            description: 'New description'
        }
    };
    return params;
}

Accessible functions

The functions below are accessible from any implemented function by the user, and those functions are directly copied onto the mixin object. That's why the name of these functions is RESERVED, and no property on the mixin can share the same name.

getModelProperty

The getModelProperty() method returns the value of a model property.  

 Syntax 


this.getModelProperty(<prop>);

Parameters
prop string
The name of the property you want to have the value.

Expected return value any
The value of the property prop. If no parameter prop is given, the whole data object is returned.

If the plugin implements a custom service, the system expects this function to return parameters for this service. Otherwise, parameters for API calls are expected.

setModelProperty

The setModelProperty() method sets the value of a model property.

 Syntax 


this.setModelProperty(<prop>, <value>);

Parameters
prop string
The name of the property you want to set the value.
value any
The new value to set.
Expected return value
None.

getResourceDir

The getResourceDir() method returns the URL of the current plugin directory.

 Syntax 


this.getResourceDir();

Parameters
None.
Expected return value string
The absolute URL of the current plugin directory.
 Examples 
Loading an image


var htmlImage = '<img src="'+this.getResourceDir()+'/Preview.jpg">';

getTranslation

The getTranslation() method returns a localized string depending on the user language.

 Syntax 


this.getTranslation(<key>, <default>);

Parameters
key string
The translation key in the localized dictionary.
default string
The default value to fall back on if the key is missing.
Expected return value string
Either the translated string if it exists in the dictionary or the default value if it doesn't.
 About the localisation 
For more information about the localisation, check the Localisation of a plugin document.

loadModel

The loadModel() method calls the API or the custom service to retrieve the model. Internally, the call will use the return of getModelMessage() as a parameter and will trigger the serverUpdate() methods once the server has responded.

 Syntax 


this.loadModel();

Parameters
None.
Expected return value
None.

setHasChanged

When the plugin uses its own model (using the API or a custom service), the system's modifications to this model are not managed. Thus, the plugin has to call setHasChanged() explicitly to tell the system that a change happened and make the save operation available.

 Syntax 


this.setHasChanged();

Parameters
None.
Expected return value
None.

 Examples 


update: function() {
    this.setHasChanged();
}
, ,