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.

Lizmap Web Client available events

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.

Lizmap Web Client available variables

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"
     })
);