This group of functions allows using element maps maintained by the generator.
What are Element Maps?
If you are going to process data sources with a large number of elements, the element maps may help you to make your templates work a lot faster (or even work them at all).
Suppose, you frequently need to obtain from a large number of elements some collections of them using rather complicated and varying query (which may depend on some external parameters). You may notice that in many instances such a query can be presented actually as a composition of two subqueries:
(Of course, such an approach may cost some memory, but given that during processing of a template some of its components may be implicitly executed a lot number of times, this will pay off and may considerably boost the generator performance.)
The DocFlex generator maintains a table of special hashmaps that associate keys with certain collections of elements. Those hashmaps called elemeny maps can be created and accessed within FlexQuery expressions in templates.
Each element map is identified by a certain object called elementMapId
.
That identifier is specified when the element map is created
and, then, should be used as a parameter with any function accessing it.
The generator maintains the whole element map table as yet another hashmap,
so each elementMapId
object is used as a map key in it and,
therefore, should comply with what is needed to be a good hash key.
See description for createElementMap()
function
for more details about that.
Each element map contains certain keys and the elements associated with those key.
The elements are the DSM (Data Source Model) elements represented by
GOMElement
objects. The elements are distinguished by their unique identifiers
(see GOMElement.id
), so different GOMElement
instances are considered
to represent the same element as long as their id
are equal.
The map keys may be any objects good to be hash keys.
Each element map represents a certain relation between keys and elements. The same element may be associated with different keys in the map as well as any key may have multiple elements associated with it.
Working with Element Maps
The following is the summary of the functions working with element maps:
createElementMap()
Creates a new element map with the specified identifier.
createElementMaps()
Creates a number of element maps with the specified identifiers.
checkElementMap()
Tests if an element map with the specified identifier exists and may return other information about the element map.
removeElementMap()
Removes the element map with the specified identifier.
putElementByKey()
Associates the specified element with the specified key in the element map with the specified identifier.
putElementByKeys()
Associates the specified element with a number of specified keys in the element map with the specified identifier.
putElementsByKey()
Associates a number of different elements with the same specified key in the element map with the specified identifier.
putElementsByKeys()
Adds a number of key/element associations to the element map with the specified identifier.
prepareElementMap()
This function combines the functionality ofcheckElementMap()
,createElementMap()
andputElementsByKeys()
functions at once.It tests if the element map with the specified identifier exists. If yes, the function does nothing and just returns the number of key/element associations contained in the map.
If the element map does not exist, the function creates it and fill with the key/element associations the same way as
putElementsByKeys()
function.
findElementByKey()
Returns an element that is associated with the given key in the element map with the specified identifier and satisfies the filter condition (if specified). If there are many such elements, the first one is returned.
findElementsByKey()
Returns all elements that are associated with the given key in the element map with the specified identifier and satisfy the filter condition (if specified).
findElementsByKeys()
Returns all elements that are associated with at least one of the given keys in the element map with the specified identifier and satisfy the filter condition (if specified).
checkElementsByKey()
Checks if the element map with the specified identifier contains elements associated with the given key.
checkElementsByKeys()
Checks if the element map with the specified identifier contains elements associated with at least one of the given keys.
countElementsByKey()
Counts all elements that are associated with the given key in the element map with the specified identifier and satisfy the filter condition (if specified).
countElementsByKeys()
Counts all elements that are associated with at least one of the given keys in the element map with the specified identifier and satisfy the filter condition (if specified).
countMappedElements()
Counts all elements contained in the specified element map.
getMappedElements()
Returns all elements contained in the specified element map.
getElementMapKeys()
Returns all keys contained in the specified element map.
${include ../../../refs/element_map_example.htm}