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

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

See FeatureCollection.

See ol.Feature.

See ol.geom.Geometry.

See ol.control.Control.

See ol.control.Control.

See Bloodhound Usage.

See Typeahead Dataset.

Properties:
  • displacement (number[], optional)

  • fill (Fill, optional)

  • radius (number)

  • stroke (Stroke, optional)

Properties:
  • name (string)

  • type (string)

  • url (string)

Properties:
  • color (number[] | string, optional)

Properties:

Properties:
  • args (string[], optional)

  • filter (string, optional)

  • postfix (string, optional)

  • separator (string, optional)

Properties:
  • color (string, optional)

  • zExtractor (integrator_guide_ngeo_properties_ZExtractorFunction)

Properties:
  • maxTilesLoading (number, optional)

  • moveTolerance (number, optional)

  • pixelRatio (number, optional)

Properties:
  • decimals (number, optional)

  • name (string)

  • unit (string, optional)

Properties:
  • code (string)

  • filter (string)

  • label (string)

Properties:
  • label ({string: boolean})

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

  • showGroupsTitle (boolean, optional)

  • useBbox (boolean, optional)

Properties:
  • definition (string[])

  • extent (number[])

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)

Properties:
  • label (string)

  • profile (string)

Properties:
  • action (string)

  • title (string)

Properties:
Properties:
  • compiled_expression (integrator_guide_ngeo_properties_RegExp, optional)

  • expression (string)

  • flags (string, optional)

  • template (string)

Properties:
  • color (number[] | string, optional)

  • lineCap (integrator_guide_ngeo_properties_CanvasLineCap, optional)

  • lineDash (number[], optional)

  • lineDashOffset (number, optional)

  • lineJoin (integrator_guide_ngeo_properties_CanvasLineJoin, optional)

  • miterLimit (number, optional)

  • width (number, optional)

Properties:
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)

Properties:
  • defaultFeatureNS (string, optional)

  • defaultFeaturePrefix (string, optional)

  • featureNS (string, optional)

  • featurePrefix (string, optional)

  • featureType (string)

  • label (string, optional)

Properties:
  • allowPasswordChange (boolean)

  • allowPasswordReset (boolean)

Properties:
  • opacityLayer (string, optional)

Properties:
  • projections (string[])

  • rasterParams ({string: string})

Properties:
  • authentication (string)

  • authenticationPanel (string)

  • desktopCanvas (string)

  • lidarFooter (string)

  • lidarPanel (string)

Properties:
  • external (boolean, optional)

  • layerVisibility (boolean, optional)

  • popup (boolean, optional)

Properties:
  • featuresStyle (StyleLike)

  • maxRecenterZoom (number, optional)

  • mergeTabs (GridMergeTabs, optional)

  • removeEmptyColumns (boolean, optional)

  • selectedFeatureStyle (StyleLike)

Properties:
  • collapsed (boolean, optional)

  • featuresStyle (StyleLike)

  • selectedFeatureStyle (StyleLike)

Properties:
  • closeAfterSave (boolean)

  • highlightStyle (StyleLike)

  • tolerance (number)

Properties:
  • layers (string[])

  • layersConfig ({string: LayerConfig})

Properties:
  • isExpanded (boolean)

  • openlinksinnewwindow (boolean)

Properties:
  • precision (number, optional)

  • sketchStyle (StyleLike)

Properties:
  • precision (number, optional)

  • sketchStyle (StyleLike)

Properties:
Properties:
Properties:
  • regularPolygonRadius (number, optional)

Properties:
  • controlZoom (integrator_guide_ngeo_properties_OlControlZoomOptions)

  • cssVars ({string: string})

  • geolocalisation (boolean, optional)

  • interationDefaults (integrator_guide_ngeo_properties_OlInteractionDefaultsOptions, optional)

  • map (MapConfig)

  • mapControls (ol.control.Control[], optional)

  • mapInteractions (ol.interaction.interaction[], optional)

  • showInfobar (boolean, optional)

  • view (View)

  • zoom (number)

Properties:
  • crosshairEnabledByDefault (boolean, optional)

  • crosshairStyle (StyleLike, optional)

  • pointRecenterZoom (number, optional)

  • projectionCodes (string[], optional)

  • useLocalStorage (boolean, optional)

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)

Properties:
  • hoverPointStyle (StyleLike)

  • numberOfPoints (number, optional)

Properties:

Properties:
  • clearButton (boolean, optional)

  • colorChooser (boolean, optional)

  • coordinatesProjections (string[])

  • datasources (SearchComponentDatasource[])

  • delay (number, optional)

  • maxZoom (number, optional)

  • placeholder (string, optional)

  • styles ({string: StyleLike})

Properties:
  • enableEmail (boolean, optional)

Properties:
  • maxFeatures (number)

Properties:
  • addBlankBackgroundLayer (boolean, optional)

Properties:

Properties:
  • accuracyFeatureStyle (StyleLike, optional)

  • atLoadingTime (boolean, optional)

  • autoRotate (boolean, optional)

  • positionFeatureStyle (StyleLike, optional)

  • zoom (number, optional)

Properties:

Properties:
  • light (boolean, optional)

  • lightXAxis (boolean, optional)

  • linesConfiguration ({string: LineConfiguration})

  • poiLabelAngle (number, optional)

  • styleDefs (string, optional)

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)

Properties:
Properties:
  • dropup (boolean, optional)

  • values (number[])

Properties:
  • bufferSize (number, optional)

  • key (string)

  • viewer (string)

Properties:
  • defaultFeatureNS (string)

  • defaultFeaturePrefix (string)

  • maxFeatures (number, optional)

  • pointRecenterZoom (number, optional)

  • wfsTypes (WfsType[])

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.