Configuration Methods and Techniques

Ways to Configure Sites

There are two ways to configure sites:

Use Geocortex Essentials Manager: Geocortex Essentials ships with a web-based tool for authoring and managing Geocortex Essentials sites, Geocortex Essentials Manager.

This is the recommended method for configuring sites. For most applications, you can do all your configuration in Manager.
Edit the Site Configuration File (Site.xml): You can edit site configuration files in a text editor or XML editor.

This method is recommended for advanced users only—it is very easy to introduce errors into XML by mistake. If you are developing a custom site extension, you must use this method.

If the configuration file contains invalid XML, the site will not work—you will not be able to edit the site in Manager or load the site in a viewer.

Ways to Add Components to a Site

Manager has three methods of adding components to a site:

Add
Import
Inherit (reference)

Add Components

Adding a component to a site adds the component with its default configuration.

In most cases, Manager uses wizards to add components to your site. The purpose of wizards is to step you through the configuration of a particular component's required settings or most important settings. Some components have less important or optional settings that are not included in the wizard. Any setting that is not in the Add wizard is assigned a default value which you can modify after you finish the wizard.

Editing an item after you have added it to your site enables you to:

Change the values of settings that you configured in the Add wizard.
Change the values of settings that the wizard did not allow you to set.
Add sub components, if the item you added supports any.

Import Components

After you have configured a component in one site using the Add function, you can import the component into as many other sites as you want. Importing a component copies the component and its configuration from the other site.

After you have imported the component, you can change its configuration. The original component and the imported copy are independent of each other—changing the configuration of one has no effect on the other.

Importing is often quicker and easier than adding, because it saves you from having to configure all of the component's settings. Also, you can import multiple components of a particular type at one time, as long as they are configured in the same site.

Inherit (Reference) Components

To make a site inherit components that are configured somewhere else, you add a reference to the site.

References have two uses:

Site Inheritance: References enable a site to inherit another site's configuration. Inherited components are added to the site's configured components.

Adding a reference to another site saves you from reconfiguring components in multiple sites.
Web Maps: References enable you to include web maps in your sites.

Geocortex Essentials does not place a limit on the number of references that you can add to a site.

Editing and Removing Components

Manager provides standard tools for editing and removing any type of component:

Edit Tool ( ): Every component that you add to a site has an Edit icon beside it in Manager, regardless of the method used to add it. Click the Edit icon beside a component to edit the component.

Editing a component allows you to configure the component's settings, and add, edit, or remove sub components.
Remove Tool ( ): Every component that you add to a site has a Remove icon beside it in Manager, regardless of the method used to add it. Click the Remove icon beside a component to delete the component. Deleting a component is permanent—you cannot undo a deletion.

Respect the Map Scale for Printing

Changing the configuration to ensure that the map scale is respected for printing applies only to map services. The configuration change does not apply to feature services, image services and other types of service on the site.

In some cases, features that are visible on a map are not included when the user prints the map. This occurs during the print preparation process when the calculated map scale is greater than the maximum scale that is set for the map service. To ensure that the visible features on the map are also included in the print output, you need to add a key to <appsettings> in the Web.config file.

The Web.config file is located in the Geocortex Essentials installation location in:

...\Rest Elements\REST\Web.config

Add the following key to <appsettings>:

Inherit Another Site's Configuration

Site inheritance is the ability to make one site inherit another site's configuration, including all of its configured components and settings. If you want Site A to inherit Site B's configuration, you edit Site A and add a reference to Site B. This example is used throughout this section—Site A contains a reference to Site B, so Site B is inherited.

Usually the components and settings in the inherited site (B) are added to the components and settings in the site that contains the reference (A). For example, if Site A references Site B, Site A will include all of its own configured components and settings, as well as all of Site B's components and settings. If a particular component is configured in both sites, Site A will have two instances of the component—one that is configured in Site A and one that is inherited from Site B.

The following table illustrates how adding a reference affects the components in a site. The leftmost column shows the components that are configured in Site A. The middle column shows the components that are configured in Site B. The last column lists all the components in Site A, both configured and inherited, after you configure a reference to Site B.

Components for Site A, Site B, and Site A after a reference to Site B is added

Components Configured in Site A	Components Configured in Site B	Total Components in Site A after a Reference to Site B is Added
Charlotte ArcGIS map service	Charlotte ArcGIS map service	Charlotte ArcGIS map service (configured)
Charlotte Silverlight viewer	Streets Bing Maps map service	Charlotte Silverlight Viewer (configured)
	Imagery Bing Maps map service	Charlotte ArcGIS map service (inherited)
	Ledger Print Template	Streets Bing Maps map service (inherited)
	CharlotteBing HTML5 Viewer	Imagery Bing Maps map service (inherited)
		Ledger Print Template (inherited)
		CharlotteBing HTML5 Viewer (inherited) *

* Inheritance works differently for viewers than for other components. See Viewer Inheritance.

Note that the Charlotte map service appears twice in Site A—one instance is configured in A and the other is inherited from B. The two instances can be configured differently, for example, they could have different visibility settings for their layers, different settings for inclusion in global search, and so on.

References can be chained. For example, suppose Site A references Site B and Site B references sites C and D. Site A inherits the configuration of all three sites, B, C, and D.

Inheritance of Unique Components and Settings

Some settings can occur only once in a site. For example, a site can only have one initial extent for the map or one overview map. This means that Essentials cannot simply add these components and settings to the site that contains the reference—special rules are required:

If Site A's component or setting still has its default value but you have changed the component or setting in Site B, Essentials uses Site B's component or setting.
In all other cases, Essentials uses Site A's component or setting.

The rules ensure that Essentials preserves any customization you have made to the component or setting, with preference given to the Site A.

Note that these rules are for a simple, unchained scenario. In more complicated scenarios, where inheritance is chained, Essentials uses the last non-default value in the chain.

Example: Chained Inheritance of Unique Components

Suppose A references B, B references C and D (in that order), and C references E. Site A inherits the configurations of B, C, D, and E. If A, B, and C use the default initial extent, and D and E have configured values for the initial extent, then D's value is used (not E's, because E is inherited as part of C's configuration, which comes before D's configuration).

Changing the Inherited Configuration

You can modify or remove inherited components and settings. Modifications you make to inherited components and settings override the inherited configuration, but do not affect the source configuration.

Inheritance works differently for viewers than for other components—when you modify the configuration of an inherited viewer, the configuration of the source viewer is also modified. See Viewer Inheritance below.

To disambiguate multiple components with the same name or multiple copies of the same component, you might want to modify or remove the inherited component.

Example: Modify the Display Name of an Inherited Layer

Suppose Site B has a map service with a layer called "Navigable Waters", and Site A references Site B. If you edit Site A and change the inherited layer's display name to "Waterways", the layer will appear as "Waterways" in Site A and "Navigable Waters" in Site B.

If you then edit Site B and change the layer's name from "Navigable Waters" to "Navigation", the layer still appears as "Waterways" in site A—your change is preserved.

Example: Modify the Visibility of an Inherited Map Service

You have a site called City that references your County site. One of the components that City inherits from County is an Agriculture map service. In the County site, the Agriculture service's default visibility is turned on. You want the default visibility to be turned off in the City site, so you edit the City site and turn off the visibility. This has no affect on the visibility of the map service in the County site—the map service's visibility is turned on in the County site and turned off in the City site.

Example: Remove an Inherited Map Service

Suppose sites A and B both have a map service called Land Use. After you add a reference to Site B, Site A has two map services called Land Use, one from A and the other inherited from B. In Site A, you remove the inherited Land Use map service, so A's map only has one instance of Land Use in it.

Example: Remove an Inherited Print Template

You create a Print Templates site where you configure print templates for your mapping sites to use. You want your County site to have all the print templates that are configured in the Print Templates site, except for the E Size template. You edit the County site and click Print Templates in the side panel. This shows you the complete list print templates in the County site, both configured and inherited. You click the Remove tool beside E Size and save the site. This has no effect on the configuration of the print template in Print Templates site, or on the template (.rpx file) itself. The County site no longer has the E Size print template.

Changing the Source Configuration

When one site references another, it remains linked to the referenced site. For example, if Site A references Site B, then A is linked to B. This means that if B's configuration changes, the change is reflected in A.

Changes made in Site B appear immediately in Site A in Manager. In the REST API, there can be a short delay before the changes appear.

Example: Add a Menu Item to the Source Configuration

Suppose Site A inherits a viewer from Site B. If you edit Site B and add a Run Workflow item to the viewer's I Want To menu, the Run Workflow item is automatically added to the viewer's I Want To menu in Site A's configuration. Similarly, if you change the title of the I Want To menu to "Tasks" in B, the menu's title is automatically changed to "Tasks" in A.

Example: Remove a map Service in the Source Configuration

Site A inherits three map services from Site B, including one called Roadways. You edit Site B and remove Roadways from the map. Now you save Site B and edit Site A. Site A no longer has the Roadways map service in it.

Viewer Inheritance

Inheritance works differently for viewers than for other components in one respect—when you modify the configuration of an inherited viewer, the configuration of the source viewer is also modified.

Deleting an inherited viewer does not affect the source viewer.

Example: Add a Menu Item to an Inherited Viewer

Suppose Site A references Site B and Site B has a viewer called B_Viewer configured for it. Site A inherits B_Viewer. You edit Site A and add an item to the I Want To menu of the inherited B_Viewer. Now you save Site A and edit Site B. You see that the I Want To menu for B_Viewer in Site B has the new item that you added in Site A.

Example: Remove an Inherited Viewer

Suppose Site A inherits a viewer from Site B. You edit Site A and remove the inherited viewer. Now you save Site A and edit Site B. You see that the viewer has not been removed or changed in any way in Site B.

Ways to Configure Hyperlinks in the Viewer

Including hyperlinks in a viewer's user interface is a powerful way to improve the viewer's usability. Whenever possible, viewers display hyperlinks for URLs that you configure in a site. In addition, Geocortex Essentials has a variety of features and tools for creating links in the viewer:

Layer Hyperlinks: Links to web pages that are relevant to the layer. Layer hyperlinks appear in a layer's or map service's context menu in the Layer List. Layer hyperlinks can contain layer tokens. For more information, see Layer Hyperlinks.
Feature Hyperlinks: Links to web pages containing information that is relevant to the feature. Feature hyperlinks appear in the feature's details. Feature hyperlinks can contain field tokens. For more information, see Feature Hyperlinks.
HTML Hyperlinks: Some settings that you configure in Manager can contain HTML markup including anchor elements (<a> tags), which define hyperlinks. Specifically, the Feature Label, Feature Description, and Feature Long Description boxes on a layer's Details tab support HTML markup. Manager has a built-in Rich Text Editor that converts your configuration to HTML markup. To open a layer's Details tab, edit the layer.
Viewer Commands in Hyperlinks: Viewer commands can be embedded in HTML anchor elements. The command executes when the user clicks the hyperlink. For more information, see Viewer Commands in Hyperlinks
Layer Tokens: Placeholders that represent layer properties. Layer tokens enable you to define dynamically generated hyperlinks that depend on the current layer. For more information, see Layer Tokens.
Field Tokens: Placeholders that represent feature attributes. Field tokens enable you to define dynamically generated hyperlinks that depend on the current feature. For more information, see Field Tokens.
Object Tokens: Placeholders that represent objects. Object tokens let you pass an object representing the current feature to a viewer command. For more information, see Object Tokens.
Data Link Tokens: Placeholders that represent the fields in a data link. Data link tokens enable you to define dynamically generated hyperlinks that depend on the current feature's data links. For more information, see Data Link Tokens.
Relationship Tokens: Placeholders that represent the fields in a layer or table that is related to another layer. For more information, see Relationship Tokens.

HTML5 viewers have links for common operations built into them, for example, viewers have a Zoom to Feature hyperlink that is visible when a feature is selected.

The Geocortex Services Enhancement Proxy

The Geocortex Services Enhancement Proxy is a legacy component that should only be enabled for applications that use the Geocortex Viewer for Silverlight or the Geocortex Viewer for HTML5 version 2.5.2 or older. For information on the Geocortex Services Enhancement Proxy, see the Geocortex Essentials 4.5 Administrator Guide.