LassoScript Utility
Basics Browse Detail

[Records_Map]

Tag Link [Records_Map] Category Results
Type Substitution Source Available Yes
Support Preferred Version 8.5
Change New Data Source Any
Output Type Map Security None
Implementation Sets Lasso 8.5

Description

[Records_Map] returns a map of maps which contain all of the results from an inline. This tag is comparable to the [Records_Array] tag, but makes it easier to extract records based on their key field value or field names.

For example, results from the [Records_Map] tag for a Contacts.People table might be represented as follows. The keys for the outer map are the key field values for each record from the table. The keys for the inner map are the field names for each record in the found set.

[Map: '1' = (Map: 'First'='John', 'Last'='Doe', 'Age'='25'),
'2' = (Map: 'First'='Jane', 'Last'='Doe', 'Age'='26')]

By default the current key field name is used to determine the key field values. If a -KeyField parameter is specified for the [Records_Map] tag then the values for that field are used instead. If no key field can be determined then a field named ID or the first field from the results is used.

The fields in the [Records_Map] can be pared down using -ReturnField parameters. If one or more -ReturnField parameters are specified then only those fields will be included in the inner maps. In addition, an -ExcludeField parameter can be used to knock only certain fields out of a [Records_Map].

The field names for the [Records_Map] are drawn from the values returned by the [Field_Names] tag. Alternate field names can be used by specifying a -Fields parameter with an array value. Note that -ReturnField, -ExcludeField, and -KeyField should all refer to the new names rather than the original names of the fields.

The order of records is not normally preserved by the [Records_Map] tag since the order of elements in a map is not defined. If the order of records is important then -Type='array' can be used to switch the outer type to an array. This array will contain pairs that correspond to the map entries from the default option.

Syntax

[Inline: -Search, -Database='Contacts', -Table='People', -KeyField='ID', -MaxRecords='all']
[Records_Map]
[/Inline]

[Inline: -Search, -Database='Contacts', -Table='People', -KeyField='ID', -MaxRecords='all']
[Records_Map: -KeyField='Last_Name']
[/Inline]

[Inline: -Search, -Database='Contacts', -Table='People', -KeyField='ID', -MaxRecords='all']
[Records_Map: -ReturnField='First_Name', -ReturnField='Last_Name']
[/Inline]

[Inline: -Search, -Database='Contacts', -Table='People', -KeyField='ID', -MaxRecords='all']
[Records_Map: -ExcludeField='ID']
[/Inline]

[Inline: -Search, -Database='Contacts', -Table='People', -KeyField='ID', -MaxRecords='all']
[Records_Map: -Fields=(Array: 'ID', 'First', 'Last')]
[/Inline]

Parameters

Optional Parameters
-KeyField The name of the field to use as the key for the outer map. Defaults to the current [KeyField_Name], "ID", or the first field of the database results.
-ReturnField Specifies a field name that should be included in the inner map. Should be called multiple times to include multiple fields. If no -ReturnField is specified then all fields will be returned.
-ExcludeField The name of a field to exclude from the inner map. If no -excludeField is specified then all fields will be returned.
-Fields An array of field names to use for the inner map. By default the value for [Field_Names] will be used.
-Type By default the tag returns a map of maps. By specifying -Type='array' the tag will instead return an array of maps. This can be useful when the order of records is important.

Examples

See the Lasso 8 Language Guide for examples of how to use this tag.