gxp.Viewer¶

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.

authenticate

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.

defaultSourceType

String The default layer source plugin type.

defaultToolType

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

field

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

map

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.

mapItems

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.

mapPlugins

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

portalConfig

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.

portalItems

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

proxy

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

saveErrorText

String

sources

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.

tools

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.

Viewer.authenticate¶

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.

Viewer.authorizedRoles¶

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.

Viewer.field¶

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

Viewer.portalItems¶

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

Viewer.selectedLayer¶

GeoExt.data.LayerRecord The currently selected layer

Viewer.tools¶

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

Public Methods¶

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

Viewer.cancelAuthentication()¶

Cancel an authentication process.

Viewer.createLayerRecord()¶

Parameters:	config – Object A minimal layer configuration object with source and name properties. callback – Function A function to be called with the layer record that corresponds to the given config. scope – Object 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.

Viewer.destroy()¶

Viewer.doAuthorized()¶

Parameters:	roles – Array Roles required for invoking the action callback – Function The action to perform scope – Object 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.

Viewer.getLayerRecordFromMap()¶

Parameters:	config – Object A minimal layer configuration object with source and name properties.
Returns:	GeoExt.data.LayerRecord

Retrieves a layer record from the map.

Viewer.getSource()¶

Parameters:	layerRec – GeoExt.data.LayerRecord the layer to get the source for.

Viewer.isAuthenticated()¶

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.

Viewer.isAuthorized()¶

Parameters:	roles – String|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.

Viewer.loadConfig()¶

Parameters:	config – Object 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()¶

Parameters:	record – GeoExt.data.LayerRecord` Layer record. Call with no layer record to remove layer selection.
Returns:	Boolean Layers were set as selected.

TODO: change to selectLayers (plural)

Viewer.setAuthorizedRoles()¶

Parameters:	authorizedRoles – Array

Change the authorized roles.

Events¶

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

authorizationchange

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

beforecreateportal

Fires before the portal is created by the Ext ComponentManager.

beforehashchange

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

window.location.hash

beforelayerselectionchange

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

Listeners arguments:

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

beforesave

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.

featureedit

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

layerselectionchange

Fired when the selected set of layers changes.

Listeners arguments:

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

portalready

Fires after the portal is initialized.

ready

Fires when application is ready for user interaction.

save

Fires when the map has been saved.

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