OpenLayers.Control.FeaturePopups

The FeaturePopups control selects vector features from a given layers on click and hover and can show the feature attributes in a popups.

Inherits from

  • <OpenLayers.Control>
Summary
OpenLayers.Control.FeaturePopupsThe FeaturePopups control selects vector features from a given layers on click and hover and can show the feature attributes in a popups.
Properties
modeTo enable or disable the various behaviors of the control.
autoActivate{Boolean} Activate the control when it is added to a map.
selectOptions{Object|null} Used to set non-default properties on SelectFeature control dedicated to select features.
boxSelectionOptions{Object|null} Used to set non-default properties on <OpenLayers.Handler.Box> dedicated to select features by a box.
hoverOptions{Object|null} Used to set non-default properties on SelectFeature control dedicated to highlight features.
popupOptions{Object} Options used to create a popup manager for hover & selections, see defaults for any valid keys.
popupHoverOptions{Object} Options used to create a popup manager to highlight on hover.
popupHoverListOptions{Object} Options used to create a popup manager for highlight on hover a cluster.
popupSingleOptions{Object} Options used to create a popup manager for single selections.
popupListOptions{Object} Options used to create a popup manager for multiple selections.
popupListItemOptions{Object} Options used to create the popup manager for show a single item into a multiple selection.
layerListTemplateDefault is “<h2>${layer.name} - ${count}</h2><ul>${html}</ul>”
hoverClusterTemplateDefault is “Cluster with ${cluster.length} features<br>on layer \”${layer.name}\””
Constructor
OpenLayers.Control.FeaturePopupsCreate a new control that internally uses two <OpenLayers.Control.SelectFeature> one for selecting features, and another only to highlight them by hover (see selectOptions, and hoverOptions).
Functions
destroy
activateActivates the control.
deactivateDeactivates the control.
clearClear selecction and popups.
addLayerAdd the layer to control and assigns it the templates, see options.
addLayers
removeLayer
unselectAllUnselect all selected features, only works if the control is active.
unselectGenericUnselect all selected features on layers on the control that don’t have popupOptions.
unselectLayerUnselect all selected features on the layer, only works if the control is active and layer is on the control.
Constants
Modes

Properties

mode

To enable or disable the various behaviors of the control.

Use bitwise operators and one or more OpenLayers.Control.FeaturePopups

NONETo not activate any particular behavior.  CLOSE_ON_REMOVE -Popups will close when removing features in a layer, is ignored when used in conjunction with SAFE_SELECTION.
SAFE_SELECTIONFeatures will remain selected even have been removed from the layer.  Is useful when using <OpenLayers.Strategy.BBOX> with features with “fid” or when using <OpenLayers.Strategy.Cluster>.  Using “BBOX” when a feature is added back to the layer will be re-selected automatically by “fid”.
CLOSE_ON_UNSELECTPopups will close when unselect the feature.
CLOSE_BOXDisplay a close box inside the popups.
UNSELECT_ON_CLOSETo unselect all features when a popup is closed.
DEFAULTIncludes default behaviors SAFE_SELECTION | CLOSE_ON_UNSELECT | CLOSE_BOX | UNSELECT_ON_CLOSE

Default is OpenLayers.Control.FeaturePopups.DEFAULT.

autoActivate

{Boolean} Activate the control when it is added to a map.  Default is true.

selectOptions

{Object|null} Used to set non-default properties on SelectFeature control dedicated to select features.  When using a null value the select features control is not created.  The default is create the control.

Default options other than SelectFeature control

  • clickout: false
  • multipleKey: ‘shiftKey’
  • toggleKey: ‘shiftKey’

Options ignored

boxSelectionOptions

{Object|null} Used to set non-default properties on <OpenLayers.Handler.Box> dedicated to select features by a box.  When using a null value the handler is not created.  The default is do not create the handler, so don’t use box selection.

Default options other than Box handler

  • KeyMask: OpenLayers.Handler.MOD_CTRL
  • boxDivClassName: ‘olHandlerBoxSelectFeature’

hoverOptions

{Object|null} Used to set non-default properties on SelectFeature control dedicated to highlight features.  When using a null value (or selectOptions.hover == true) the highlight features control is not created.  The default is create the control.

Options ignored

popupOptions

{Object} Options used to create a popup manager for hover & selections, see defaults for any valid keys.

May contain 5 valid keys: “hover”,”hoverList”, “list”, “single” and, “listItem”.  To not use the popups associated with a key set the value of the key to null.

For more details of valid options for any key see FeaturePopups.Popup.Constructor.

NOTE: Use this keys instead of popupHoverOptions, popupHoverListOptions, popupListOptions, popupSingleOptions and popupListItemOptions.

Default options for “hover”

popupClass<OpenLayers.Popup.Anchored>
panMapIfOutOfViewfalse
followCursortrue
anchor{size: new OpenLayers.Size(15, 19), offset: new OpenLayers.Pixel(-1, -1)}
relatedToClear[“hoverList”]

Default options for “hoverList”

popupClass<OpenLayers.Popup.Anchored>
panMapIfOutOfViewfalse
followCursortrue
anchor{size: new OpenLayers.Size(15, 19), offset: new OpenLayers.Pixel(-1, -1)}
relatedToClear[“hover”]

Default options for “list”

popupClass<OpenLayers.Popup.FramedCloud>
panMapIfOutOfViewtrue
unselectFunctionDepends on the FeaturePopups.mode (internal use)
closeBoxDepends on the FeaturePopups.mode (internal use)
observeItemstrue (internal use)
relatedToClear[“hover”, “hoverList”, “listItem”, “single”]

Default options for “single”

popupClass<OpenLayers.Popup.FramedCloud>
panMapIfOutOfViewtrue
unselectFunctionDepends on the mode (internal use)
closeBoxDepends on the mode (internal use) relatedToClear: [“hover”, “hoverList”, “listItem”, “list”]

Default options for “listItem”

popupClass<OpenLayers.Popup.FramedCloud>
panMapIfOutOfViewtrue
closeBoxDepends on the mode (internal use)
relatedSimultaneous{axis: “v”, related: “list”} (internal use)
relatedToClear[“single”]

popupHoverOptions

{Object} Options used to create a popup manager to highlight on hover.  See FeaturePopups.Popup constructor options for more details.

Default options

popupClass<OpenLayers.Popup.Anchored>
panMapIfOutOfViewfalse

Default options for internal use

followCursortrue
anchor{size: new OpenLayers.Size(15, 19), offset: new OpenLayers.Pixel(-1, -1)}
relatedToClear[“hoverList”]

popupHoverListOptions

{Object} Options used to create a popup manager for highlight on hover a cluster.  See FeaturePopups.Popup constructor options for more details.

Default options

popupClass<OpenLayers.Popup.Anchored>
panMapIfOutOfViewfalse

Default options for internal use

followCursortrue
anchor{size: new OpenLayers.Size(15, 19), offset: new OpenLayers.Pixel(-1, -1)}
relatedToClear[“hover”]

popupSingleOptions

{Object} Options used to create a popup manager for single selections.  See FeaturePopups.Popup constructor options for more details.

Default options

popupClass<OpenLayers.Popup.FramedCloud>
panMapIfOutOfViewtrue

Default options for internal use

unselectFunctionDepends on the mode
closeBoxDepends on the mode relatedToClear: [“hover”, “hoverList”, “list”, “listItem”]

popupListOptions

{Object} Options used to create a popup manager for multiple selections.  See FeaturePopups.Popup constructor options for more details.

Default options

popupClass<OpenLayers.Popup.FramedCloud>
panMapIfOutOfViewtrue

Default options for internal use

unselectFunctionDepends on the mode
closeBoxDepends on the mode
observeItemstrue
relatedToClear[“hover”, “hoverList”, “single”, “listItem”]

popupListItemOptions

{Object} Options used to create the popup manager for show a single item into a multiple selection.  See FeaturePopups.Popup constructor options for more details.

Default options

popupClass<OpenLayers.Popup.FramedCloud>
panMapIfOutOfViewtrue

Default options for internal use

closeBoxDepends on the mode
relatedToClear[“single”]
relatedSimultaneous{axis: “v”, related: “list”}

layerListTemplate

Default is “<h2>${layer.name} - ${count}</h2><ul>${html}</ul>”

hoverClusterTemplate

Default is “Cluster with ${cluster.length} features<br>on layer \”${layer.name}\””

Constructor

OpenLayers.Control.FeaturePopups

Create a new control that internally uses two <OpenLayers.Control.SelectFeature> one for selecting features, and another only to highlight them by hover (see selectOptions, and hoverOptions).  This control can use also a <OpenLayers.Handler.Box> to select features by a box, see boxSelectionOptions .

The control can generates three types of popup: “hover”, “single” and “list”, see addLayer.  Each popup has a displayClass according to their type: “[displayClass]_hover” ,”[displayClass]_select” and “[displayClass]_list” respectively.

options{Object}

Functions

destroy

destroy: function()

activate

activate: function()

Activates the control.

Returns

{Boolean} The control was effectively activated.

deactivate

deactivate: function()

Deactivates the control.

Returns

{Boolean} The control was effectively deactivated.

clear

clear: function()

Clear selecction and popups.

addLayer

addLayer: function(layer,
options)

Add the layer to control and assigns it the templates, see options.

To add a layer that has already been added (maybe automatically), first must be removed using removeLayer.

Templates containing patterns as ${i18n(“key”)} are internationalized using <OpenLayers.i18n> function.

The control uses the patterns as ${showPopup()} in a “item” template to show individual popups from a list.  This pattern becomes a combination of the layer.id+feature.id and can be used only as an html attribute.

Parameters

layer{<OpenLayers.Layer.Vector>}
options{Object} Optional

Valid options

templates{Object} Templates
listContext{Object} Contains the keys with the values that were used instead of values of context used by templates `list` and `hoverList`.  If ‘undefined’ key exists their value will be used instead of text ‘undefined’.
featureContext{Object} Contains the keys with the values --could be a function or {string}--, the resulting value is used instead of values of feature property with the same name.  Used by templates: single, item, hover, hoverItem.  If ‘undefined’ key exists their value will be used instead of text ‘undefined’.
eventListeners{Object} This object will be registered with <OpenLayers.Events.on>, default scope is the control.
pupupOptions{Object} Inform to display the list popup separate from other layers, set to {} to use default options.  See <FeaturePopups.Layer.pupupOptions> property for more details.
templates: {
  hover: '${.name}',
  single: 'Name: ${.name}<br>Area: ${area} km2<hr>${.description}',
  item: '<li><a href="#" ${showPopup()}>${.name}</a></li>'
},
featureContext: {
  area: function(feature) { return feature.geometry.getArea(); },
  ...
}, ...

NOTE: If the features of the layer may have an ”fid” duplicate the key “fid” of “featureContext” should be declared, and returns unique values for each layer features, e.g. as

... },
featureContext: {
  fid: function(feature) { return feature.id; },
  ...
}, ...

Valid templates

single{String || Function} template used to show a single feature.
list{String || Function} template used to show selected features as a list (each feature is shown using “item”), defaul is layerListTemplate.
item{String || Function} template used to show a feature as a item in a list.
hover{String || Function} template used on hover a single feature.
hoverList{String || Function} template used on hover a clustered feature.
hoverItem{String || Function} template used to show a feature as a item in a list on hover a clustered feature.

Contexts of templates

single, item, hover, hoverItemContext is feature, can use `.` instead of `attributes.`, note that the feature can not have a layer property whether it belongs from clustered feature.
list, hoverListcontext is a object with three properties: “count” (number of features) “html” (html of list of features) and “layer” (vector layer)

If specified some template as layer property and as options has priority the options template.

Valid events on eventListeners

selectionchangedTriggered after selection is changed, receives a event with “layer” and “selection” as array of features (note that features are not clustered and in this case may lack the property layer)
featureschangedTriggered after layer features are changed, fired only changing the list of features and ignore the clusters changes or recharge if obtained new features but with the same “fid”.  Receives a event with “layer” and “features” as array of features (note that features are not clustered and in this case may lack the property layer)

Note: “featureschanged” event is the first if the “selectionchanged” event is also triggered.

addLayers

addLayers: function(layers)

Parameters

layersArray({<OpenLayers.Layer.Vector>} || Array({Object})) Layers to add, and array of layers or pairs of arguments layer and options.

removeLayer

removeLayer: function(layer)

unselectAll

unselectAll: function()

Unselect all selected features, only works if the control is active.

unselectGeneric

unselectGeneric: function()

Unselect all selected features on layers on the control that don’t have popupOptions.  Only works if the control is active.

unselectLayer

unselectLayer: function(layer)

Unselect all selected features on the layer, only works if the control is active and layer is on the control.

Constants

Modes

NONE{Integer} Used in mode indicates to not activate any particular behavior.
CLOSE_ON_REMOVE{Integer} Used in mode indicates that the popups will close when removing features in a layer.
SAFE_SELECTION{Integer} Used in mode indicates that the features will remain selected even have been removed from the layer.  Is useful when using <OpenLayers.Strategy.BBOX> with features with “fid” or when using <OpenLayers.Strategy.Cluster>.  Using “BBOX” when a feature is added back to the layer will be re-selected automatically by “fid”.
CLOSE_ON_UNSELECT{Integer} Used in mode indicates that the popups will close when unselect the feature.
CLOSE_BOX{Integer} Used in mode indicates to display a close box inside the popups.
UNSELECT_ON_CLOSE{Integer} Used in mode indicates to unselect all features when a popup is closed.
DEFAULT{Integer} Used in mode indicates to activate default behaviors as SAFE_SELECTION | CLOSE_ON_UNSELECT | CLOSE_BOX | UNSELECT_ON_CLOSE.
{Object|null} Used to set non-default properties on SelectFeature control dedicated to select features.
{Object|null} Used to set non-default properties on SelectFeature control dedicated to highlight features.
destroy: function()
activate: function()
Activates the control.
deactivate: function()
Deactivates the control.
clear: function()
Clear selecction and popups.
addLayer: function(layer,
options)
Add the layer to control and assigns it the templates, see options.
addLayers: function(layers)
removeLayer: function(layer)
unselectAll: function()
Unselect all selected features, only works if the control is active.
unselectGeneric: function()
Unselect all selected features on layers on the control that don’t have popupOptions.
{Object} Options used to create a popup manager for hover & selections, see defaults for any valid keys.
unselectLayer: function(layer)
Unselect all selected features on the layer, only works if the control is active and layer is on the control.
Create a new control that internally uses two OpenLayers.Control.SelectFeature one for selecting features, and another only to highlight them by hover (see selectOptions, and hoverOptions).
{Integer} Used in mode indicates to activate default behaviors as SAFE_SELECTION | CLOSE_ON_UNSELECT | CLOSE_BOX | UNSELECT_ON_CLOSE.
{Object|null} Used to set non-default properties on OpenLayers.Handler.Box dedicated to select features by a box.
{Object} Options used to create a popup manager to highlight on hover.
{Object} Options used to create a popup manager for highlight on hover a cluster.
{Object} Options used to create a popup manager for multiple selections.
{Object} Options used to create a popup manager for single selections.
{Object} Options used to create the popup manager for show a single item into a multiple selection.
To enable or disable the various behaviors of the control.
Default is “h2>${layer.name} - ${count}</h2><ul>${html}</ul”
{Integer} Used in mode indicates that the features will remain selected even have been removed from the layer.
{Integer} Used in mode indicates that the popups will close when unselect the feature.
{Integer} Used in mode indicates to display a close box inside the popups.
{Integer} Used in mode indicates to unselect all features when a popup is closed.
Close