Creating New Controls

The XVM has been designed in order to load Controls with a modular approach, making changing the controls we want to load very easy and without the need of modifying any JavaScript code.

General Structure

Each XVM Control is stored inside the CONTROLSFOLDER folder (the one configured in XVM, check Customization for more info on this) in an independent folder with the name of the control specified in the controls yaml file (check Customization for more info on this), which should contain at least three files with the same base name as the folder:

• <control_name>.js: contains the code with the functionality of the control itself.
• <control_name>.css: contains the HTML style of all the control related GUI components.
• <control_name>.yaml: contains the configuration parameters and the internationalization strings of the control.

JavaScript File

This file contains the code that implements the control. XVM controls are thought as a wrapper onto an Open Layers Control, providing a facade that simplifies their management. Controls must extend the XVM.Control class, which provides the skeleton for their methods. Though we can overwrite the whole class if we want a very special control, the attributes and functions we usually have to change or access are:

• addToPanel: determines whether our control must be placed into a panel (usually for buttons) instead of directly into the map (e. g., a scale line). By default it's false.
• OLMap: the attribute where the Open Layers Map where we want to add this control is stored for additional references.
• OLControl: the attribute where we store the Open Layers Control for adding it to the map or panel afterwards.
• createControl: function intended for creating an Open Layers Control ans assigning it to the attribute OLControl.
• beforeAddingControl: by overwriting this method we can perform additional actions before adding a control to the map or panel.
• afterAddingControl: by overwriting this method we can perform additional actions after adding a control to the map or panel.

For a very simple example of all this, you can check the ZoomIn control, and on the other side the DrawFeature control shows a more complete one.

Custom Open Layers controls

There is also support for loading custom Open Layers controls. In this case we must configure an additional parameter:

• customOLControlFile: this parameter contains the path to the custom Open Layers control JavaScript file from the control folder.

You can check the FeatureInfoGeoJson control as a working example.

Css File

This is an optional css file that simply contains styles for the control GUI components. You may have a look at the ZoomIn css file for an example.

Yaml File

This yaml file includes the customizable options of the control. It has three main top attributes:

• init: should contain all the parameters needed by our XVM Control or by the Open Layers Control. its content is passed to our XVM Control, so we can construct and handle it as we see fit. If we need internationalized strings or code references, we can wrap our attribute value with eval in order to make it evaluate in execution time (e.g. eval($.i18n("measured_area"))). It's worth pointing out that despite Open Layers doesn't accept autoActivate for panel controls, our wrapper does, manually activating the control. In case multiple controls are set to auto-activate, only the last one inserted will remain so.
• position: we can specify a position for our control in the panel. A higher value means a bigger position (bottom) in the vertical panel. In case of position conflict, results may vary.
• properties: for storing all the internationalization strings. First sub-level for the language (e.g. 'es') and then the translation for each string (e.g. 'measured_area': 'Medir área').

The MeasureArea yaml file and ZoomIn yaml file are good examples of all this.