Click or drag to resize

MapperExtensionKernel Class

The base class for an IMapper extension used to handle mapper ExtensionEvents. Type-safe extension can be created using the TypedMapperExtensionT generic base class. As with all extensions and extension base classes, the class implements the IExtension interface and responds to ExtensionEvents. For each mapper event a virtual method is provided that your extension can override to handle the event. Note that all the base implementations are empty so there is never a need to call the base class method. That is, for example, your override of RowBeforeInsert(IMapper, EAPEventArgs) never needs to call this class's RowBeforeInsert(IMapper, EAPEventArgs). However, if you override the HandleEvent(ExtensionEvents, Object, EAPEventArgs) method you must call the base class method if you don't handle the event.

In addition to the dedicated mapper event virtual methods (e.g. RowCurrent(IMapper, EAPEventArgs)), there are virtual methods you can override for other events: Custom(Object, EAPCustomEventArgs) for custom events, and Other(Object, EAPEventArgs) for other, unexpected events.

The general sequence of events for rendering a mapper is:
The general sequence of events for saving a mapper is:
Inheritance Hierarchy

Namespace:  NetQuarry.Data
Assembly:  EAP.Mapper (in EAP.Mapper.dll) Version: (
public class MapperExtensionKernel : MapperExtensionBase

The MapperExtensionKernel type exposes the following members.

Public methodMapperExtensionKernel
Initializes a new instance of this object.
Public propertyApplication
Returns the application object (from IMapper.Application)
(Inherited from MapperExtensionBase.)
Public propertyDatabase
Returns the main database object (from IMapper.Database)
(Inherited from MapperExtensionBase.)
Protected propertyIsPlatform
Gets whether or not the extension is a platform extension vs. a custom extension.
(Inherited from MapperExtensionBase.)
Public propertyMapper
Returns the Mapper object that this extension is attached to.
(Inherited from MapperExtensionBase.)
Protected propertyMapperCommandsHandled
Gets the semi-colon separated list of MapperCommands handled by this extension.
(Inherited from MapperExtensionBase.)
Public propertyParentKeyValue
Gets the request's parent record's row key value under most circumstances including: datasheets, subforms, popup new forms, and datasheet drilldowns.
(Inherited from MapperExtensionBase.)
Public propertyProperties
Returns this instance's properties.
(Inherited from MapperExtensionBase.)
Public propertyCode exampleTextItems
Returns a collection of TextItems loaded from metadata related to this component.
(Inherited from MapperExtensionBase.)
Public methodAuditDelete
Fired when the mapper has performed a delete operation and any auditing should be performed in response to this event.
Public methodAuditExport
Fired when an application wants to log a custom audit message to the audit export table.
Public methodAuditInsert
Fired when the mapper has performed an insert operation and any auditing should be performed in response to this event.
Public methodAuditMessage
Fired when an application wants to log a custom message to the audit trail table.
Public methodAuditUpdate
Fired when the mapper has performed an update operation and any auditing should be performed in response to this event.
Public methodCustom
An event in the range of CustomStart and CustomEnd has been fired.
Public methodEquals
Determines whether the specified Object is equal to the current Object.
(Inherited from Object.)
Protected methodExtensionCommand
Handle extension commands.
(Inherited from MapperExtensionBase.)
Public methodFieldAjaxSave
Fired when a new field value has been sent back via an AJAX call. Detailed save information is provided in the FieldAjaxSaveEventArgs parameter.
Public methodFieldAnomaly
Fired when a field anomaly has been detected. Detailed anomaly information is provided in the FieldAnomalyArgs parameter (which includes the FieldAnomaly) .
Public methodFieldBuildFilter
Fired when the field has been asked to build a filter on itself. This event provides an opportunity for an extension to create a custom filter. Detailed filter information is provided in the BuildFilterArgs parameter.
Public methodCode exampleFieldButtonClick
Fired when the field's button has been clicked. A button click event is supported in both the detail and datasheet versions of the mapper. Note that when the FieldButtonClick event is received, the mapper will already have been positioned to the record on which the click was performed. In the case of a FieldButtonClick on a datasheet, the original list mapper is cloned, the cloned positioned to the appropriate record, and the event fired on the clone.
The following FieldButtonClick handler demonstrates how to return an error from an event and execute a SQL statement to update a table.
public override void FieldButtonClick(IField sender, EAPEventArgs e)
    if (sender.Key == "btn_enable")
        IField fldID = sender.Fields["dealer_id"];
        IField fldDealershipID = sender.Fields["dealership_id"];
        string dealerID = EAPUtil.ToString(fldID.Value);
        string sql = string.Format("UPDATE dealer SET status_id = 1 WHERE dealer_id = '{0}'", dealerID);

        if (0 == EAPUtil.ToString(fldDealershipID.Value).Length)
            e.Error("You must select a dealership for this dealer before they can be enabled.");

In general, if the handler wants to take advantage of the FieldButtonClickArgs object, it should test the type of the e parameter before attempting to use it since that arg type is not provided in all cases. For exampe:

FieldButtonClickArgs args = e as FieldButtonClickArgs;

if (args != null)
    args.Message = "The message!";
Public methodFieldConfirm
Fired when an action occurs on a field that requires confirmation and the field has been configured to use a FieldConfirm event. Detailed request information, though typically not needed, is provided in the FieldConfirmArgs parameter. The handler should configure the FieldConfirmArgs.MessagePopResponse as desired.
Public methodFieldCreateControl
Fired when a field with CellType of Dynamic needs to create a WebControl (typically for use in a detail page or editable datasheet). In response the exension should specify the CellTypes and/or WebControl to use. The CellTypes is set by calling SetCellType(CellTypes, Int32) and the WebControl is set via BaseControl. If only the CellTypes is set then the field will perform normal control creation and configuration for that CellTypes. If a live WebControl object is provided via BaseControl then that control will be used and it is the extension's obligation to perform most set up. See CreateControlArgs for additional information about how to respond to this event.
Public methodFieldTest
Fired when the field should execute it's self-test.
Public methodFileDownload
Fired when a file is about to be downloaded.
Protected methodFinalize
Allows an Object to attempt to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection.
(Inherited from Object.)
Public methodGetHashCode
Serves as a hash function for a particular type.
(Inherited from Object.)
Protected methodGetText
Get the specified localized text for this mapper. Obtaining the text is a four step process: 1) Look for the text item in the mapper's TextItems collection, 2) if not found, look for the item in the extension's TextItems collection, 3) if not found, look for the item in the locale resource file, 4) if not found, use the provided defaultText.
(Inherited from MapperExtensionBase.)
Public methodGetType
Gets the Type of the current instance.
(Inherited from Object.)
Protected methodHandleEvent
IExtension.OnEvent handler. Note that generally speaking, you will want to override the individual methods specific to the event and not implement the interface directly.
(Overrides MapperExtensionBaseHandleEvent(ExtensionEvents, Object, EAPEventArgs).)
Public methodInfo
Return requested information about the extension.
(Inherited from MapperExtensionBase.)
Public methodMailAfterSend
Fired when mail has been successfully sent to the recipient represented by the current row in the mapper.
Public methodMailBeforeSend
Fired when mail is about to be sent to the recipient represented by the current row in the mapper.
Public methodMapperAfterLayout
Fired when the mapper has just layed out the mapper's UI.
Public methodMapperAfterLoad
Fired when the mapper's meta-data has been loaded, fields created, etc, but no field controls created. This is typically the only opportunity to alter field CellType programmatically for fields not specified as Dynamic. Immediately after this event is fired, the mapper fires the ApplicationMapperLoad event to provide the Application with an opportunity to "hook" the mapper.
Public methodMapperAfterRequery
Fired when the mapper has just requeried its operational data.
Public methodMapperBeforeLayout
Fired when the mapper is just about to begin laying out the mapper's UI.
Public methodMapperBeforeRequery
The mapper is just about to requery its operational data.
Public methodMapperBuildFilter
Fired when the mapper is building a filter. During this event any changes to the filter criteria, table, columns are detected and used for the actual filter.
Public methodMapperBulkAfterDelete
Fired when a bulk delete operation, using this mapper, has been completed.
Public methodMapperBulkAfterInsert
Fired when a bulk insert operation, using this mapper, has been completed.
Public methodMapperBulkAfterUpdate
Fired when a bulk update operation, using this mapper, has been completed.
Public methodMapperBulkBeforeDelete
Fired when a bulk delete operation, using this mapper, is being started.
Public methodMapperBulkBeforeInsert
Fired when a bulk insert operation, using this mapper, is being started.
Public methodMapperBulkBeforeUpdate
Fired when a bulk update operation, using this mapper, is being started.
Public methodCode exampleMapperCommand
Fired when a mapper command has been invoked. MapperCommands can be added to a mapper programmatically by adding a MapperCommand(IMapper, EAPCommandEventArgs) to Commands, typically during the MapperBeforeLayout(IMapper, EAPEventArgs) event. They can also be specified in meta-data via a NavTarget with TargetType of Command on a menu Navigator.
Public methodMapperExecSQL
Fired when the mapper is about to execute a SQL statement. The SQL to be executed is contained in the ExecSQLArgs parameter. Any change made to the SQL in that parameter cause the altered SQL to be used instead of the mapper-generated SQL.
Public methodMapperQueryError
Fired when the mapper has just requeried and there has been an error. You must return HandledByExt and set the desired error message in the event arguments
Protected methodMemberwiseClone
Creates a shallow copy of the current Object.
(Inherited from Object.)
Public methodOnEvent
This method is called to fire an event. The extension responds to this event.
(Inherited from MapperExtensionBase.)
Protected methodOnSetOwner
Called when the Owner of this extension is set by the extension loader.
(Inherited from MapperExtensionBase.)
Public methodOnUnload
Notifies the extension that it should perform any cleanup necessary just prior to being unloaded.
(Inherited from MapperExtensionBase.)
Public methodOther
Handles an un-recognized event. This includes all non-mapper events except Custom(Object, EAPCustomEventArgs) events.
Public methodRowAfterDelete
Fired when the mapper has just completed deleting an entire row from the database.
Public methodRowAfterInsert
Fired when the mapper has just completed inserting an entire row into the database.
Public methodRowAfterUpdate
Fired when the mapper has just completed updating an entire row in the database.
Public methodRowAjaxRequest
Fired when an AJAX request was directed to this mapper. The mapper has been requeried on the requested RowKey and the extension should take appropriate action which might include returning a JSON response in the event arguments. Upon return, the HTTP response will be cleared and any JsonResponse set in the event args will be written to the response. If the extension DOES NOT want this value written to a cleared response object, set the ExtResults.HandledByExt or ExtResults.ContinueNoExec result in the event args. Note that a cancel result will also prevent the HTTP response from being modified. Detailed request information is provided in the AjaxRequestEventArgs parameter.
Public methodRowBeforeDelete
Fired when the mapper is just about to delete an entire row from the database.
Public methodRowBeforeInsert
Fired when the mapper is just about to insert an entire row into the database.
Public methodRowBeforeUpdate
Fired when the mapper is just about to update an entire row in the database.
Public methodRowCurrent
Fired when the mapper has just positioned to a different record.
Public methodRowDrilldown
Datasheet drilldown buttons are normally rendered as links to the same detail page with a different RowKey per link. However, when the DrilldownAttrs.FireDrilldownEvent bit is set, the drilldown button is rendered as a button that, when clicked, posts back the page causing the mapper to fire the this event. The event will be fired on a clone of the mapper positioned to the row that was clicked (per its RowKey). Typically an extension handling this event will programmatically determine the drilldown target and call Navigate(String, String, String, String) or alter the RowDrilldownArgs values to specify a new target MOP and/or RowKey and allow the mapper to perform the custom navigation. If no action is performed by the extension then the mapper will perform the Application.Navigate using the same MOP and RowKey that it would have used had the FireDrilldownEvent not been set.
Public methodRowExecSQL
Fired when the mapper is just about to execute a single SQL statement that is row-specific (e.g. executing an INSERT, UPDATE or DELETE statement).
Public methodRowSetDefaults
Fired when the mapper is moving to a new record and has just completed populating defaults. Immediately following this event it will fire the RowCurrent event. The intent is to provide an opportunity for programmatically setting defaults to field values. Generally it is expected that any field values will be set using
IField.SetValue(val, SetValFlags.DoNotMakeDirty, null);
so that the fields are not made dirty (meaning that if no non-default values are ever set then no save will be attempted. Setting field values using
IField.Value = val;
will make the fields dirty resulting, eventually, in a save even if no non-default values are ever set. You can also change defaults by setting
IField.DefaultValue = val;
and returning
e.Result = ExtResults.DataChanged;
to notify the mapper that it should repopulate from defaults.
Public methodRowValidate
This event is fired by WizSimpleImport (and possibly other import mechanisms) during its validate-only phase each time the import mapper has been populated with all data from the current import record and all built-in validation has been performed. RowValidateArgs are provided in the Event Args.
Public methodToString
Returns a String that represents the current Object.
(Inherited from Object.)
Protected field_logRowCurrent
Specifies whether or not log RowCurrent events to the devlog. Such logging also depends on NoDebug.
(Inherited from MapperExtensionBase.)
Protected field_mapper
The attached mapper object to derived classes
(Inherited from MapperExtensionBase.)
Extension Methods
Public Extension MethodEqualValue
Determines if the object value is equal to another object. If the two objects are null, then this returns true. There is special handling for guid comparisons (since a guid could be a string formatted in up to 3 different ways). If the special guid handling is not performed, then the object.Equals method is used.
(Defined by EAPUtil.)
See Also