OpenLayers.ElementsIndexer

This class takes care of figuring out which order elements should be placed in the DOM based on given indexing methods.

Summary

OpenLayers.ElementsIndexer	This class takes care of figuring out which order elements should be placed in the DOM based on given indexing methods.
Properties
maxZIndex	{Integer} This is the largest-most z-index value for a node contained within the indexer.
order	{Array<String>} This is an array of node id’s stored in the order that they should show up on screen.
indices	{Object} This is a hash that maps node ids to their z-index value stored in the indexer.
compare	{Function} This is the function used to determine placement of of a new node within the indexer.
Functions
initialize	Create a new indexer with
insert	Insert a new node into the indexer.
remove
clear
exists
getZIndex	Get the z-index value for the current node from the node data itself.
determineZIndex	Determine the z-index for the current node if there isn’t one, and set the maximum value if we’ve found a new maximum.
getNextElement	Get the next element in the order stack.
OpenLayers.ElementsIndexer.IndexingMethods	These are the compare methods for figuring out where a new node should be placed within the indexer.
Functions
Z_ORDER	This compare method is used by other comparison methods.
Z_ORDER_DRAWING_ORDER	This method orders nodes by their z-index, but does so in a way that, if there are other nodes with the same z-index, the newest drawn will be the front most within that z-index.
Z_ORDER_Y_ORDER	This one should really be called Z_ORDER_Y_ORDER_DRAWING_ORDER, as it best describes which ordering methods have precedence (though, the name would be too long).
OpenLayers.Renderer.Elements	This is another virtual class in that it should never be instantiated by itself as a Renderer.
Properties
rendererRoot	{DOMElement}
root	{DOMElement}
vectorRoot	{DOMElement}
textRoot	{DOMElement}
xmlns	{String}
xOffset	{Number} Offset to apply to the renderer viewport translation in x direction.
rightOfDateLine	{Boolean} Keeps track of the location of the map extent relative to the date line.
Indexer	{<OpenLayers.ElementIndexer>} An instance of OpenLayers.ElementsIndexer created upon initialization if the zIndexing or yOrdering options passed to this renderer’s constructor are set to true.
Constants
BACKGROUND_ID_SUFFIX	{String}
LABEL_ID_SUFFIX	{String}
LABEL_OUTLINE_SUFFIX	{String}
Constructor
OpenLayers.Renderer.Elements
Functions
destroy
clear	Remove all the elements from the root
setExtent	Set the visible part of the layer.
getNodeType	This function is in charge of asking the specific renderer which type of node to create for the given geometry and style.
drawGeometry	Draw the geometry, creating new nodes, setting paths, setting style, setting featureId on the node.
redrawNode
redrawBackgroundNode	Redraws the node using special ‘background’ style properties.
drawGeometryNode	Given a node, draw a geometry on the specified layer.
postDraw	Things that have do be done after the geometry node is appended to its parent node.
drawPoint	Virtual function for drawing Point Geometry.
drawLineString	Virtual function for drawing LineString Geometry.
drawLinearRing	Virtual function for drawing LinearRing Geometry.
drawPolygon	Virtual function for drawing Polygon Geometry.
drawRectangle	Virtual function for drawing Rectangle Geometry.
drawCircle	Virtual function for drawing Circle Geometry.
removeText	Removes a label
getFeatureIdFromEvent
eraseGeometry	Erase a geometry from the renderer.
nodeFactory	Create new node of the specified type, with the (optional) specified id.
nodeTypeCompare
createNode
moveRoot	moves this renderer’s root to a different renderer.
getRenderLayerId	Gets the layer that this renderer’s output appears on.
isComplexSymbol	Determines if a symbol cannot be rendered using drawCircle

Properties

maxZIndex

{Integer} This is the largest-most z-index value for a node contained within the indexer.

order

{Array<String>} This is an array of node id’s stored in the order that they should show up on screen. Id’s higher up in the array (higher array index) represent nodes with higher z-indeces.

indices

{Object} This is a hash that maps node ids to their z-index value stored in the indexer. This is done to make finding a nodes z-index value O(1).

compare

{Function} This is the function used to determine placement of of a new node within the indexer. If null, this defaults to to the Z_ORDER_DRAWING_ORDER comparison method.

Functions

initialize

initialize: function( yOrdering )

Create a new indexer with

Parameters

yOrdering

{Boolean} Whether to use y-ordering.

insert

insert: function( newNode )

Insert a new node into the indexer. In order to find the correct positioning for the node to be inserted, this method uses a binary search. This makes inserting O(log(n)).

Parameters

newNode

{DOMElement} The new node to be inserted.

Returns {DOMElement} the node before which we should insert our newNode, or null if newNode can just be appended.

remove

remove: function( node )

Parameters

node	{DOMElement} The node to be removed.

clear

clear: function()

exists

exists: function( node )

Parameters

node	{DOMElement} The node to test for existence.

Returns

{Boolean} Whether or not the node exists in the indexer?

getZIndex

getZIndex: function( node )

Get the z-index value for the current node from the node data itself.

Parameters

node	{DOMElement} The node whose z-index to get.

Returns

{Integer} The z-index value for the specified node (from the node data itself).

determineZIndex

determineZIndex: function( node )

Determine the z-index for the current node if there isn’t one, and set the maximum value if we’ve found a new maximum.

Parameters

node	{DOMElement}

getNextElement

getNextElement: function( index )

Get the next element in the order stack.

Parameters

index

{Integer} The index of the current node in this.order.

Returns

{DOMElement} the node following the index passed in, or null.

OpenLayers.ElementsIndexer.IndexingMethods

These are the compare methods for figuring out where a new node should be placed within the indexer. These methods are very similar to general sorting methods in that they return -1, 0, and 1 to specify the direction in which new nodes fall in the ordering.

Summary

Functions
Z_ORDER	This compare method is used by other comparison methods.
Z_ORDER_DRAWING_ORDER	This method orders nodes by their z-index, but does so in a way that, if there are other nodes with the same z-index, the newest drawn will be the front most within that z-index.
Z_ORDER_Y_ORDER	This one should really be called Z_ORDER_Y_ORDER_DRAWING_ORDER, as it best describes which ordering methods have precedence (though, the name would be too long).

Functions

Z_ORDER

Z_ORDER: function( indexer,
newNode,
nextNode )

This compare method is used by other comparison methods. It can be used individually for ordering, but is not recommended, because it doesn’t subscribe to drawing order.

Parameters

indexer	{OpenLayers.ElementsIndexer}
newNode	{DOMElement}
nextNode	{DOMElement}

Returns

{Integer}

Z_ORDER_DRAWING_ORDER

Z_ORDER_DRAWING_ORDER: function( indexer,
newNode,
nextNode )

This method orders nodes by their z-index, but does so in a way that, if there are other nodes with the same z-index, the newest drawn will be the front most within that z-index. This is the default indexing method.

Parameters

indexer	{OpenLayers.ElementsIndexer}
newNode	{DOMElement}
nextNode	{DOMElement}

Returns

{Integer}

Z_ORDER_Y_ORDER

Z_ORDER_Y_ORDER: function( indexer,
newNode,
nextNode )

This one should really be called Z_ORDER_Y_ORDER_DRAWING_ORDER, as it best describes which ordering methods have precedence (though, the name would be too long). This method orders nodes by their z-index, but does so in a way that, if there are other nodes with the same z-index, the nodes with the lower y position will be “closer” than those with a higher y position. If two nodes have the exact same y position, however, then this method will revert to using drawing order to decide placement.

Parameters

indexer	{OpenLayers.ElementsIndexer}
newNode	{DOMElement}
nextNode	{DOMElement}

Returns

{Integer}

OpenLayers.Renderer.Elements

This is another virtual class in that it should never be instantiated by itself as a Renderer. It exists because there is tons of shared functionality between different vector libraries which use nodes/elements as a base for rendering vectors.

The highlevel bits of code that are implemented here are the adding and removing of geometries, which is essentially the same for any element-based renderer. The details of creating each node and drawing the paths are of course different, but the machinery is the same.

Inherits

OpenLayers.Renderer

Summary

Properties
rendererRoot	{DOMElement}
root	{DOMElement}
vectorRoot	{DOMElement}
textRoot	{DOMElement}
xmlns	{String}
xOffset	{Number} Offset to apply to the renderer viewport translation in x direction.
rightOfDateLine	{Boolean} Keeps track of the location of the map extent relative to the date line.
Indexer	{<OpenLayers.ElementIndexer>} An instance of OpenLayers.ElementsIndexer created upon initialization if the zIndexing or yOrdering options passed to this renderer’s constructor are set to true.
Constants
BACKGROUND_ID_SUFFIX	{String}
LABEL_ID_SUFFIX	{String}
LABEL_OUTLINE_SUFFIX	{String}
Constructor
OpenLayers.Renderer.Elements
Functions
destroy
clear	Remove all the elements from the root
setExtent	Set the visible part of the layer.
getNodeType	This function is in charge of asking the specific renderer which type of node to create for the given geometry and style.
drawGeometry	Draw the geometry, creating new nodes, setting paths, setting style, setting featureId on the node.
redrawNode
redrawBackgroundNode	Redraws the node using special ‘background’ style properties.
drawGeometryNode	Given a node, draw a geometry on the specified layer.
postDraw	Things that have do be done after the geometry node is appended to its parent node.
drawPoint	Virtual function for drawing Point Geometry.
drawLineString	Virtual function for drawing LineString Geometry.
drawLinearRing	Virtual function for drawing LinearRing Geometry.
drawPolygon	Virtual function for drawing Polygon Geometry.
drawRectangle	Virtual function for drawing Rectangle Geometry.
drawCircle	Virtual function for drawing Circle Geometry.
removeText	Removes a label
getFeatureIdFromEvent
eraseGeometry	Erase a geometry from the renderer.
nodeFactory	Create new node of the specified type, with the (optional) specified id.
nodeTypeCompare
createNode
moveRoot	moves this renderer’s root to a different renderer.
getRenderLayerId	Gets the layer that this renderer’s output appears on.
isComplexSymbol	Determines if a symbol cannot be rendered using drawCircle

Properties

rendererRoot

{DOMElement}

root

{DOMElement}

vectorRoot

{DOMElement}

textRoot

{DOMElement}

xmlns

{String}

xOffset

{Number} Offset to apply to the renderer viewport translation in x direction. If the renderer extent’s center is on the right of the dateline (i.e. exceeds the world bounds), we shift the viewport to the left by one world width. This avoids that features disappear from the map viewport. Because our dateline handling logic in other places ensures that extents crossing the dateline always have a center exceeding the world bounds on the left, we need this offset to make sure that the same is true for the renderer extent in pixel space as well.

rightOfDateLine

{Boolean} Keeps track of the location of the map extent relative to the date line. The setExtent method compares this value (which is the one from the previous setExtent call) with the current position of the map extent relative to the date line and updates the xOffset when the extent has moved from one side of the date line to the other.

Indexer

{<OpenLayers.ElementIndexer>} An instance of OpenLayers.ElementsIndexer created upon initialization if the zIndexing or yOrdering options passed to this renderer’s constructor are set to true.

Constants

BACKGROUND_ID_SUFFIX

{String}

LABEL_ID_SUFFIX

{String}

LABEL_OUTLINE_SUFFIX

{String}

Constructor

OpenLayers.Renderer.Elements

Parameters

containerID	{String}
options	{Object} options for this renderer.

Supported options are

yOrdering	{Boolean} Whether to use y-ordering
zIndexing	{Boolean} Whether to use z-indexing. Will be ignored if yOrdering is set to true.

Functions

destroy

destroy: function()

clear

clear: function()

Remove all the elements from the root

setExtent

setExtent: function( extent,
resolutionChanged )

Set the visible part of the layer.

Parameters

extent	{OpenLayers.Bounds}
resolutionChanged	{Boolean}

Returns

{Boolean} true to notify the layer that the new extent does not exceed the coordinate range, and the features will not need to be redrawn. False otherwise.

getNodeType

getNodeType: function( geometry,
style )

This function is in charge of asking the specific renderer which type of node to create for the given geometry and style. All geometries in an Elements-based renderer consist of one node and some attributes. We have the nodeFactory() function which creates a node for us, but it takes a ‘type’ as input, and that is precisely what this function tells us.

Parameters

geometry	{OpenLayers.Geometry}
style	{Object}

Returns

{String} The corresponding node type for the specified geometry

drawGeometry

drawGeometry: function( geometry,
style,
featureId )

Draw the geometry, creating new nodes, setting paths, setting style, setting featureId on the node. This method should only be called by the renderer itself.

Parameters

geometry	{OpenLayers.Geometry}
style	{Object}
featureId	{String}

Returns

{Boolean} true if the geometry has been drawn completely; null if incomplete; false otherwise

redrawNode

redrawNode: function( id,
geometry,
style,
featureId )

Parameters

id	{String}
geometry	{OpenLayers.Geometry}
style	{Object}
featureId	{String}

Returns

{Boolean} true if the complete geometry could be drawn, null if parts of the geometry could not be drawn, false otherwise

redrawBackgroundNode

redrawBackgroundNode: function( id,
geometry,
style,
featureId )

Redraws the node using special ‘background’ style properties. Basically just calls redrawNode(), but instead of directly using the ‘externalGraphic’, ‘graphicXOffset’, ‘graphicYOffset’, and ‘graphicZIndex’ properties directly from the specified ‘style’ parameter, we create a new style object and set those properties from the corresponding ‘background’-prefixed properties from specified ‘style’ parameter.

Parameters

id	{String}
geometry	{OpenLayers.Geometry}
style	{Object}
featureId	{String}

Returns

{Boolean} true if the complete geometry could be drawn, null if parts of the geometry could not be drawn, false otherwise

drawGeometryNode

drawGeometryNode: function( node,
geometry,
style )

Given a node, draw a geometry on the specified layer. node and geometry are required arguments, style is optional. This method is only called by the render itself.

Parameters

node	{DOMElement}
geometry	{OpenLayers.Geometry}
style	{Object}

Returns

{Object} a hash with properties “node” (the drawn node) and “complete” (null if parts of the geometry could not be drawn, false if nothing could be drawn)

postDraw

postDraw: function( node )

Things that have do be done after the geometry node is appended to its parent node. To be overridden by subclasses.

Parameters

node	{DOMElement}

drawPoint

drawPoint: function( node,
geometry )

Virtual function for drawing Point Geometry. Should be implemented by subclasses. This method is only called by the renderer itself.

Parameters

node	{DOMElement}
geometry	{OpenLayers.Geometry}

Returns

{DOMElement} or false if the renderer could not draw the point

drawLineString

drawLineString: function( node,
geometry )

Virtual function for drawing LineString Geometry. Should be implemented by subclasses. This method is only called by the renderer itself.

Parameters

node	{DOMElement}
geometry	{OpenLayers.Geometry}

Returns

{DOMElement} or null if the renderer could not draw all components of the linestring, or false if nothing could be drawn

drawLinearRing

drawLinearRing: function( node,
geometry )

Virtual function for drawing LinearRing Geometry. Should be implemented by subclasses. This method is only called by the renderer itself.

Parameters

node	{DOMElement}
geometry	{OpenLayers.Geometry}

Returns

{DOMElement} or null if the renderer could not draw all components of the linear ring, or false if nothing could be drawn

drawPolygon

drawPolygon: function( node,
geometry )

Virtual function for drawing Polygon Geometry. Should be implemented by subclasses. This method is only called by the renderer itself.

Parameters

node	{DOMElement}
geometry	{OpenLayers.Geometry}

Returns

{DOMElement} or null if the renderer could not draw all components of the polygon, or false if nothing could be drawn

drawRectangle

drawRectangle: function( node,
geometry )

Virtual function for drawing Rectangle Geometry. Should be implemented by subclasses. This method is only called by the renderer itself.

Parameters

node	{DOMElement}
geometry	{OpenLayers.Geometry}

Returns

{DOMElement} or false if the renderer could not draw the rectangle

drawCircle

drawCircle: function( node,
geometry )

Virtual function for drawing Circle Geometry. Should be implemented by subclasses. This method is only called by the renderer itself.

Parameters

node	{DOMElement}
geometry	{OpenLayers.Geometry}

Returns

{DOMElement} or false if the renderer could not draw the circle

removeText

removeText: function( featureId )

Removes a label

Parameters

featureId

{String}

getFeatureIdFromEvent

getFeatureIdFromEvent: function( evt )

Parameters

evt	{Object} An OpenLayers.Event object

Returns

{String} A feature id or undefined.

eraseGeometry

eraseGeometry: function( geometry,
featureId )

Erase a geometry from the renderer. In the case of a multi-geometry, we cycle through and recurse on ourselves. Otherwise, we look for a node with the geometry.id, destroy its geometry, and remove it from the DOM.

Parameters

geometry	{OpenLayers.Geometry}
featureId	{String}

nodeFactory

nodeFactory: function( id,
type )

Create new node of the specified type, with the (optional) specified id.

If node already exists with same ID and a different type, we remove it and then call ourselves again to recreate it.

Parameters

id	{String}
type	{String} type Kind of node to draw.

Returns

{DOMElement} A new node of the given type and id.

nodeTypeCompare

nodeTypeCompare: function( node,
type )

Parameters

node	{DOMElement}
type	{String} Kind of node

Returns

{Boolean} Whether or not the specified node is of the specified type This function must be overridden by subclasses.

createNode

createNode: function( type,
id )

Parameters

type	{String} Kind of node to draw.
id	{String} Id for node.

Returns

{DOMElement} A new node of the given type and id. This function must be overridden by subclasses.

moveRoot

moveRoot: function( renderer )

moves this renderer’s root to a different renderer.

Parameters

renderer

{OpenLayers.Renderer} target renderer for the moved root

getRenderLayerId

getRenderLayerId: function()

Gets the layer that this renderer’s output appears on. If moveRoot was used, this will be different from the id of the layer containing the features rendered by this renderer.

Returns

{String} the id of the output layer.

isComplexSymbol

isComplexSymbol: function( graphicName )

Determines if a symbol cannot be rendered using drawCircle

Parameters

graphicName

{String}

Returns {Boolean} true if the symbol is complex, false if not