SharingLink Module

The SharingLink Module creates viewer URLs that the Share Module can share with other applications.

As part of creating a viewer URL to share, the SharingLink Module assembles URL parameters. The URL parameters for sharing links fall into two categories:

• Intrinsic: URL parameters that are preserved from the URL that the user used to launch the viewer.

• State-Preserving: URL parameters that capture the viewer's current state.

Intrinsic URL Parameters

Intrinsic URL parameters come from the URL that the user used to launch the viewer. Usually, intrinsic parameters are essential for the viewer to function properly. By default, the following URL parameters are intrinsic:

• configBase

• viewer

• viewerConfigUri

For example, suppose the original URL uses the viewerConfigUri parameter to point to the viewer's configuration files. When the SharingLink Module assembles a URL to share, it copies the viewerConfigUri parameter and its value from the original URL to the sharing URL that it is assembling.

You can override the default list of intrinsic parameters using the intrinsicUrlParameters property. Note that intrinsicUrlParameters overrides the default list—it does not add to it. This means that you must include the default intrinsic parameters in the list, as well as any other parameters that you want to preserve from the original URL.

For example, suppose the original URL contains the viewerConfigUri, extent, and runWorkflow parameters. Under the default configuration, the SharingLink Module copies viewerConfigUri to the sharing URL, but not extent or runWorkflow. If you want sharing links to run the workflow but not set the extent to the original URL's extent, you could configure intrinsicUrlParameters as follows:

  {
    "moduleName": "SharingLink",
    "moduleType": "geocortex.essentialsHtmlViewer.mapping.modules.sharingLink.SharingLinkModule",
    "configuration": {
      intrinsicUrlparameters [
        configBase,
        viewer,
        viewerConfigUri,
        runWorkflow
      ],
    ...

In this example, you do not have to include viewer and viewerConfigUri in intrinsicUrlParameters. However, it is a good practice to list all of the default intrinsic parameters.

We recommend that you list all the default intrinsic parameters in intrinsicUrlParameters, even if you do not use them all in the URLs that you distribute to your users. Then, if you ever change the method that you use to point to the viewer's configuration files, sharing links will still work.

The intrinsicUrlParameters property can include any of the parameters listed in the URL Parameters Reference.

State-Preserving URL Parameters

State-preserving URL parameters preserve the state of the viewer when the user shares the link. Preserving the viewer's state ensures that other users see the same view of the map as the user who shared the link. For example, a URL parameter that captures the current map extent is state preserving.

The SharingLink Module creates state-preserving URL parameters when it assembles the sharing link. The specific parameters are determined by the sharingLinkProviders property. Each sharing link provider corresponds to a URL parameter that the SharingLink Module includes in the sharing link. The sharing link providers are:

• LayerThemeSharingLinkProvider: Preserves the layer theme that is active when the user shares the link.

• LayersSharingLinkProvider: Preserves a snapshot of which layers are visible when the user shares the link.

• ExtentSharingLinkProvider: Preserves the map extent that is in effect when the user shares the link.

• CenterSharingLinkProvider: Preserves the coordinates of the map's center point when the user shares the link.

• ScaleSharingLinkProvider: Preserves the map's scale when the user shares the link.

By default, the layer theme, layer visibility, center, and scale providers are enabled, and the extent provider is disabled. There is no need to enable the extent provider when the center and scale providers are enabled.

The SharingLink Module has a HandleGenerateSharingLink command that creates the URL. If a sharing link provider's generate property is true, HandleGenerateSharingLink creates the parameter for that provider and includes it in the URL.

Each sharing link provider also has an apply property, which applies the parameter when the site is first loaded. By default, generate and apply are true. To disable a sharing link provider, set generate and apply to false. If you want the end user to supply the URL parameter, set generate to false and apply to true.

Each sharing link provider has a name property that you can use to change the names of the state-preserving URL parameters that are included in sharing links. This is useful for localization. For example, if your users are predominantly French, you could set each provider's name property to the name's French translation. Users who click the shared link will see the French names for the URL parameters.

Configuration Properties

Module

• intrinsicUrlParameters: An array of URL parameters to include in the sharing link URL. By default, intrinsicUrlParameters includes configBase, viewer, and viewerConfigUri. The full list of possible parameters is given in URL Parameters Reference.

• sharingLinkProviders: An array whose items control which aspects of the viewer's state are preserved in the sharing link. Each sharingLinkProvider corresponds to a URL parameter that can be included in the URL to share. Each provider has the following properties:

  • type: The type of sharing link provider.

  • name: The name that is used to identify the URL parameter within the URL. For example, in the URL http://server.domain.com/vwr/Index.html?center=-13176043.9862,4002474.5385, the parameter's name is center.

  • apply: When apply is true, the URL parameter is applied when the site is first loaded. If you omit apply from the configuration, it is true.

  • generate: When generate is true, the HandleGenerateSharingLink command creates the URL parameter for this provider and includes the parameter in the URL to share. If you omit generate from the configuration, it is true.

Views

The SharingLinks Module does not have any views.

View Models

The SharingLinks Module does not have any view models.

See also...

Share Module