URLs (Uniform Resource Locators) are also known as web addresses. For example, http://www.esri.com/
is a URL. A viewer URL is a URL that launches a viewer. In order for a user to launch a viewer, the user must know the viewer's URL, or have access to a hyperlink or QR code that links to the URL.
Geocortex Essentials Manager provides viewer launch links in several places: in the Site List, on the Viewers page, and also on the Viewer Info page for a specific viewer. These links are useful while you are developing and testing a site.
For legibility, URLs and URL parameters are shown unencoded. You should always URL encode your URLs.
The general form of a viewer's URL is:
http://<server.domain.com>/<iis-virtual-directory>/<page>?<url-parameters>
where:
<server.domain.com>
specifies the server that the viewer template is deployed to.
<iis-virtual-directory>
is the virtual directory in IIS that the viewer template is deployed to.
<page>
is the name of the page to launch, for example, Index.html
.
<url-parameters>
are the parameters that allow you to control how the viewer launches—the extent that is initially shown, the language that is used, and so on.
The simplest URL to launch an HTML5 viewer is:
http://<server.mydomain.com>/<iis-virtual-directory>
This launches the default page, Index.html
, for an unsecured site. The default page detects the type of device and launches the appropriate interface: Desktop, Tablet or Handheld.
To explicitly launch the Tablet interface for medium-format, touch-screen devices like tablets, use Tablet.html
as the <page>
. To explicitly launch the Handheld interface for small-format, touch-screen devices like smartphones, use Handheld.html
as the <page>
.
To find the URL for a particular viewer, launch the viewer and copy the URL from the browser's address bar. To launch the viewer, click the viewer's Launch URL link in Manager.
Launch URL for an HTML5 viewer, shown on Manager's Viewers page
Note that the viewer URLs that Manager displays are not the full URL—it is just the link text. For example, the full URL for the link shown above is actually:
http://MyServer.com/Html5Viewer/Index.html?configBase=http://MyServer.com/Geocortex/Essentials/REST/sites/LA_County/viewers/LA_County_HTML/virtualdirectory/Resources/Config/Default
A URL parameter is a string attached to a URL that specifies initial values or actions. For example, you can use the extent
URL parameter to make the map zoom to a particular extent when the viewer is launched. From the end user's point of view, the URL parameter's value is the default value. For example, to the end user, the extent at which the map loads is the default extent.
To specify a URL parameter, you add a question mark to the end of the URL, followed by parameter=value
. The general form is:
http://server.domain.com/vwr/Index.html?parameter=value
A URL can have multiple parameters. Parameters are separated by the ampersand character (&). The general form is:
http://server.domain.com/vwr>/Index.html?parameter1=value1¶meter2=value2&...
For a viewer to launch, the viewer must load a configuration file. If you know what type of device the end user will be using, you can specify which configuration file to load. If the viewer will be launched on different types of devices, you can let the viewer detect the device type and load the appropriate configuration file.
The viewer launch URL has two parameters that you can use to tell the viewer how to locate the configuration file to load:
configBase
: Specify the folder that contains the three different configuration files, and let the viewer detect the type of device and load the appropriate configuration file. The launch links in Manager use the configBase
parameter.
viewerConfigUri
: Specify which configuration file to load. This parameter overrides the configBase
parameter.
Example
In this example, the Handheld interface of the LA_County site's LA_County_HTML viewer launches in Canadian French with debugging turned on. The site is not secured.
http://server.domain.com/vwr/Handheld.html?configBase=http://server.domain.com/Geocortex/Essentials/REST/sites/LA_County/viewers/LA_County_HTML/VirtualDirectory/Resources/Config/Default&locale=fr-CA&debug=true
For legibility, URLs and URL parameters are shown unencoded. You should always URL encode your URLs.
URL Parameters that can be used in HTML5 Viewer launch URLs |
---|
|
Specifies the coordinates at which to center the map when the map image loads. If you want to specify the coordinates using a different spatial reference than the map's, append the WKID that you want to use. |
Syntax: |
Example 1: In this example, the map pans to center on the specified map coordinates when the viewer is launched. http://MyServer.com/Html5Viewer/Index.html?center=-13176043.9862,4002474.5385 Example 2: In this example, the coordinates are given in the specified spatial reference (WKID 4326) instead of the map's spatial reference. When the viewer is launched, the map is reprojected to WKID 4326 and then pans to the specified coordinates. http://MyServer.com/Html5Viewer/Index.html?center=-114.7993,30.9820,4326 Example 3: In this example, the http://MyServer.com/Html5Viewer/Index.html?center=255421.6566,b6250846.4361,3857&scale=9000 |
Module: Map Module |
|
Specifies the URI of the folder where the configuration files are stored. The viewer detects the device type and loads the appropriate configuration file from the specified folder. Use a fully qualified URI. This URL parameter is useful if the viewer will be launched on different device types. You can force the viewer to load a particular configuration file even though it uses |
Syntax: |
Example 1: This example launches the http://MyServer.com/Html5Viewer/Index.html?configBase=http://MyServer.com/Geocortex/Essentials/REST/sites/LA_County/Viewers/LA_County_HTML/VirtualDirectory/Resources/Config/Default Example 2: This example launches the http://MyServer.com/Html5Viewer/Handheld.html?configBase=http://MyServer.com/Geocortex/Essentials/REST/sites/LA_County/Viewers/LA_County_HTML/VirtualDirectory/Resources/Config/Default |
Module: None |
|
Logs additional types of event to the viewer's log file, and lists commands executed and events fired in the console. If you do not want additional logging turned on, omit the |
Syntax: |
Example: This example turns on additional logging for the viewer. http://MyServer.com/Html5Viewer/Index.html?debug |
Module: Log Module |
|
Zooms the map to the specified map coordinates. If you want to specify the coordinates using a different spatial reference than the map's, append the WKID that you want to use. |
Syntax: |
Example 1: In this example, the map zooms to the specified map coordinates when the viewer is launched. http://MyServer.com/Html5Viewer/Index.html?extent=1441172.484,550015.006,1456136.010,537754.744 Example 2: In this example, the coordinates are given in the specified spatial reference (WKID 4326) instead of the map's spatial reference. The map zooms to the specified latitude/longitude coordinates when the viewer is launched. http://MyServer.com/Html5Viewer/Index.html?extent=35.2468,-80.8718,35.2139,-80.8210,4326 |
Module: Map Module |
layerTheme |
Specifies the layer theme to use when the viewer launches. You can specify the layer theme either by its ID or by its Display Name. |
Syntax: |
Example 1: In this example, the viewer launches using a layer theme with the ID, http://MyServer.com/Html5Viewer/Index.html?layerTheme=0 Example 2: In this example, the viewer launches using a layer theme with the Display Name, http://MyServer.com/Html5Viewer/Index.html?layerTheme=Imagery |
Module: LayerThemes Module |
locale |
Specifies the language to use for the viewer. For this parameter to work, a language file for the specified language must exist and be configured in the viewer configuration. See Geocortex Viewer for HTML5 Translation for instructions. By default, viewers display date/time and number data in the user's locale. The |
Syntax: The language code for |
Example: In this example, the viewer launches in Canadian French, provided the fr-CA language file exists and is configured. http://MyServer.com/Html5Viewer/Index.html?locale=fr-CA |
Module: None— |
project |
Specifies a project to load when the viewer launches. The Projects belong to the site of the viewer that created the project. A user cannot create a project in one viewer and then load the project in a viewer that belongs to a different site. |
Syntax: You can find out a project's ID by viewing the project’s details on Manager's Data Store - Documents page. For information, see Geocortex Data Store. Alternatively, you can get the project's ID from the Project URL that shows on the viewer's Share Project panel. See Sharing Projects for information. |
Example: This example launches the LA_County_HTML viewer and loads the project with ID 45ca42175c554a1e82c9a63cb3d570b3: http://host.domain.com/Html5Viewer/Index.html?viewer=LA_County.LA_County_HTML&project=45ca42175c554a1e82c9a63cb3d570b3 |
Module: Project Module |
|
Runs the specified workflow(s), mapping URL parameters to workflow input arguments. The If you specify more than one workflow to run, the workflows run concurrently. Each additional workflow must be separated by a comma ( Workflows specified with the If the workflow has arguments, you specify the arguments the same way you would specify additional URL parameters ( |
Syntax: These two forms run workflows that do not have arguments:
These two forms run the specified workflow with the specified arguments (
|
Example 1: In this example, the URL that you make available to end users launches the viewer and runs the workflow with ID "StartupWorkflow". StartupWorkflow does not have any arguments. http://MyServer.com/Html5Viewer/Index.html&runWorkflow=StartupWorkflow Example 2: This example runs the FindParcel workflow. The FindParcel workflow finds the specified parcel, and then optionally runs a report using the parcel's information. The workflow's two arguments are:
http://MyServer.com/Html5Viewer/Index.html&run=FindParcel&pid=02503116&reportToRun=MailingLabels Example 3: This example runs the same FindParcel workflow as the previous example, except the optional http://MyServer.com/Html5Viewer/Index.html&run=FindParcel&pid=02503116 |
Module: Workflow Module |
|
Specifies the initial scale. The |
Syntax: |
Example 1: In this example, when the viewer launches, the map zooms to the scale nearest to 1:2654.7813. http://MyServer.com/Html5Viewer/Index.html?scale=2654.7813 Example 2: In this example, the http://MyServer.com/Html5Viewer/Index.html?center=255421.6566,6250846.4361,3857&scale=9000 |
Module: Map Module |
Specifies the ID of the viewer to launch. The value to use for the As the name suggests, the Global Unique ID must be unique for each viewer across all sites and instances of Essentials. The Global Unique ID must not contain special characters such as <, >, %, &, :, *, \, / and ?. If you do not set the Global Unique ID, all viewers use the default Global Unique ID, which consists of the Site ID and the Viewer ID separated by a period character. For example, |
Syntax: |
Example: In this example, the viewer whose Global Unique ID is http://MyServer.com/Html5Viewer/Index.html?viewer=MyViewer The Global Unique ID is set by editing the viewer, on the Viewer Info page. |
Module: None |
|
The Specifies the URI of the configuration file to load. We recommend using a fully qualified URI. The configuration file must be on the same domain as the viewer. This parameter overrides the This URL parameter is useful if you know the type of device that the end user will be using. If you do not know the device type, use the |
Syntax: |
Example: This example launches the http://MyServer.com/Html5Viewer/Index.html?viewerConfigUri=http://MyServer.com/Geocortex/Essentials/REST/sites/LA_County/viewers/LA_County_HTML/VirtualDirectory/Resources/Config/Default/Handheld.json.js Because you are specifying which configuration file to load, you could use the corresponding HTML page— |
Module: None |
You can set up a short launch URL for a particular viewer that has the form:
http://MyServer.com/Html5Viewer/index.html?viewer=MyViewer
There are a few different ways to set up the value for the viewer
parameter:
Configure the Global Unique ID.
We recommend this method because it is both the easiest and the most robust in terms of upgrading the viewer.
Configure a short viewer URL in the ViewerSettings.json.js file.
This method may slightly improve performance but requires manually editing a viewer configuration file. Any changes will also survive after upgrading the viewer. This method overrides the previous method.
Configure a short viewer URL in the Index.html file.
This method offers the greatest performance but is also the most fragile. Any changes must be reapplied after upgrading the viewer. We do not recommend using this method. This method overrides the previous methods.
To configure the Global Unique ID by editing the viewer:
In beside the viewer.
On the Viewer Info page, type any value without special characters for Global Unique ID. For example, MyViewer.
As the name suggests, the Global Unique ID must be unique for each viewer across all sites and instances of Essentials.
The Global Unique ID must not contain special characters such as <, >, %, &, :, *, \, / and ?.
Click Apply Changes.
Click Save Site.
The Launch in Browser link now contains the short launch URL in the form of:
http://MyServer.com/Html5Viewer/index.html?viewer=MyViewer
where the viewer
parameter is the same value as the Global Unique ID of the viewer.
If you do not set the Global Unique ID, all viewers use the default Global Unique ID, which consists of the Site ID and the Viewer ID separated by a period character. For example, http://MyServer.com/Html5Viewer/index.html?viewer=MySiteID.MyViewerID
.
To configure a short viewer URL in the ViewerSettings.json.js file:
In the root folder where the HTML5 Viewer is installed, open the ViewerSettings.json.js
file in a text editor. The default location is:
C:\inetpub\wwwroot\Html5Viewer\ViewerSettings.json.js
You may need to run your text editor as an Administrator to modify this file.
For each viewer, do one of the following:
To configure a short launch link for any interface, in the viewerSettings
array, add a new object with the following properties.
The viewerConfigUri
property has been deprecated.
{ "viewerSettings": [ { "id": "MyViewer", "url": "http://MyServer.com/Geocortex/Essentials/REST/sites/LA_County/Viewers/LA_County_HTML/VirtualDirectory/Resources/Config/Default/", "securityUrl": "" } ], ... }
Set id
to any value without special characters you want to use for the viewer
parameter.
Set url
to the folder containing the viewer configuration files.
If the site is secured, set the optional securityUrl
property to the Essentials sign-in URL. For example:
http://MyServer.com/Geocortex/Essentials/REST/security/signin?token_type=fragment&app=
To configure a short launch link for a specific interface such as the Handheld interface, in the viewerSettings
array, add a new object with the following properties:
{ "viewerSettings": [ { "id": "MyViewer", "viewerConfigUri": "http://MyServer.com/Geocortex/Essentials/REST/sites/LA_County/viewers/LA_County_HTML/VirtualDirectory/Resources/Config/Default/Handheld.json.js", "securityUrl": "" } ], ... }
Set id
to any value without special characters you want to use for the viewer
parameter.
Set viewerConfigUri
to the location of a specific viewer configuration file.
If the site is secured, set the optional securityUrl
property to the Essentials sign-in URL. For example:
http://MyServer.com/Geocortex/Essentials/REST/security/signin?token_type=fragment&app=
If you want the viewer to use a custom splash screen image, add the splashScreenUrl
property to the viewerSettings
object. Set splashScreenUrl
to the image's fully qualified URL.
When you configure the short URL in the ViewerSettings.json.js
file, you must configure the custom splash screen image in the ViewerSettings.json.js
file instead of in Manager.
{ "viewerSettings": [ { "id": "MyViewer", "url": "http://MyServer.com/Geocortex/Essentials/REST/sites/LA_County/Viewers/LA_County_HTML/VirtualDirectory/Resources/Config/Default/", "splashScreenUrl": "http://host.domain.com/resources/images/splash-image.png" "securityUrl": "" } ], ... }
Save the file.
You can use the following URL to launch the viewer:
http://MyServer.com/Html5Viewer/index.html?viewer=MyViewer
To configure a short viewer URL in the Index.html file:
In the root folder where the HTML5 Viewer is installed, open the Index.html
file in a text editor. The default location is:
C:\inetpub\wwwroot\Html5Viewer\Index.html
You may need to run your text editor as an Administrator to modify this file.
For each viewer, do one of the following:
Within the ViewerInitializationOptions
object passed into the ViewerLoader
's loadAndInitialize()
method, add a new property to the aliases
property:
new geocortex.essentialsHtmlViewer.ViewerLoader().loadAndInitialize({ aliases: { default: "Resources/Config/Default/" + shellName + ".json.js", MyViewer: "http://MyServer.com/Geocortex/Essentials/REST/sites/LA_County/viewers/LA_County_HTML/virtualdirectory/Resources/Config/Default/" + shellName + ".json.js" } });
Set the name of the new property to the ID you want to use for the viewer
parameter.
Set the value of the new property to the location of the viewer configuration file. The shellName
variable allows the viewer to load different configuration files for each type of interface: Desktop, Tablet or Handheld.
Viewers defined using this method override viewers defined using the following alternative method.
Within the viewerConfig
variable, add a new property to the configurations
property:
var viewerConfig = { "configurations": { "default": "Resources/Config/Default/" + shellName + ".json.js", "MyViewer": "http://MyServer.com/Geocortex/Essentials/REST/sites/LA_County/viewers/LA_County_HTML/virtualdirectory/Resources/Config/Default/" + shellName + ".json.js" }, "viewerConfigUri": null };
Set the name of the new property to the ID you want to use for the viewer
parameter.
Set the value of the new property to the location of the viewer configuration file. The shellName
variable allows the viewer to load different configuration files for each type of interface: Desktop, Tablet or Handheld.
The configuration files must be on the same domain as the viewer.
Save the file.
You can use the following URL to launch the viewer:
http://MyServer.com/Html5Viewer/index.html?viewer=MyViewer
You do not need a different URL to access a secured site—you can use a regular viewer URL, as described above in Form of a Viewer's URL. However, you can improve a viewer's launch performance by using a URL that links directly to the sign-in page. A direct link skips the steps required for the viewer to determine whether the site is secured.
When you link directly to the sign-in page, you pass the viewer's URL as a parameter. This ensures that the user's browser can be correctly directed to the viewer after the user has authenticated.
The general form for a URL that links directly to the sign-in page is:
http://server.domain.com/Geocortex/Essentials/REST/security/signIn?[url-parameters]
For legibility, URLs and URL parameters are shown unencoded. You should always URL encode your URLs.
The table below lists the parameters that you can use in sign-in page URLs.
URL Parameters for Sign-in Page URLs |
---|
|
The URL of the web application (viewer) to launch after the user has authenticated. The |
Syntax: |
|
The security provider to use for authentication. Some security providers are identified using a predefined value. Other security providers are identified by the security provider's unique issuer seed. For information, see Find the Value for the idp URL Parameter below. The |
Syntax: |
|
Required in viewer URLs that link directly to the sign-in page. |
Syntax: |
The idp
URL parameter identifies the security provider to use for authentication. The table below lists the values for different security providers. For Geocortex Identity Server and ArcGIS Online security providers, you need the security provider's issuer seed. Instructions for getting the issuer seed are given below the table.
Values to Use for the idp URL Parameter
Security Provider |
Value |
Example |
---|---|---|
Windows Integrated |
AD AUTHORITY |
idp=AD AUTHORITY |
Anonymous Access |
urn:gcx:guest |
idp=urn:gcx:guest |
Geocortex Identity Server |
urn:gcx:idp:[issuer-seed] |
idp=urn:gcx:idp:2895BE5E-FA19-4731-82F1-33F5FE30F786 |
ArcGIS Online |
urn:gcx:ags:[issuer-seed] |
idp=urn:gcx:ags:b2e2357d-84e8-4406-94aa-e34b798d1a98 |
To get the issuer seed for a security provider:
In
Click the Edit icon beside the security provider whose issuer seed you want to get.
In the Advanced area, select the issuer seed and copy it.
Click OK to close the dialog box.
Paste the issuer seed in the URL's idp
parameter.
Suppose you have a site that is secured using the Windows Integrated security provider. The URL below performs the authentication using Windows Authentication, and then launches the HTML5 viewer called MyViewer
.
http://server.domain.com/Geocortex/Essentials/REST/security/signIn?token_type=fragment&idp=AD+AUTHORITY&app=http://server.domain.com/viewers/Index.html?Viewer=MyViewer
Suppose you have a site that is secured using ArcGIS Online. The URL below performs the authentication using ArcGIS Online, and then launches the HTML5 viewer called mobile
in the Handheld interface.
http://server.domain.com/Geocortex/Essentials/REST/security/signIn?token_type=fragment&idp=urn:gcx:ags:9b567ddc-27ab-4321-b968-570df7b53bfe&app=http://server.domain.com/gvh/Handheld.html?Viewer=mobile
As the application administrator, you must provide users with a way to launch the viewer. There are different ways to do this:
URL: Give the viewer's URL to users, so they can type the URL into their browser's address bar.
Hyperlink: Put a hyperlink representing the viewer's URL on a website or other web-connected resource. Users click the hyperlink to launch the viewer.
URL-encode your URLs.
QR Code: Provide a QR (Quick Response) code in a web or print resource. To launch the viewer, users scan the QR code using a mobile device, such as a smartphone or tablet.
To display a QR code for a launch link in Manager, hover the mouse pointer over the QR code icon beside the launch link—the icon will expand into a scannable QR code.