Table Of Contents

Previous topic


Next topic



class gxp.Viewer(config)

A map viewer application framework that can be extended with plugins for layer sources and tools. Types of viewers that can be built with this framework range from simple map viewers to complex web-based GIS applications with capabilities like feature editing, styling and more.

Example Use

A viewer can be added to an HTML page with a script block containing something like this for a minimal viewer with an OSM layer:

var app = new gxp.Viewer({
    sources: {
        osm: {
            ptype: "gxp_osmsource"
    map: {
        center: [0, 0],
        zoom: 2,
        layers: [{
            source: "osm",
            name: "mapnik"

Config Options

Configuration properties in addition to those listed for Ext.util.Observable.


Function A global authentication function that is invoked by doAuthorized() if no user is logged in or the current user is not authorized. That process is supposed to call setAuthorizedRoles() upon successful authentication, and cancelAuthentication() if the user cancels the login process. Typically this function creates and opens a login window. Optional, default is null.


String The default layer source plugin type.


String The default tool plugin type. Default is “gxp_tool”


gxp.form.ViewerField Optional - set by gxp.form.ViewerField so plugins like gxp.plugins.FeatureToField can set the form field’s value.


Object Map configuration for this viewer. This object is similar to the GeoExt.MapPanel configuration, with the following exceptions:

  • center: Array of lon (x) and lat (y) values

  • items: not available - use mapItems instead

  • tbar: not available - use gxp.Tool plugins to populate the tbar

  • wrapDateLine: Boolean Should we wrap the dateline? Defaults to true

  • numZoomLevels: Integer The number of zoom levels to use.

  • layers: Array(Object). Each object has a source property referencing a gxp.plugins.LayerSource. The viewer will call the createLayerRecord of this source with the object as argument, which will result in a layer being created with the configuration provided here.

    Valid config options for all layer sources:

    • source: String referencing a source from sources
    • name: String - the name from the source’s store (only for sources that maintain a store)
    • visibility: Boolean - initial layer visibility
    • opacity: Number - initial layer.opacity
    • group: String - group for the layer when the viewer also uses a gxp.plugins.LayerTree. Set this to “background” to make the layer a base layer
    • fixed: Boolean - Set to true to prevent the layer from being removed by a gxp.plugins.RemoveLayer tool and from being dragged in a gxp.plugins.LayerTree
    • selected: Boolean - Set to true to mark the layer selected
  • map: not available, can be configured with maxExtent, numZoomLevels and theme.

  • restrictedExtent: Array to be consumed by OpenLayers.Bounds.fromArray - the restrictedExtent of the map

  • maxExtent: Array to be consumed by OpenLayers.Bounds.fromArray - the maxExtent of the map

  • numZoomLevels: Number - the number of zoom levels if not available on the first layer

  • theme: String - optional theme for the OpenLayers.Map, as in OpenLayers.Map.theme.


Array(Ext.Component) Any items to be added to the map panel. A typical item to put on a map would be a GeoExt.ZoomSlider.


Array(Ext.util.Observable) Any plugins to be added to the map panel.


Object Configuration object for the wrapping container of the viewer. This will be an Ext.Panel if it has a renderTo property, or an Ext.Viewport otherwise.


Array Items for the portal. A MapPanel will automatically be added to the portal, unless portalConfig has items configured.


String An optional proxy url which can be used to bypass the same origin policy. This will be set as OpenLayers.ProxyHost.




Object Layer source configurations for this viewer, keyed by source id. The source id will be used to reference the layer source in the layers array of the map object.


Array( gxp.plugins.Tool ) Any tools to be added to the viewer. Tools are plugins that will be plugged into this viewer’s portal. The tools array is usually populated with configuration objects for plugins (using a ptype), rather than instances. A default ptype can be configured with this viewer’s defaultToolType option.

Public Properties

Public properties in addition to those listed for Ext.util.Observable.


Function Like the config option above, but this can be set after configuration e.g. by a plugin that provides authentication. It can also be accessed to check if an authentication mechanism is available.


Array Roles the application is authorized for. This property is usually set by the setAuthorizedRoles() method, which is typically called by a component that authenticates the user (e.g. a login window. After authentication, if the client is authorized to do everything, this should be set to ["ROLE_ADMINISTRATOR"].

If this property is undefined, the isAuthorized() method will return undefined, so plugins can check for that to do their own auth checks in this case. So if the application uses an authentication component (e.g. a login window), it is recommended to set this to [] (equivalent to “not authorized to do anything”) initially.


gxp.form.ViewerField Used by plugins to access the form field. Only available if this viewer is wrapped into an Ext.form.ViewerField.


Array(Ext.Component) Items that make up the portal.

Viewer.selectedLayer The currently selected layer

Object Storage of tool instances for this viewer, keyed by id

Public Methods

Public methods in addition to those listed for Ext.util.Observable.


Cancel an authentication process.

  • configObject A minimal layer configuration object with source and name properties.
  • callbackFunction A function to be called with the layer record that corresponds to the given config.
  • scopeObject Optional scope for the callback.

Asyncronously retrieves a layer record given a basic layer config. The callback will be called as soon as the desired layer source is ready. This method should only be called to retrieve layer records from sources configured before the call.

  • rolesArray Roles required for invoking the action
  • callbackFunction The action to perform
  • scopeObject The execution scope for the callback

Performs an action (defined as callback function), but only if the user is authorized to perform it. If no user is logged in or the logged in user is not authorized, the viewer’s authenticate() function will be invoked. This method is usually called by plugins.

Parameters:configObject A minimal layer configuration object with source and name properties.

Retrieves a layer record from the map.

Viewer.getSource() the layer to get the source for.
Returns:Boolean The user has authenticated.

Determines whether a user has logged in. In cases where the application doesn’t provide a login dialog, the user will be considered logged in. In this same case, where components require authentication, the browser will prompt for credentials when needed.

Parameters:rolesString|Array optional, default is “ROLE_ADMINISTRATOR”. If an array is provided, this method will return if any of the roles in the array is authorized.
Returns:Boolean The user is authorized for the given role.

Returns true if the client is authorized with the provided role. In cases where the application doesn’t explicitly handle authentication, the user is assumed to be authorized for all roles. This results in authentication challenges from the browser when an action requires credentials.

Parameters:configObject The config object passed to the constructor.

Subclasses that load config asynchronously can override this to load any configuration before applyConfig is called.

Viewer.selectLayer()` Layer record. Call with no layer record to remove layer selection.
Returns:Boolean Layers were set as selected.

TODO: change to selectLayers (plural)


Change the authorized roles.


Events in addition to those listed for Ext.util.Observable.


Fired when the authorizedRoles are changed, e.g. when a user logs in or out.


Fires before the hash is updated after saving a map. Return false in the listener not to update the hash.

Listeners arguments: * hash - String The hash which will be set as


Fired before the selected set of layers changes. Listeners can return false to stop the selected layers from being changed.

Listeners arguments:

  • layerRecord - the record of the selected layer, or null if no layer is selected.

Fires before application saves a map. If the listener returns false, the save is cancelled.

Listeners arguments:

  • requestConfig - Object configuration object for the request, which has the following properties: method, url and data.
  • callback - Function Optional callback function which was passed on to the save function.

Fired when features were edited.

Listener arguments:

  • featureManager - gxp.plugins.FeatureManager the the feature manager that was used for editing
  • layer - Object object with name and source of the layer that was edited

Fired when the selected set of layers changes.

Listeners arguments:

  • layerRecord - the record of the selected layer, or null if no layer is selected.

Fires after the portal is initialized.


Fires when application is ready for user interaction.


Fires when the map has been saved.

Listener arguments: * id - Integer The identifier of the saved map