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;
}
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.
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();
}