IMapper Interface

A Mapper is the primary means of mapping object-oriented programming objects to data sources managed by relational databases or other sources of data. A Mapper provides 2-way (Read and Write) access to the underlying Data Source.

Among the most important aspects of a mapper are:

A mapper contains a collection of IField objects in its Fields collection.
A set of MapperAttrs provide high-level control over mapper behaviour.
A mapper fires ExtensionEvents to MapperExtensionKernel extensions in its Extensions collection in descending Priority order.
A mapper provides for record movement via methods such as MoveNext and MoveNew.
A mapper accesses its data source using an IDatabase object.
A mapper is used to perform CRUD operations using Save to insert/update records and Delete to delete records.
The mapper's Exec(MapperExecCmds, Int32, Object) method exposes additional functionality via MapperExecCmds.

There are several implementations of mappers that implement this interface and all of which derive from MapperKernel which implements all the common functionality:

Mapper - Basic mapper intended for programmatic use (with no UI).
MapperList - Basic list mapper intended for programmatic use (with no UI).
MapperDetail - Standard editable single-item detail UI mapper.
MapperDatasheet - Standard list UI mapper.

In most cases you will want a TypedMapper for each mapper manipulated programmatically. A TypedMapper provides a type-safe implementation of a mapper based on its meta-data.

Remarks

By default a mapper is forward-only and uses an ADO DataReader for efficent cursor-based access to large sets of data. Set the BiDirectional attribute to cause the mapper to read the queried data into an internal DataTable and provide forward and backward movement.

Remarks

Typically a mapper query is performed against a table or view, however, it is possible to configure a mapper to use a Stored Procedure as the source for its data by setting the mapper's QuerySQL property. When specified, QuerySQL will override the mapper's View (which, though ignored, must still be specified) when the mapper queries for its data during Requery(RequeryHints). A typical Stored Procedure QuerySQL looks like:

spMyData [[PREFILTER]], [[FILTER]], [[OPTIONS]], [[SORT]], [[TOPN]], <params>.

Stored Procedure parameters may be passed in any order, are resolved for embedded functions using the EmbeddedParser, and may optionally include any or all of these predefined parameter markers that will be replaced by the mapper when the Stored Procedure is called. Note that all markers are case-sensitive.

[[PREFILTER]] - The SQL WHERE clause (without "WHERE"), constructed by the mapper, to be applied to the intermediate Stored Procedure result. Only those MapperFilter items in the mapper's MapperFilters collection marked with PreFilter will be included in this clause. Typically a MapperFilter is marked as PreFilter because is was generated from a IField marked as PreFilter (e.g. from the FBF). This should be a string type (e.g. nvarchar) with a minimum sugested length of 2000 characters, or better yet, unlimited length (e.g. nvarchar(max)).
[[FILTER]] - The SQL WHERE clause (without "WHERE"), constructed by the mapper, to be applied to the final Stored Procedure result. Only those MapperFilter items in the mapper's MapperFilters collection not marked with PreFilter will be included in this clause. This should be a string type (e.g. nvarchar) with a minimum sugested length of 2000 characters, or better yet, unlimited length (e.g. nvarchar(max)).
[[OPTIONS]] - Options from QuerySqlOptions telling the Stored Procedure what kind of data to return. This is an int type.
[[SORT]] - The SQL ORDER BY clause (without "ORDER BY") constructed by the mapper. This should be a string type (e.g. nvarchar) with a minimum sugested length of 200 characters, or better yet, unlimited length (e.g. nvarchar(max)).
[[TOPN]] - The TOP(N) value specifying that only the first N records should be returned or -1 if no limit. This is an int type.

Namespace: NetQuarry.Data
Assembly: EAP.Core (in EAP.Core.dll) Version: 2.0.0.0 (4.6.8.0)

Syntax

Copy

public interface IMapper : IDisposable

Public Interface IMapper
	Inherits IDisposable

The IMapper type exposes the following members.

Properties

	Name	Description
	Application	The platform IAppContext context object. The Application is set in the Init(String, IAppContext) method.
	Attributes	MapperAttrs flags specifying various behaviour of the mapper. This is normally loaded from meta-data during Load.
	Caption	The localized caption for the mapper. Call Exec(MapperExecCmds, Int32, Object) with the Caption command to get a caption that includes additional information including current paging and filtering for a live mapper.
	Commands	Mapper commands are used to add custom MapperCommand commands to a mapper's page. Typically commands are added to the toolbar or the More (Actions) button on the toolbar. When invoked, a MapperCommand(IMapper, EAPCommandEventArgs) event is fired on the mapper. You can add commands to the mapper programmatically, typically during the MapperBeforeLayout(IMapper, EAPEventArgs) event. Commands are also added automatically from meta-data NavTarget elements with TargetType of Command on Navigator elements configured in meta-data for use on the page, page element, or mapper.
	CssClass	The Cascading Style Sheet class to use for the mapper.
	CurrentPage	The 1-based current page index for the mapper. In mappers other than datasheets, the RecordsPerPage is generally one so the CurrentPage is the same as the CurrentRecord.
	CurrentRecord	The 1-based index of the current record in the mapper.
	Database	The data IDatabase used by the mapper. The data database holds the mapper's operational data.
	DeleteLocked	Specifies whether or not the row should be allowed to be deleted for the current row only. This property is cleared by the mapper immediately prior to the RowCurrent event. An extension can then set the property to true to prevent this row from being deleted. The mapper also supports a DeleteLockExpression property allowing the delete lock condition to be specified in meta-data. The DeleteLockExpression is a javascript expression, typically including field references, that is evaluated with each row to initialize its DeleteLocked value. For row-level record locking, see RowLocked.
	Dirty	The dirty property can be read to determine if any of the mapper's fields values have been changed since being populated from the database or original datatable. The property can be cleared to clear the dirty flags on all the mapper's fields. If set true, the mapper's internal dirty flag is set, but the mapper's fields are not set dirty.
	Extensions	Gets the collection of IExtension mapper extension objects for the mapper. Extensions provide both additional standard and custom functionality. Mapper extensions are the primary means by which custom functionality is added to the application. Generally extensions used across multiple mappers derive from the MapperExtensionKernel class whereas those that are intended for use on a single mapper derive from an application-specific generated class derived from the TypedMapperExtension template class. Extensions derived from TypedMapperExtension can only be used on the intended mapper, but provide a type-safe, easier to use implementation. These are the most common type of extension in most applications. The more primitive, but flexible MapperExtensionKernel-derived extension are typically used for non-mapper specific functionality such as in the ReadableAudit extension. Virtually all platform-provided extensions are of this type.
	Fields	The Fields collection of IField objects which generally corresponding to columns in the underlying table or view. IField's are rich objects which can be configured in meta-data and manipulated programmatically.
	Filters	The collection of MapperFilter objects used to filter the mapper queries. Filters can be specified in meta-data and manipulated programmatically. Standard datasheet filtering is handled by the MapperDatasheet object.
	Flavor	Flavor is used to include or exclude certain fields based on their IncludeFlavor and ExcludeFlavor bits. Fields that are excluded are not hidden; they are never loaded into the mapper's Fields collection. A flavor of zero indicates that all fields with any IncludeFlavor bits set will not be loaded. If a field is marked as both included and excluded for a particular Flavor then the exclude bit is favored.
	HasMorePages	Returns true if there are additional pages beyond the current page. This should be used (possibly in conjunction with HasRecords) instead of calling RecordCount in order to manage UI paging.
	HasRecords	HasRecords returns true if there are one or more records in the current mapper filter, else false. Note that using HasRecords never requires an additional database query and should therefore be used in place of RecordCount when possible.
	IgnorePostback	Indicates whether postback data is being used or ignored.
	IsDesignMode	Returns true if the control is in Design mode.
	IsNew	Indicates whether or not the mapper is positioned on a new row.
	Key	Gets the key (ID) of the mapper. This is the meta-data's unique identifier for the mapper definition.
	Mode	Mapper mode specifies how the mapper is being used and controls the overall look and behaviour of the mapper.
	ModuleKey	The key to the module using this mapper -- typically obtained from Module. Note that this may be misleading on Console and Wizard pages. To obtain the module for the mapper itself use MapperModuleKey.
	MOP	The MOP using this mapper. A MOP is a Module-Page of the form <module>!<page>.
	OrderBy	A SQL ORDER BY clause used as the default sort for the mapper. User sorting in a datasheet supercedes this clause.
	Page	The .Net Page holding this mapper.
	PageInfo	The PageInfo object related to this mapper. This is a reference to the session's PageInfo object. Note that since this is a copy of the session's PageInfo object, you should not modify this instance of the PageInfo object. If you want to modify the PageInfo object for this mapper instance only then you should clone the PageInfo object using Clone(IAppContext) and set it back on the mapper as in the example below: Examples Copy PageInfo info = mapper.PageInfo.Clone(cxt); info.TextItems.Add("Caption", "My Caption"); mapper.PageInfo = info;
	PageNm	The name of the Page using this mapper -- typically obtained from Name.
	ParentContext	Gets RelatedMapperContext information about this mapper's parent mapper including, if requested, a filtered instance of the parent. Typically the parent mapper is determined from the request's QueryString.
	Properties	The mapper's Properties collection. Properties can be specified in meta-data using the mapper's property sheet, or programmatically. Properties are used to specify many aspects of mapper appearance and behaviour.
	Purpose	Purpose is used to identify the purpose to which the live mapper object is currently being put. Note that Purpose can be set to custom values by an application depending on how the mapper is being used, but constants for a standard set of purposes can be found in MapperPurposes.
	RecordCount	Returns the number of records in the current filter. Note that this number is not limited by paging. For example, if on a datasheet displaying the first 10 records out of 53 records matching the filter, RecordCount will return 53. Note that calling RecordCount may require an additional database query and should be avoided when possible. If the intent is to determine if there are zero vs. one or more records use HasRecords instead which never requires an additional query. Note that you can use RecordCountSafe to obtain the record count without the possibility of an error being thrown.
	RecordsPerPage	The number of records per page in the mapper. In mappers other than datasheets this is generally 1.
	Repository	The repository IDatabase used by the mapper. The repository holds the mapper's meta-data.
	RowKey	A key uniquely identifying the current row. In the case of multiple keys, this will be a combined key. This key can be passed to RowKeyFilter(String) to generate a filter for the record from which the key was obtained.
	RowLocked	Specifies whether or not the row should be locked for the current row only. This property is cleared by the mapper immediately prior to the RowCurrent event. An extension can then set the property to true to lock this row only. To perform row locking on some, but not all, the fields in a row, set the RowLocked property for the appropriate fields instead of the mapper-level row lock, or set the mapper-level RowLocked and set the field's IgnoreRowLock property in the fields' meta-data. Note that a field will be locked for all the static reasons (e.g. if the Locked attribute is set), or if the field is row-locked, or if the mapper is row-locked and the field's IgnoreRowLock property is not set. Note that the IgnoreRowLock property applies only to mapper-level row locking and has no impact on field-level row locking. The mapper also supports a RowLockExpression property allowing the row lock condition to be specified in meta-data. The RowLockExpression is a javascript expression, typically including field references, that is evaluated with each row to initialize its RowLocked value. For row-level delete locking, see DeleteLocked.
	TextItems	The mapper's localized TextItem collection. For a particular instance of a mapper only the locale (language) for the current user is loaded.
	View	The name of the mapper's underlying view or table. This is normally loaded from meta-data during IMapper.Load(). Note that the View is used in the mapper's operational query and count SELECT statements, but is not used for INSERT, UPDATE, or DELETE operations. All INSERT, UPDATE, and DELETE operations are performed against the fields' underlying tables based on each field's Table property. Although the View is required, you can configure the mapper to used a Stored Procedure instead of the view by specifying the QuerySQL property. If the QuerySQL property is specified, the View will be ignored (but the Studio will still require it. Note that View can be overridden on a page-by-page basis using a page's PageView property.
	ViewState	The ViewState for the current page. Used to maintain filter and sort state across postbacks.

Top

Methods

	Name	Description
	BindPage(Page, Boolean)	Binds the mapper to the current .Net Page.
	BindPage(Page, Control, Boolean)	Binds the mapper to the current .Net Page.
	BindPage(Page, Control, Boolean, MapperBindFlags)	Binds the mapper to the current .Net Page.
	BulkDeleteBegin	Initiate a bulk delete using the mapper and fire its corresponding extension event. The object controlling the bulk operation typically makes this call before performing the delete operations in a loop using the same mapper instance. The bulkContext will be provided in the BulkContext parameter for all mapper events performed during the bulk operation. If a null bulkContext object is provided, the method will instantiate one for you. If you want a custom bulkContext, you should derive from the base EventBulkContext object and provide an instance of your derived class. If BulkDeleteBegin is called, you should call BulkDeleteEnd when the operation completes. Note that the MapperBulkBeforeDelete event is fired from within this method.
	BulkDeleteEnd	Complete a bulk delete operation that was initiated with a call to BulkDeleteBegin(EventBulkContext). This method will delete the mapper's internal bulk context object set by that call. This method should be called if, and only if, BulkDeleteBegin was called. Note that the MapperBulkAfterDelete event is fired from within this method.
	BulkInsertBegin	Initiate a bulk insert using the mapper and fire its corresponding extension event. The object controlling the bulk operation typically makes this call before performing the insert operations in a loop using the same mapper instance. The bulkContext will be provided in the BulkContext parameter for all mapper events performed during the bulk operation. If a null bulkContext object is provided, the method will instantiate one for you. If you want a custom bulkContext, you should derive from the base EventBulkContext object and provide an instance of your derived class. If BulkInsertBegin is called, you should call BulkInsertEnd when the operation completes.
	BulkInsertEnd	Complete a bulk insert operation that was initiated with a call to BulkInsertBegin(EventBulkContext). This method will delete the mapper's internal bulk context object set by that call. This method should be called if, and only if, BulkInsertBegin was called.
	BulkUpdateBegin	Initiate a bulk update using the mapper and fire its corresponding extension event. The object controlling the bulk operation typically makes this call before performing the update operations in a loop using the same mapper instance. The bulkContext will be provided in the BulkContext parameter for all mapper events performed during the bulk operation. If a null bulkContext object is provided, the method will instantiate one for you. If you want a custom bulkContext, you should derive from the base EventBulkContext object and provide an instance of your derived class. If BulkUpdateBegin is called, you should call BulkUpdateEnd when the operation completes.
	BulkUpdateEnd	Complete a bulk update operation that was initiated with a call to BulkUpdateBegin(EventBulkContext). This method will delete the mapper's internal bulk context object set by that call. This method should be called if, and only if, BulkUpdateBegin was called.
	Clone(IMapper, MapperCloneFlags)	Create a clone of the mapper. Unless otherwise specified by modifier flags, the clone will be requeried using the same filters and sort as the original mapper.
	Clone(IMapper, MapperCloneFlags, Flavors)	Create a clone of the mapper. Unless otherwise specified by modifier flags, the clone will be requeried using the same filters and sort as the original mapper.
	Close	Closes all internal resources
	Delete	Delete the current record. Note that, following the delete and all associated mapper events, the mapper will perform a MoveNext to position to the next record in the filter. Because of this, when deleting multiple records you should not perform a MoveNext except on those rows you do not intend to delete. See also DeleteAll to delete all records in the filter.
	DeleteAll	Delete all records in the current filter. DeleteAll is a bulk operation and as such will fire the MapperBulkBeforeDelete and MapperBulkAfterDelete events. Typically at the start of DeleteAll processing an EventBulkContext is established, however, you may establish a custom bulk context by calling BulkDeleteBegin(EventBulkContext) immediately prior to calling DeleteAll.
	Dispose	Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources. (Inherited from IDisposable.)
	DoCommand	Execute the specified command. Typically commandName is the ID of one of the MapperCommand items added to the mapper's Commands collection. To invoke a command by its Command, pass a 1 in the flags parameter.
	Exec(MapperExecCmds, Enum, Object)	The Exec method provide extended functionality for mappers. See MapperExecCmds for the enumerated list of commands.
	Exec(MapperExecCmds, Int32, Object)	The Exec method provide extended functionality for mappers. See MapperExecCmds for the enumerated list of commands.
	FireEvent	FireEvent is called by the owner to fire an event to the mapper's extensions.
	GetFieldList	Gets a semi-colon separated list of fields to render for this mapper based on various PageElementInfo properties including FieldList, FieldListMobile, and GroupList, or on a value set programmatically via SetFieldList(String, SetFieldListOpts). Also handles the HiddenFields property when HiddenFields is specified. Note that the possibililty of HiddenFields complicates construction of a field list and typically requires calling this method first to get a possible list of explicitly shown fields (where no such list means to show all fields normally visible in the mapper) then calling the method again to get a possible list of explicitly hidden fields and combining the results (including handling the case where fields are explicitly hidden, but not explicitly shown).
	HandleRequest	Handle a specific HTTP request.
	HasPermission	Determines if the mapper has the specified ObjectPermissions for the current user. If the object has no assigned permisions, the return value is true.
	Init(String, IAppContext)	This method initializes the mapper.
	Init(String, IAppContext, Page)	This method initializes the mapper.
	Init(String, IAppContext, Page, PageInfo)	This method initializes the mapper.
	IsAttrSet	Determines if a particular attribute (or any of a set of attributes) is set. Note that this is a shorthand for the expression (0 != (mapper.Attributes & attributes)) (C#) or (0 <> (mapper.Attributes Or attributes)) (VB).
	IsConfiguredFor	Determines if the mapper is currently configured for the specified MapperCapabilities.
	Load	Loads the mapper's meta-data from the Repository IDatabase. Use Load(MapperLoadFlags) to load the mapper with specific load options.
	Load(MapperLoadFlags)	Loads the mapper's meta-data from the Repository IDatabase.
	Load(DataTable, MapperLoadFlags)	Sets up the mapper's meta-data per the table's schema. If so specified the mapper will use the table's data.
	MoveBOF	Move to the Beginning Of File (BOF). That is, position the cursor just prior to the first record in the mapper. Note that this will throw an InvalidMapperMovement error if the mapper is positioned on or beyond the first record and is not BiDirectional. Use MoveFirst to position directly to the first data row.
	MoveFirst	Move to the first record in the mapper. Note that this will throw an InvalidMapperMovement error if the mapper is positioned beyond the first record and is not BiDirectional. Use MoveBOF to position just prior to the first data row. You should not call MoveFirst prior to calling MoveNext to loop through records in a mapper as this will result in the first record being skipped (unless of course you want to skip the first record). Immediately following a Requery(RequeryHints) the mapper will already be positioned BOF and you can simply loop by calling MoveNext. If you are using a BiDirectional mapper and need to perform subsequent MoveNext loops, call MoveBOF to position just prior to the first data row before starting each subsequent MoveNext.
	MoveLast	Move to the last record in the mapper.
	MoveNew	Move to a new record.
	MoveNew(Boolean)	Move to a new record.
	MoveNext	Move to the next record in the mapper. You should not call MoveFirst prior to calling MoveNext to loop through records in a mapper as this will result in the first record being skipped (unless of course you want to skip the first record). Immediately following a Requery(RequeryHints) the mapper will already be positioned BOF and you can simply loop by calling MoveNext. If you are using a BiDirectional mapper and need to perform subsequent MoveNext loops, call MoveBOF to position just prior to the first data row before starting each subsequent MoveNext.
	MovePrev	Move to the previous record in the mapper. Note that this will throw an InvalidMapperMovement error if the mapper is not BiDirectional.
	MoveRelative(Int32, Boolean)	Move to a record relative to the current record. Note that this will throw an InvalidMapperMovement error if movement is negative and the mapper is not BiDirectional.
	MoveRelative(Int32, Boolean, MoveReason)	Move to a record relative to the current record. Note that this will throw an InvalidMapperMovement error if movement is negative and the mapper is not BiDirectional.
	MoveTo(Int32)	Move to the specified row number (1-based). Note that RowCurrent events are NOT fired and data is NOT moved through the mapper's Fields during the move. In general you should use this method to position the mapper to the record immeditately PRIOR to the first record of interest and then use MoveNext to iterate through one or more records of interest. Remarks Note that this will throw an InvalidMapperMovement exception if the mapper is positioned beyond the specified record and is not BiDirectional. Examples For example, to implement a page size of 10 records and read data for the 2nd page, you would first call mapper.MoveTo(10); to position to the 10th row (the last row of page 1) then iteratively call mapper.MoveNext(); until you have read 10 records (11 through 20) or until mapper.MoveNext();MoveNext() returns false indicating that there are no more records.
	MoveTo(String)	Move to the row corresponding to the specified RowKey.
	Permissions	Gets the ObjectPermissions for the mapper.
	Requery	Opens the operational data reader, or fills the internal DataTable, for the mapper.
	ResolveSortSpec	Resolve a !Sort() expression into its constituent parts.
	RowDigest	Generate a digest of the field values in the mapper for the current row.
	RowKeyFilter	RowKeyFilter is used to build a filter unique for a RowKey obtained from the RowKey property.
	Save	Save the current changes. If no fields are Dirty, no save is performed. You can use the Save(MapperSaveOptions) to override certain standard Save behaviour, the standard behaviour is typically recommended. See Save(MapperSaveOptions) for some additional information about mapper saves.
	Save(MapperSaveOptions)	Save the current changes allowing for specific MapperSaveOptions options. If no fields are Dirty, no save is performed. Saves are typically performed using the Save method with default mapper Save behaviour.
	SelectedKeys	SelectedKeys is used to obtain a list of the RowKeys for the rows currently selected in the mapper. In a detail this is the current row. In a datasheet this is the set of selected rows.
	SelectedKeys(EAPEventArgs)	SelectedKeys is used to obtain a list of the RowKeys for the rows currently selected in the mapper. In a detail this is the current row. In a datasheet this is the set of selected rows. If an EAPEventArgs object is provided from a particular mapper event that can specify one or more RowKeys, e.g. EAPCommandEventArgs.RowKey and one or more RowKeys are specified in that object, then the RowKey(s) from the event will be returned.
	Send(String, String)	Simple way to send a message using this mapper and a Template. The mapper sets up the message, the relationships, and creates the template data appropriate from the current row before sending.
	Send(String, String, NameValueCollection)	Simple way to send a message using this mapper and a Template. The mapper sets up the message, the relationships, and creates the template data appropriate from the current row before sending.
	Send(String, String, NameValueCollection, MessageRelationships)	Simple way to send a message using this mapper and a Template. The mapper sets up the message, the relationships, and creates the template data appropriate from the current row before sending.
	SetFieldList	Sets the semi-colon separated list of fields to render for this mapper. Setting this value programmatically overrides any meta-data specified list. See GetFieldList(GetFieldListOpts).
	Signature	Generates a signature string for the mapper as currently filtered and sorted.

Top

Extension Methods

	Name	Description
	GetPageElement	Gets the PageElementInfo for the IMapper, if available. Note that this is simply a wrapper around the GetPageElement command. (Defined by MapperUtils.)
	IsPageElement	Determines if the IMapper is being rendered for the specified MOP and Name of the PageElementInfo. This method is safe to use even if the mapper is null, has no MOP, and/or has no PageElementInfo associated. (Defined by MapperUtils.)
	ResolveExpression	Resolve the specified field expression using ExpressionResolve mapper command. See ExpressionParser for more information about field expressions. Use ExpressionEscape to escape apparent field references in a string. Note that although, for historical reasons, the ExpressionResolve command will throw an error if the expression contains an unresolvable field or other syntax error, this method DOES NOT throw by default because it adds the DoNotThrow flag UNLESS the ThrowOnAnomaly flag is set. (Defined by MapperUtils.)

Top

Reference

NetQuarry.Data Namespace