ngeo

Organization

Simple and advanced modes

The HTML and the JS of an interface are in the files: geoportal/<package>_geoportal/static-ngeo/js/apps/<interface>.html.ejs and geoportal/<package>_geoportal/static-ngeo/js/apps/Controller<interface>.js where <interface> is the interface name.

In all application modes (simple and full):

The style sheet file is geoportal/<package>_geoportal/static/css/<interface>.css.

The header file is geoportal/<package>_geoportal/static/header.html.

The images used from the admin interface should be placed in the folder geoportal/<package>_geoportal/static/images/.

Advanced mode only

The style sheet vars file is geoportal/<package>_geoportal/static-ngeo/js/apps/sass/vars_<interface>.scss.

The style sheet file is geoportal/<package>_geoportal/static-ngeo/js/apps/sass/<interface>.scss.

The images used by the application code should be placed in the folder geoportal/<package>_geoportal/static-ngeo/images/.

HTML file

Note

This is not possible in the simple application mode

In this file, you can add some blocks like

<gmf-auth-panel slot="tool-panel-auth"></gmf-auth-panel>

to include a web-component in a specific slot (one UI part of the app).

You can find the available component in the ngeo documentation.

The controller (js file) is commonly named mainCtrl. So you can use a value from the controller by doing the following (here, the controller is the DesktopController):

<html lang="{{desktopCtrl.lang}}" ng-app="mydemo" ng-controller="DesktopController as mainCtrl">
  <head>
  ...
  </head>
  <body>
  ...
  <gmf-mycomponent
    slot="map"
    gmf-mycomponent-variableproperty="mainCtrl.open"
    gmf-component-staticproperty="::mainCtrl.map">
  <gmf-component>
  ...
  </body>
</html>

Controller (js file)

Note

This is not possible in the simple application mode

In the controller you have some lines like:

import gmf<Component>Module from 'gmf/<component>/module';

This is needed to include the javascript of the used component.

You can add your own imports.

Most of the component configuration and the map configuration is in the interfaces_config section of the vars file. See the section below.

Dynamic.json view

To configure the ngeo constants with dynamic or configurable values, you can use the dynamic view.

This view is configurable in the vars files in the section interfaces_config. The sub section is the interface name, and after that we have:

  • redirect_interface: Interface to be redirected to if an unexpected device type is used (mobile/desktop).

  • do_redirect: Directly do the redirect.

  • extends: Interface for which the constants, dynamic_constants, static and routes shall be extended. These values will be updated with the interface configuration (but can not be removed via interface configuration).

  • constants: Directly define a constant in the vars file.

  • dynamic_constants: Define a constant from a dynamic values.

  • static, the key is the constant name:
    • name: The path of the resource whose URL we want to have e.g.

      /etc/geomapfish/static/contextualdata.html.

    • append: A text we want to append.

  • routes, the key is the constant name:

    • name: Name of the route whose URL we want to have.

    • kw: Keyword arguments to supply for dynamic path elements in the route definition.

    • elements: Additional positional path segments to append to the URL after it is generated.

    • params: Query string parameters to append to the URL (available parameters of our services: Webservices documentation).

    • dynamic_params: Query string parameters from dynamic values to append to the URL.

    For more information regarding the elements and kw properties see the Pyramid Request.route_url documentation.

  • lang_urls_suffix suffix used in l10n URL, see: Multi organization.

The dynamic values names are:

  • interface: The interface name given in the parameters of the dynamic view.

  • cache_version: The version of the cache.

  • two_factor: Two factor authentication status from vars.authentication.two_factor.

  • lang_urls: The language URL for AngularJS dynamic locale.

  • i18next_configuration: The i18next configuration from vars.i18next.backend with dynamically calculated loadPath,

  • fulltextsearch_groups: The search groups from the layer_name of the Full-Text Search table.

Ngeo configuration options

Configuration

The full configuration

Properties:

Ngeo API configuration options

APIConfig

Properties:

  • backgroundLayer (string, optional)

  • extent (number[], optional)

  • localeUrl (string, optional)

  • projection (string, optional)

  • projections ({string: Projection}, optional)

  • queryableLayers (string[], optional)

  • resolutions (number[], optional)

  • searchUrl (string, optional)

  • themesUrl (string, optional)

Ngeo internal object configuration options

Define additional types used in the config

FeatureCollection

See FeatureCollection.

ol.Feature

See ol.Feature.

ol.geom.Geometry

See ol.geom.Geometry.

ol.control.Control

See ol.control.Control.

ol.interaction.interaction

See ol.interaction.interaction.

Bloodhound.BloodhoundOptions

See Bloodhound Usage.

Twitter.Typeahead.Dataset

See Typeahead Dataset.

ZExtractorFunction

RegExp

See RegExp.

lineCap

See lineCap.

lineJoin

See lineJoin.

ol.control.ZoomOptions

See ol.control.ZoomOptions.

ol.interaction.DefaultsOptions

See ol.interaction.DefaultsOptions.

i18next.InitOptions

See i18next.InitOptions.

Ngeo internal object configuration options

Circle

Properties:

  • displacement (number[], optional)

  • fill (Fill, optional)

  • radius (number)

  • stroke (Stroke, optional)

ExternalOGCServer

The definition of an external OGC server

Properties:

  • name (string)

  • type (string)

  • url (string)

Fill

Properties:

  • color (number[] | string, optional)

GridMergeTabs

Configuration option for {@link import(‘gmf/query/gridComponent’).GmfQueryGridComponent} to merge grid tabs. E.g. ‘two_wheels_park’: [‘velo_park’, ‘moto_park’]} merges the sources with label velo_park and moto_park into a new source two_wheels_park.

Properties:

LayerConfig

Properties:

  • args (string[], optional)

  • filter (string, optional)

  • postfix (string, optional)

  • separator (string, optional)

LineConfiguration

Configuration object for one profile’s line.

Properties:

MapConfig

The map definition.

Properties:

  • maxTilesLoading (number, optional)

  • moveTolerance (number, optional)

  • pixelRatio (number, optional)

MeasureRasterLayer

Properties:

  • decimals (number, optional)

  • name (string)

  • unit (string, optional)

MousePositionProjection

Projection object for the MousePositionDirective. Define a label and a filter to use to display coordinates for a projection.

Properties:

  • code (string)

  • filter (string)

  • label (string)

OptionsLegendType

Properties:

  • label ({string: boolean})

  • params ({string: {string: string}})

  • showGroupsTitle (boolean, optional)

  • useBbox (boolean, optional)

Projection

A projection definitions.

Properties:

  • definition (string[])

  • extent (number[])

RegularShape

Specify radius for regular polygons, or radius1 and radius2 for stars. See also: https://openlayers.org/en/latest/examples/regularshape.html

Properties:

  • angle (number, optional)

  • displacement (number[], optional)

  • fill (Fill, optional)

  • points (number)

  • radius (number, optional)

  • radius1 (number, optional)

  • radius2 (number, optional)

  • rotateWithView (boolean, optional)

  • rotation (number, optional)

  • stroke (Stroke, optional)

RoutingProfile

Properties:

  • label (string)

  • profile (string)

SearchAction

Properties:

  • action (string)

  • title (string)

SearchComponentDatasource

Datasource configuration options for the search directive.

Properties:

StringToHtmlReplacement

Properties:

  • compiled_expression (RegExp, optional)

  • expression (string)

  • flags (string, optional)

  • template (string)

Stroke

Properties:

  • color (number[] | string, optional)

  • lineCap (lineCap, optional)

  • lineDash (number[], optional)

  • lineDashOffset (number, optional)

  • lineJoin (lineJoin, optional)

  • miterLimit (number, optional)

  • width (number, optional)

Style

The style description.

Properties:

StyleLike

View

The view definition.

Properties:

  • center (number[], optional)

  • constrainOnlyCenter (boolean, optional)

  • constrainResolution (boolean, optional)

  • constrainRotation (boolean | number, optional)

  • enableRotation (boolean, optional)

  • extent (number[], optional)

  • maxResolution (number, optional)

  • maxZoom (number, optional)

  • minResolution (number, optional)

  • minZoom (number, optional)

  • multiWorld (boolean, optional)

  • projection (string)

  • resolution (number, optional)

  • resolutions (number[], optional)

  • rotation (number, optional)

  • showFullExtent (boolean, optional)

  • smoothExtentConstraint (boolean, optional)

  • smoothResolutionConstraint (boolean, optional)

  • zoom (number, optional)

  • zoomFactor (number, optional)

WfsType

A WFS type. To be used with {@link WfsPermalinkOptions }.

Properties:

  • defaultFeatureNS (string, optional)

  • defaultFeaturePrefix (string, optional)

  • featureNS (string, optional)

  • featurePrefix (string, optional)

  • featureType (string)

  • label (string, optional)

authenticationBaseUrl

URL to the authentication web service.

defaultLang

Default language

fulltextsearchUrl

URL to the full-text search web service.

gmfAuthenticationConfig

The Authentication configuration.

Properties:

  • allowPasswordChange (boolean)

  • allowPasswordReset (boolean)

gmfAuthenticationNoReloadRole

Don’t request a new user object from the back-end after logging out if the logged-in user’s role has this role.

gmfBackgroundLayerSelectorOptions

The background layer selector options

Properties:

  • opacityLayer (string, optional)

gmfContextualDataOptions

Properties:

  • projections (string[])

  • rasterParams ({string: string})

gmfCsvFilename

The CSV file name.

gmfCustomCSS

Additional CSS for the different elements

Properties:

  • authentication (string)

  • authenticationPanel (string)

  • desktopCanvas (string)

  • lidarFooter (string)

  • lidarPanel (string)

gmfCustomJavascriptUrl

Use to inject custom javascript from an URL.

gmfCustomStylesheetUrl

Use to inject custom stylesheet from an URL.

gmfDatasourceOptions

Properties:

gmfDisclaimerOptions

The disclaimers options

Properties:

  • external (boolean, optional)

  • layerVisibility (boolean, optional)

  • popup (boolean, optional)

gmfDisplayQueryGridOptions

The display query grid component options.

Properties:

  • featuresStyle (StyleLike)

  • maxRecenterZoom (number, optional)

  • mergeTabs (GridMergeTabs, optional)

  • removeEmptyColumns (boolean, optional)

  • selectedFeatureStyle (StyleLike)

gmfDisplayQueryWindowOptions

The display query window component options.

Properties:

  • collapsed (boolean, optional)

  • displayNullAttributes (boolean, optional)

  • featuresStyle (StyleLike)

  • selectedFeatureStyle (StyleLike)

gmfEditFeatureOptions

Properties:

  • closeAfterSave (boolean)

  • highlightStyle (StyleLike)

  • tolerance (number)

gmfElevationOptions

The elevation (raster) options.

Properties:

  • layers (string[])

  • layersConfig ({string: LayerConfig})

gmfExternalOGCServers

gmfFloors

Floor dimension values and labels.

gmfLayerTreeOptions

Properties:

  • isExpanded (boolean)

  • openlinksinnewwindow (boolean)

gmfLayersUrl

URL to the layers web service.

gmfMobileMeasureAreaOptions

Properties:

  • precision (number, optional)

  • sketchStyle (StyleLike)

gmfMobileMeasureLengthOptions

Properties:

  • precision (number, optional)

  • sketchStyle (StyleLike)

gmfMobileMeasurePointOptions

Properties:

gmfMousePositionOptions

Properties:

gmfObjectEditingToolsOptions

Additional configuration options for the object editing tools directive.

Properties:

  • regularPolygonRadius (number, optional)

gmfOptions

The application wide options.

Properties:

gmfPermalinkOptions

Configuration options for the permalink service.

Properties:

  • crosshairEnabledByDefault (boolean, optional)

  • crosshairStyle (StyleLike, optional)

  • pointRecenterZoom (number, optional)

  • projectionCodes (string[], optional)

  • useLocalStorage (boolean, optional)

gmfPrintOptions

Properties:

  • defaultLayout (string, optional)

  • fieldValues ({string: string | number | boolean}, optional)

  • goodnessOfFit (number, optional)

  • hiddenAttributes (string[], optional)

  • legend (OptionsLegendType, optional)

  • rotateMask (boolean, optional)

  • scaleInput (boolean, optional)

gmfPrintUrl

URL to MapFishPrint.

gmfProfileJsonUrl

URL to the profile web service.

gmfProfileOptions

The elevation (raster) options.

Properties:

  • hoverPointStyle (StyleLike)

  • numberOfPoints (number, optional)

gmfProjectionsOptions

The available projections definitions.

Properties:

gmfQueryGrid

Use the query grid instead the query window to display the query result.

gmfRasterUrl

URL to the raster web service.

gmfSearchGroups

gmfSearchOptions

Properties:

  • clearButton (boolean, optional)

  • colorChooser (boolean, optional)

  • coordinatesProjections (string[])

  • datasources (SearchComponentDatasource[])

  • delay (number, optional)

  • maxZoom (number, optional)

  • placeholder (string, optional)

  • styles ({string: StyleLike})

gmfShareOptions

Properties:

  • enableEmail (boolean, optional)

gmfShortenerCreateUrl

URL to the shortener web service.

gmfSnappingOptions

The snapping options

Properties:

  • maxFeatures (number)

gmfThemesOptions

Configuration options for the themes service.

Properties:

  • addBlankBackgroundLayer (boolean, optional)

gmfTreeManagerModeFlush

Flush mode active?

gmfTreeUrl

URL to the theme web service.

gmfTwoFactorAuth

Does the application use tow factor authentication

langUrls

Languages URL

Properties:

ngeoCsvEncoding

File encoding of the CSV file.

ngeoCsvExtension

File extension of the CSV file.

ngeoCsvIncludeHeader

Whether to include the header in the exported file or not.

ngeoCsvQuote

Quote character.

ngeoCsvSeparator

Separator character.

ngeoGeolocationOptions

Options for the geolocation directive.

Properties:

  • accuracyFeatureStyle (StyleLike, optional)

  • atLoadingTime (boolean, optional)

  • autoRotate (boolean, optional)

  • positionFeatureStyle (StyleLike, optional)

  • zoom (number, optional)

ngeoMeasureDecimals

ngeoMeasurePrecision

ngeoMeasureSpherical

ngeoNominatimSearchDefaultParams

Properties:

ngeoOfflineTestUrl

URL of the test page to detect online/offline.

ngeoPermalinkOgcserverUrl

URL to the WFS server.

ngeoPointfilter

ngeoProfileOptions

Options for the profile.

Properties:

  • light (boolean, optional)

  • lightXAxis (boolean, optional)

  • linesConfiguration ({string: LineConfiguration})

  • poiLabelAngle (number, optional)

  • styleDefs (string, optional)

ngeoQueryOptions

The options for the query service.

Properties:

  • bboxAsGETParam (boolean, optional)

  • cursorHover (boolean, optional)

  • featureNS (string, optional)

  • featurePrefix (string, optional)

  • geometryName (string, optional)

  • limit (number, optional)

  • queryCountFirst (boolean, optional)

  • sourceIdsProperty (string, optional)

  • tolerance (number, optional)

  • toleranceTouch (number, optional)

ngeoRoutingOptions

Properties:

ngeoScaleSelectorOptions

The scale selector options

Properties:

  • dropup (boolean, optional)

  • values (number[])

ngeoSnappingTolerance

ngeoStreetviewOptions

Configuration object for streetview.

Properties:

  • bufferSize (number, optional)

  • key (string)

  • viewer (string)

ngeoStringToHtmlReplacements

List of replacements for string to html.

ngeoTilesPreloadingLimit

Load tiles up to preload levels. By default preload is Infinity, which means load all tiles on the top of the visible level. See also preload value in documentation for ol.Layer.Tile.

ngeoUsedKeyRegexp

Regexp used to identify the used keys.

ngeoWfsPermalinkOptions

The options for the WFS query service (permalink).

Properties:

  • defaultFeatureNS (string)

  • defaultFeaturePrefix (string)

  • maxFeatures (number, optional)

  • pointRecenterZoom (number, optional)

  • wfsTypes (WfsType[])

ogcServerDatasourceOptions

Properties:

  • arcgisWMSInfoFormat (string)

pytreeLidarprofileJsonUrl

URL to LIDAR profile pytree service.

CSS style

Simple and advanced modes

In the gmfOptions we have a cssVars property where we can configure all CSS variable (var(--a-variable) in the css files.

The content of cssVars is a dictionary where the keys are the CSS variable names, and the values the value to be set to the CSS variable. For the CSS variables named brand-primary and brand-secondary we also calculated the other colors related to those variable as it’s done in the SCSS, to be able to change the major application colors.

The components of the interface are using Shadow DOM (in open mode). That means that their style is protected and not accessible through the main css file. To change the styling of a component, you can inject your style with the gmfCustomCSS constants in the vars.yaml file. Example:

<interface>:
  constants:
    gmfCustomCSS:
      authentication: '<selector> {<property>: <value>;}'

Advanced mode only

In the advanced mode, you can set the style of a component by selecting the component using the querySelector native function and by appending a new style to this element. Example:

const style = document.createElement( 'style' )
style.innerHTML = '<selector> {<property>: <value>;}'
document.querySelector('<my-component-selector>').shadowRoot.appendChild(style);

Or alternatively, you can override a component to access and modify the render function. In this function, you can modify the customCSS_ property to set directly your own style. This way is not recommended if you don’t have to override the component for another purpose.

Creating your own component

Note

This is not possible in the simple application mode

Create your .ts file in a dedicated folder under: geoportal/<package>_geoportal/static-ngeo/js/. We encourage you to use LitElement web-components.

For the structure, you can be inspired by one of the (not AngularJS) components in ngeo. For instance, the src/auth/FormElement.ts.

Here’s a Hello <name> component:

// File ...static-ngeo/js/custom/helloWorld.ts;
import {html, TemplateResult, CSSResult, css} from 'lit';
import {customElement, property} from 'lit/decorators.js';
import GmfBaseElement from 'gmfapi/elements/BaseElement';
import i18next from 'i18next';

@customElement('hello-world')
export default class GmfAuthForm extends GmfBaseElement {
  @property({type: String}) name = 'Unknow';

  connectedCallback(): void {
    super.connectedCallback();
  }

  static styles: CSSResult[] = [
    ...GmfBaseElement.styles,
    css`
      .name {
        color: green;
      }
    `,
  ];

  protected render(): TemplateResult {
    return html`
      <div>
        <span>${i18next.t('Hello')}&nbsp;</span>
        <span class="name">${this.name}</span>
      </div>
    `;
  }
}

Then load your component in the controller of one of your interfaces:

import GmfAuthForm from '../custom/helloWorld';

At this point, if in your <interface> HTML app file you declare your component, it should be loaded:

<hello-world name="Demo"></hello-world>

It should print Hello Demo (with “Demo” in a green color).

If you have no error and no result, verify that the component is correctly declared and loaded. A custom markup in the HTML is not an error and no error will be thrown if the component is not loaded at all.

Every information that could be used by multiple components should be stored in a store. Our stores are based on the rxjs library. Existing stores in ngeo are in srcapi/store.

Logic between a store and a component should be stored in a singleton (“service”). A singleton is a class with only one instantiation. This instance is exported and usable everywhere in the code. Example in ngeo: src/auth/service.ts.

We recommend to minimize the amount of code within your component, and to use reusable external classes, static functions, helper and utils files instead. It will facilitate the maintenance.

Extending or overriding an existing component

Note

This is not possible in the simple application mode

Overriding an existing component is possible but you have to test carefully your code after each GMF update as the original code may have changed.

You can define some new functions or new variables to a class via the prototype. Here’s an example with the ngeo auth form component:

import GmfAuthForm from 'ngeo/auth/FormElement';

GmfAuthForm.prototype.myNewValue;

GmfAuthForm.prototype.newFunction = function () {};

To replace an existing function, just create a function with the same name than the one to replace:

GmfAuthForm.prototype.logout(evt: Event): void {
  console.log('I do nothing but print a message');
};

You will have to copy-paste the content of the original function to keep the component working. But you can modify it.

Finally be sure that the file where you override or extend existing content is read by the main controller file of your app:

import '../custom/myOverridenComponent.js';

Note

You can do the same with every “store”, “service”, function, etc. as long as the original piece of code you want to override is exported.

Note

The constructor of a class is not modifiable. If you want to modify to logic inside a constructor, you must copy the original class to a new custom class and use it instead of the original one. In some cases, you may use inheritance (with the extends keyword) to limit the copy-paste.