parametermanager

The Parameter Manager delegates URL parameters to those parameterizable components. It also provides an API to generate a URL with current app state parameters (see API Documentation). For details, see use cases.

The bundle share-link provides a widget that allows users to share a link.

Usage

No configuration is needed.

The following aspects of an app can be controlled by a URL parameter:

The following table shows how to use each parameter and gives an example URL.

URL parameters are shown as unencoded strings for exposition only. They must be encoded into valid URL components in practice (for example by using JavaScript's encodeURIComponent()).

To use multiple parameters at once, you may combine them with an & like for example .../index.html?lang=en&theme=everlasting.

Setting layers visibility and transparency

Parameter l is used to set the layers' visible or invisible state that differs from the initial app configuration. This means that only the visibility of layers appearing in the URL are changed. The visibility of other layers of your app remains untouched. The transparency of layers can be controlled by this parameter, too.

The notation is explained in the following samples:

To set layers visible, list their IDs:

index.html?l=id1,id2,...

Listed IDs may contain the following characters: A-Z a-z 0-9 - + _ : . | and the special characters äÄ öÖ üÜ and ß (spaces are not allowed).

Combine the ID with a leading - to set the layer invisible:

index.html?l=-id1,-id2,...

A combination looks like:

index.html?l=id1,-id2,id3,-id4

Layers id1 and id3 are visible, layers id2 and id4 are invisible.

To control the transparency of a layer use the curly braces syntax:

index.html?l=id1{t:10},-id2{t:0},~id3{t:90}
// encoded: index.html?l=id1%7Bt%3A10%7D%2C-id2%7Bt%3A0%7D%2C~id3%7Bt%3A90%7D

• Layer id1 is set visible with 10 percent transparency (opacity:0.9).
• Layer id2 is set invisible and 0 percent transparency (opacity: 1).
• Layer id3 is independent of the visibility, the transparency is changed to 90 percent (opacity: 0.1).

A special syntax is used to control the visibility of sub layers:

index.html?l=image(1,3)
// encoded: index.html?l=image(1%2C3)

This means that layer image is set to visible and the sub layers 1 and 3 are visible, too.

To modify the visibility of sub layers only add a ~ to the layer ID.

index.html?l=~image(1,3)
// encoded: index.html?l=~image(1,3)

This means that only the sub layers 1 and 3 are set visible, layer image remains as defined by the app configuration.

The - sign can be used for sub layer IDs, too.

index.html?l=~image(-1,-3)
// encoded: index.html?l=~image(-1,-3)

This means that the sub layers 1 and 3 are set invisible while image is untouched.

If the name property is available at a sublayer, this property is preferred over the id property. This means that for WMS layers the names of the service layers are encoded if available.

index.html?l=~wms_germany(CITY,COUNTY)
// encoded: index.html?l=~wms_germany(CITY%2CCOUNTY)

If change of transparency is supported by sublayers, the curly braces syntax can be used here, too.

index.html?l=~image(0{t:50})
// encoded: index.html?l=~image(0%7Bt%3A50%7D)

Layer sublayer 0 of layer image is changed to be 50 percent transparent and visible.

To keep URLs short, use short IDs for your layers.

WARNING: If you do not declare an ID for your layer, an ID is generated automatically. The generated ID changes on every app reload and therefore cannot be used in a parameterized link!

Constraints

• Some values such as x,y,scale,heading or tilt are rounded when encoded in the URL to keep the URL short. This may cause some small shifts of the view, if the generated URL is called. To go to a more exact view, add more precise values in the URL manually.
• Layer visibility is only applied when an app is launched. Layers that are added after app launch are not recognized.

Use Cases

How to use the ParameterManager API

The ParameterManager is registered as parametermanager.ParameterManager in the system. The ParameterManager's public interface is described in the API Documentation.

Reference it in your manifest.json file like this:

components:[{
        "name": "MyURLWidget",
        "references": [{
            "name": "parameterManager",
            "providing": "parametermanager.ParameterManager"
        }]
}]

The ParameterManager provides the method 'getEncodedURL' to resolve a URL to the current app that has parameters appended.

class MyURLWidget {

    showURL(){
        // as default base URL window.location is used
        let urlWithParameters = parameterManager.getEncodedURL();

        // you can choose a custom base URL for the parameters
        let myBase = http://myserver.de;
        let myBaseWithParameters = parameterManager.getEncodedURL(myBase);

    }
}

How to build a custom Parametrizable

The ParameterManager component gets injected all components that implement the parametermanager.Parametrizable interface. See also the API Documentation.

The interface defines following methods:

interface Parametrizable {

    /**
     *  (optional) lists all parameters handled by this Parametrizable.
     *  It is used to remove existing URL parameters if they
     *  are not listed by the encodeURLParameter() response.
     */
    parameterNames: ["myparameter"],

    /**
     * Creates an object, which lists all parameters to append to a URL.
     * Parameters that have 'undefined' values are removed from a URL.
     */
    encodeURLParameter() {
        return {
            "myparamter": "value"
        };
    }
    /**
     * Called by the ParameterManager to trigger the decoding of parameters.
     */
    decodeURLParameter(allParameters) {
        let value = allParameters.myparameter;
        // do something with the value
    }
}

When the app is started, the ParameterManager analyzes the URL and assigns the key-value pairs from the URL to a JavaScript object. It calls decodeURLParameter on each parametrizable component and passes the JavaScript object containing the URL parameters as argument. Each Parametrizable component is responsible to interpret the values from the URL and perform the corresponding actions.

To encode the values from a single Parametrizable into the URL, the ParameterManager component calls the encodeURLParameter method on each Parametrizable. That method must return an object where the properties contain the URL values as strings.