Configuration of a portal

Layers from external sources

In customer-infra/json/<portal_name>/external, you can add JSON files describing layers from external WMS or WMTS servers. These files must have the following attributes:

  • name
  • resolutions (WMTS only)
  • timeEnabled (WMTS only)
  • timestamps (WMTS only)
  • type
  • wmsUrl (WMS only)
  • matrixSet (WMTS only)

They can have the following optional attributes:

  • label (default: name)
  • attribution (default: empty)
  • attributionUrl (default: empty)
  • hasLegend (default: false)
  • legend (default: empty)
  • format (default: png)
  • opacity (default: 1)
  • queryable (default: false)
  • serverLayerName (default: name)
  • wmsLayers (default: name, WMS only)
  • crossOrigin: (default: null, possible: "undefined" WMS only). If the value is set to "undefined", this will force OpenLayers to discard cross origin information. This can be useful when you import an external WMS layer and encounter cross origin problems.
  • background (default: false)
  • timeBehaviour (default: last, WMTS only)
  • templateUrl (default: null, WMTS only)

Example JSON file for external WMS layer

{
    "name": "UP5",
    "label": "UP5",
    "attribution": "Berne",
    "attributionUrl": "http://www.geoservice.apps.be.ch",
    "background": true,
    "hasLegend": false,
    "legendUrl": "",
    "format": "png",
    "type": "wms",
    "opacity": 0,
    "queryable": false,
    "serverLayerName": "UP5",
    "wmsLayers": "GEODB.UP5_SITU5_MOSAIC",
    "wmsUrl": "//www.geoservice.apps.be.ch/geoservice2/services/a42geo/a42geo_basiswms_d_fk/MapServer/WMSServer?"
}

Example JSON file for external WMTS layer

{
    "name": "ch.swisstopo.swissimage",
    "label": "Orthophotos",
    "attribution": "CNES, Spot Image, swisstopo, NPOC",
    "attributionUrl": "http://www.swisstopo.admin.ch/internet/swisstopo/en/home.html",
    "background": true,
    "hasLegend": false,
    "format": "jpeg",
    "type": "wmts",
    "opacity": 0,
    "queryable": false,
    "timeEnabled": false,
    "serverLayerName": "ch.swisstopo.swissimage",
    "matrixSet": "21781_26",
    "resolutions": [
             4000,
             3750
    ],
    "timestamps": [
             "20151231",
             "20140620"
    ],
    "timeBehaviour": "last"
 }

Translations

Translations for a portal are located in the four files listed below. All these files must have this header: key,fr,de,en,commentaires. The content of the commentaires column will be ignored. You can off course add/remove language columns.

  1. The translation document managed by Swisstopo.
  2. customer-infra/translations/catalog.csv: the content of the catalog, common to all portals. This includes the layer names present in the catalog and the title of the section of the catalog.
  3. customer-infra/translations/<portal-name>.csv: everything else (note: the translation for the topic titles and the topic tooltip – topic_<topic_name>_tooltip – go here).
  4. customer-infra/translations/common.csv (optional): if you find redundancies between the translations for different portals, you can put them in this file. It will be loaded before the file for the portal, which means, you can override a translation from this file in a portal file.

Attention

At least one of the files above must contain a translation line. Otherwise, no layers config will be created. Which means your portal won’t work.

Translation from Swisstopo are overridden by translations in common.csv and translation from both Swisstopo and common.csv are overridden by translations from <portal>.csv. To ignore a translation from Swisstopo, put its id in the customer-infra/translations/ignore.csv file. This file must just contain the translation ids (one per line). You can view an example here.

Attention

ids present in ignore.csv will never get into a translation file.

Topics

Topics are defined in JSON files located in customer-infra/json/<portal>/topics/<topic_name>.json. They must contains the keys below:

  • backgroundLayers: the list of background layer ids for this topic in the order they will appear in the background selector. For instance:

    "backgroundLayers": ["voidLayer", "landuse"]
    
  • langs: the list of languages for which this topic is available. For instance:

    "langs": ["en", "fr"]
    
  • name: the name of the topic. For instance:

    "name": "Topic 1"
    

    This is what must be used in translation files to translate the topic name.

  • catalog: defines the layers available for this topic and how they will be displayed. You can simply use a list of layer ids to have a catalog without depth. For instance:

    "catalog": [
        "places",
        "buildings"
    ]
    

    But you can also use a list of objects to group layers into categories. These objects must have the following keys:

    • category (string): can be anything but root and layer.
    • selectedOpen (boolean): if it is true, then the group will be opened by default when the user expands the catalog for this topic.
    • children: it can be either:
      • a list of layer ids. In this case, the layers will be presented to the user at this level.
      • a list of objects with the same properties as the ones in the catalog. This allows you to create subcategories.

    For instance:

    "catalog": [
        {
            "category": "land",
            "selectedOpen": false,
            "children": [
                "transport_osm_roads",
                "transport_osm_railways"
            ]
        },
        {
            "category": "air",
            "selectedOpen": false,
            "children": [
                "transport_osm_aeroways"
            ]
        }
    ]
    

You can also use the optional keys below:

  • activatedLayers (default: empty list): the layers whose id is listed here will be in the Map Displayed selector by won’t be selected. This allows you to put layers in the selector while hiding them by default. For instance:

    "activatedLayers": ["waterareas"]
    
  • selectedLayers (default: empty list): the layers whose id is listed here will be in the Map Displayed selector and will be selected. This allows you to preselect some layers for a topic. For instance:

    "selectedLayers": ["places", "buildings"]
    

Identify features

In order to enable a feature view, for a portal, you need to enable it in the features.map_layers_features table. To do this, add or update a row like this:

  • In the column feature put the name of the feature view.
  • In the column portal_names put the table of portals for which the feature view must be available. For instance: {demo}.
  • In the column layer_names put the name of the layers for which the feature view must be requested. For instance: {roads}.

Referer to the feature section of the database page to learn more how this works in the database and how to create feature views.

Special columns for features

To be able to render feature columns with another representation than the “raw” content coming from the database, it is possible to create custom templates for columns verifying a special pattern. A number of special cases are handled automatically by default:

  • hidden: if a column name ends with _hidden it will not be displayed by default. The user can choose to see it if necessary.
  • url: if a column name ends with _url it will be rendered as an url (useful if the content has to be a valid clickable url). _url can be combined with _hidden to hide a URL type column by default like that _url_hidden.
  • pdf: if a column name ends with _pdf, the content will be rendered as a link with a acrobat pdf icon as content. The link generally points to /files/FILE.pdf.

To use these templates, name your columns like this: name<pattern>, eg website_url or boring_hidden.

To add a new pattern, the code of the frontend needs to be updated. Ask a developer to do this. You can point to the relevant section of the documentation.

Help

This section explains how the help website and the help available from geo-front3 is generated.

The help website is a small static website written using AngularJS. It is design to show help to the user of a portal and can be accessed for each one on by appending /help to the address of a portal. For instance for https://map.geoportal.xyz, https://map.geoportal.xyz/help.

Update the help (images and texts) from Swisstopo

This rely on the scripts/generate_help.py python script (not usable directly). This will download the texts for each language supported by Swisstopo from google fusion table in the JSON format. The script will then convert this JSON file to a csv file and save the result in in/help/swisstopo/texts.

While fetching the texts, the content is scanned by beautiful soup in order to find all images (these images are used with the a tag with a href attribute like (?:https?:)?//help.geo.admin.ch/([^ ])). The links are corrected in order to use images from /help/img/. These images are converted to PNG and saved in in/help/swisstopo/img.

To do this, use in geo-infra:

manuel help-update

Note

There is no particular way to know if the help was updated by Swisstopo. Launch the update task and git will tell you if anything changed.

Generate the help for a portal

The script will output the help in two formats:

  • One for the help website. The files used are in <type>/<portal>/help/texts/<lang>.json.
  • One for the use within geo-front3 in <type>/<portal>/help/texts/<id>-<lang>.json

All the images are saved in <type>/<portal>/help/img.

In order to generate the texts, the script will:

  1. Parse the texts from geo-infra/help/texts/<lang>.csv.
  2. Parse the texts from customer-infra/help/<portal>/texts/<lang>.csv. So in order to change a text from Swisstopo, you simply must add a row with the same id in the corresponding language specific file. For instance, in order to change the home page for French for geoportalxyz, you must edit ioda-infra/help/geportalxyz/texts/fr.csv. You must then add a line with the id 1. The number from the sort column (second column) must correspond to the one used by Swisstopo. For instance:
1,1,PAGE D'ACCUEIL,"<b>AIDE CARTE: FONCTIONS ET APPLICATIONS PRATIQUES</b>"

You can ignore a page by putting its id in in/help/<portal_name>/ignore.csv.

For instance:

id
42

To create a new language file for a portal, create a <lang>.csv file in customer-infra/help/<portal>/texts and put the following header:

id,sort,title,content,legend,image

In order to generate the images, the script will:

  1. Copy the images from geo-infra/help/img.
  2. Copy the images from customer-infra/help/<portal>/img. So to replace an image from Swisstopo, you must add an image with the same name (this include the extension) in customer-infra/help/<portal>/img.

To build the help website (static site and files needed for the help within geo-front3), use in geo-infra:

manuel help-site [TYPE] PORTAL

Help generation in short

The content of the site is generated as follows:

  1. The images from Swisstopo are copied in the destination directory.
  2. The images for the current portal are copied in the destination directory. This means that if an image has the same name as an image from Swisstopo, it will replace it.
  3. The texts from Swisstopo are parsed from their respective csv files.
  4. The texts for a current portal are parsed from its csv files. If a text has the same id as a text from Swisstopo it will replace it. This means that you only have to put the line you want to change into the portal CSV.

Writing help texts

We advise you to use LibreOffice or equivalent to edit the CSV files. This way you can be sure that the CSV file you save is valid. It will also make editing of big texts easier.

Plugins

For features may be available through plugins. To enable a plugin on a portal, add it to the plugins list of the front.default_values section. For instance, to enable the plugin named test, your portal config file should contain:

[front.default_values]
plugins = ['test']

Print

Printing a map relies on MapFish Print a Java servlet developed by Camptocamp SA.

You can either build it from scratch from the source or use our last build.

You can view examples of print templates here. You can create your print templates with Jasper Studio or directly by editing the jrxml files with a text editor.

To learn more about the available options, see the proper page of the documentation.