Adding your own JavaScript
Principle
Adding some JavaScript (JS) is useful for a variety of advanced usage. For instance, you can:
hide some UI elements that you don’t want to display by default
add a custom button in the UI
add a popup when the project is opened (to display funders, credits…)
avoid people being able to download elements of the page by right clicking on them, and of course much more.
Prerequisites
This function needs to be activated by the administrator of the Lizmap instance.
The
media
directory. Read how to use Media folder in Lizmap.
Configuring the tool
In your repository (e.g.
/home/data/repo1/myproject.qgs
), you should have these directories:media |-- js |-- myproject |-- default
All the JavaScript code you copy in the
/home/data/rep1/media/js/myproject/
directory will be executed by Lizmap for this specific project only.All the JavaScript code in
default
will be executed for all projects.To allow the execution of JavaScript code, in the Lizmap admin interface, you must add the privilege Allow themes for this repository.
Video tutorial
This video is an quick start how to add a JavaScript to change the default panel in Lizmap.
Library of scripts
You can find some examples in the JavaScript library on GitHub.
Also, in the directory lizmap-web-client/lizmap/install/qgis/media/js/
(or in
GitHub),
you can find examples of suitable JavaScript code.
Remove the extension .example
and copy them to your media/js/default/
folder to activate them.
API documentation
An automated generated documentation of the JavaScript API is available on docs.3liz.org.
Available Javascript events
The Javascript code can use many events fired by Lizmap Web Client. Here is a list of all the events available, with the returned properties.
Event name |
Description |
Returned properties |
---|---|---|
treecreated |
Fired when layer tree has been created in legend panel |
|
mapcreated |
Fired when OpenLayers map has been created |
|
layersadded |
Fired when Openlayers layers have been added |
|
uicreated |
Fired when interface has been created |
|
dockopened |
Fired when a dock is opened (left panel) |
id |
dockclosed |
Fired when a dock is closed (left panel) |
id |
minidockopened |
Fired when a mini-dock ( right container for tools) is opened |
id |
minidockclosed |
Fired when a mini-dock is closed |
id |
bottomdockopened |
Fired when the bottom dock is opened |
id |
bottomdockclosed |
Fired when the bottom dock is closed |
id |
lizmapbaselayerchanged |
Fired when the baselayer has been changed |
layer |
lizmapswitcheritemselected |
Fired when a layer has been highlighted in the layer legend panel |
name | type | selected |
layerstylechanged |
Fired when a layer style has been changed |
featureType |
lizmaplocatefeaturecanceled |
Fired when the user has canceled the locate by layer tool |
featureType |
lizmaplocatefeaturechanged |
Fired when the user has selected an item in the locate by layer tool |
featureType | featureId |
lizmappopupdisplayed |
Fired when the popup content is displayed |
|
lizmappopupallchildrendisplayed |
Fired when the all children popups are displayed |
parentPopupElement | childPopupElements |
lizmappopupdisplayed_inattributetable |
Fired when the popup content is displayed in attribute table (right sub-panel) |
|
lizmapeditionformdisplayed |
Fired when a edition form is displayed |
layerId | featureId | editionConfig |
lizmapeditionfeaturecreated |
Fired when a layer feature has been created with the edition tool |
layerId |
lizmapeditionfeaturemodified |
Fired when a layer feature has been modified with the edition tool |
layerId |
lizmapeditionfeaturedeleted |
Fired when a layer feature has been deleted with the edition tool |
layerId | featureId |
attributeLayersReady |
Fired when all layers to be displayed in the attribute layers tool have been set |
layers |
attributeLayerContentReady |
Fired when a table for a layer has been displayed in the bottom dock |
featureType |
layerfeaturehighlighted |
Fired when a feature has been highlighted in the attribute table ( grey rectangle ). Firing this event manually forces a refresh of child tables if any exist for the layer |
sourceTable | featureType | fid |
layerfeatureselected |
Fire this event to trigger the selection of a feature for a layer, by passing feature id. Once the selection is done, the event layerSelectionChanged is fired in return. |
featureType | fid | updateDrawing |
layerfeaturefilterselected |
Fire this event to trigger the filtering of a layer for the selected features. You must select some features before firing this event. Once the filter is applied, Lizmap fires the event layerFilteredFeaturesChanged in return. |
featureType |
layerFilteredFeaturesChanged |
Fired when a filter has been applied to the map for a layer. This event also trigger the redrawing of the map and the attribute tables content. |
featureType | featureIds | updateDrawing |
layerFilterParamChanged |
Fired when the WMS requests parameters have changed for a layer. For example when a STYLE or a FILTER has been modified for the layer. |
featureType | filter | updateDrawing |
layerfeatureremovefilter |
Fire this event to remove any filter applied to the map. Once done, the event layerFilteredFeaturesChanged is fired back, and the map content and attribute tables content are refreshed. |
featureType |
layerSelectionChanged |
Fired when the selection have been changed for a layer. This also trigger the redrawing of attribute table content and map content |
featureType | featureIds | updateDrawing |
layerfeatureselectsearched |
Fire this event to select all the features corresponding to the displayed lines of the attribute table, which can be visually filterd by the user by entering some characters in the search text input. |
featureType | updateDrawing |
layerfeatureunselectall |
Fire this event to remove all features from selection for a layer. Once done, Lizmap responds with the event layerSelectionChanged |
featureType | updateDrawing |
lizmapexternalsearchitemselected |
Fired when the user has selected an item listed in the results of the header search input |
feature |
actionResultReceived |
Fired when a Lizmap popup action has been performed and the result has been received |
layerId | featureId | action | features |
There are also some variables which are available.
Variable name |
Description |
---|---|
lizUrls.media |
URL to get a media |
lizUrls.params.repository |
Name of the current repository |
lizUrls.params.project |
Name of the current project |
Examples
Legend API
For a given layer buildings
:
var layer = lizMap.mainLizmap.state.rootMapGroup.getMapLayerByName('buildings');
// Name of the current loaded style
layer.wmsSelectedStyleName
// Toggle true or false the layer in the legend
layer.checked = true;
Please have a look to existing online demo, like the Paris by night
Disable right click
Add a file named e.g. disableRightClick.js
with the following code:
lizMap.events.on({
uicreated: function(e) {
$('body').attr('oncontextmenu', 'return false;');
}
});
If you want this code to be executed for all projects of your repository, you have to copy the file in the directory
/home/data/rep1/media/js/default/
rather than in/home/data/rep1/media/js/myproject/
.
Send current login user-ID
An example allowing you to send current login User-ID (and/or other user data) to PostgreSQL table column, using edition tool:
var formPrefix = 'jforms_view_edition';
// Name of the QGIS vector layer fields which must contain the user info
// In the list below, replace the right side by your own fields in Lizmap
var userFields = {
login: 'your_lizmap_user_login_field',
firstname: 'your_lizmap_user_firstname_field',
lastname: 'your_lizmap_user_lastname_field'
};
lizMap.events.on({
'lizmapeditionformdisplayed': function(e){
// If user is logged in
if( $('#info-user-login').length ){
// Loop through the needed fields
for( var f in userFields ){
// If the user has some data for this property
if( $('#info-user-' + f).text() ){
// If the field exists in the form
var fi = $('#' + formPrefix + '_' + userFields[f]);
if( fi.length ){
// Set val from lizmap user data
fi.val( $('#info-user-' + f).text() )
// Set disabled
fi.hide();
}
}
}
}
}
});
URL of a static file
If you want to get the URL of a static file, located in the Media folder:
var media = '/media/image/logo.jpg';
// It can also be a media located in the common media folder such as
// var media = '../media/logo.png';
var url = lizUrls.media + '?repository=' + lizUrls.params.repository + '&project=' + lizUrls.params.project + '&path=' + media;
// console.log(url);
var image = '<img src="' + url + '" title="Logo" style="display:inline;height:80px;margin:20px 10px;" />';
It’s possible to use a function from the OpenLayers library to help building the URL :
var mediaUrl = OpenLayers.Util.urlAppend(
lizUrls.media,
OpenLayers.Util.getParameterString({
"repository": lizUrls.params.repository,
"project": lizUrls.params.project,
"path": "picture.png"
})
);