Avectra.NetForum.Data.FacadeClass

The Avectra.NetForum.Data.FacadeClass is the base class of all NetForum Facade Objects.

Every Object in NetForum is represented by the Object in the NetForum Toolkit. The Object refers to the assembly and typename of the object class. Most NetForum objects are "dynamic" and belong to the Avectra.NetForum.Data.DynamicFacade, which is a subclass of FacadeClass. Approximately twenty percent of NetForum objects are "static" facade objects, which are heavily custom subclasses of FacadeClass.

Features

All of the NetForum business objects (Invoice, Member, Individual, Event, etc.) are implemented in NetForum through the Façade Object model with the namespace Avectra.netFORUM.Data.FacadeClass. Each object has an associated Object metadata reference describes the Assembly and Type. Simpler objects (Prefix, Suffix, etc.) use a generic type called Dynamic Façade with the namespace Avectra.NetForum.Data.DynamicFacade. More complex objects (Invoice, Payment, etc.) use specialized objects that inherit from the base Façade Class. We call these Static façade objects (to differentiate from Dynamic Façade Objects).

Based on these objects and their definitions, the NetForum applications (iWeb, eWeb, xWeb, etc.) marshal them accordingly.

The diagram below, from a seminar at one of Avectra's Users and Developers Conference, illustrates this model:

Properties

bExecuteInheritedWorkflow (bool). For custom facade objects, set to True if you want to execute Workflow for the object from which you are inheriting.
CurrentKey (string). The primary key of the record loaded in the Facade Object. May be get or set. Set the property when you want to load a new object. Returns a string that will be a GUID if the select was successful and empty string if unsuccessful.
oParentFacadeDetails (Avectra.NetForum.Data.FacadeDetails). A FacadeDetails Collection containing the Parent Facade Object, if any, used in conjunction with oParentFacadeDetails.oParentFacadeObject.
oParentFacadeDetails.oParentFacadeDetails (Avectra.NetForum.Data.FacadeClass). The parent Facade Class of the given Facade Object.
DoNotSave (bool). If set to true, then the object will not save when the Insert or Update method is called. Set this to true when you want NetForum to skip the Save event for any reason.
SupportsCorrespondence (bool). Enables the List Page Select Mode and other email features to be used. Equivalent to the Supports Correspondence checkbox on the Object. You should set this property to true if the object ultimately connects to a customer.

Methods

Avectra.NetForum.Data.FacadeClass.AddDataObject. Adds an Avectra.NetForum.Data.DataClass to a Facade Object.
Avectra.NetForum.Data.FacadeClass.ClearValues. Clears the value of every NetForum.Data.Field in every Avectra.NetForum.Data.DataClass of the Facade Object.
Avectra.NetForum.Data.FacadeClass.Delete. Deletes existing rows of data related to the CurrentKey property of the facade object.
Avectra.NetForum.Data.FacadeClass.GetDataObject. Returns a Avectra.NetForum.Data.DataClass from a Facade Object.
Avectra.NetForum.Data.FacadeClass.GetValue Gets a value of a field from the Facade Object.
Avectra.NetForum.Data.FacadeClass.GetOriginalValue -- similar to GetValue, only returns the original value as it existed just after the SelectByKey method is called.
Avectra.NetForum.Data.FacadeClass.Insert. Inserts new rows of data into the database based on the data contained in the facade object.
Avectra.NetForum.Data.DataUtils.InstantiateFacadeObject - method to instantiate a new facade object.
Avectra.NetForum.Data.FacadeClass.LoadRelatedData. Loads related data objects based on the values of controls that are foreign keys.
Avectra.NetForum.Data.FacadeClass.SelectByKey. Loads a Facade Object's data based on the value of the CurrentKey property.
Avectra.NetForum.Data.FacadeClass.SetValue. Sets the value of a field in the Facade Object.
Avectra.NetForum.Data.FacadeClass.Update. Updates existing rows of data in the database based on the data contained in the facade object.
Avectra.NetForum.Data.FacadeClass.ValueChanged. Returns bool; true if the value changed, else false.

Before and After Methods

The following four methods provide the ability to run limited operations before or after the main transaction. Note that this code fires only in iWeb and eWeb upon the Save of a form and in UpdateFacadeObject. Therefore, these methods should only be used to present non-critical choices to a user or work closely with UI functions such a Confirmation Dialog to present different ErrorLevels depending on user entries. The database connection and transaction associated with the Save or Delete are NOT available, so be aware that any database calls will be happening independently of the active connection/transaction because in the case of the Before methods, the connection/transaction don't exist yet, and in the case of the After methods, the connection/transaction have already been closed and committed. Owing to these limitations, use these methods with caution.

If you need a rule to fire universally, it is better to override the Insert, Update or Delete methods. Based on years of experience, the best value of these methods is to pose a Confirmation Dialog to the user in either of the two Before methods.

The base methods do nothing; these methods are meant for implementation-specific overrides.

Avectra.NetForum.Data.FacadeClass.AfterSave - note that if you try to raise Config.LastError here, it is too late as the Save has already occurred. You will not be able to present any dialog boxes to a user from this method as you can in the BeforeSave; they will be ignored.
Avectra.NetForum.Data.FacadeClass.BeforeDelete
Avectra.NetForum.Data.FacadeClass.BeforeSave - commonly used to pose an Avectra.NetForum.Common.ErrorClass.ErrorLevel.ConfirmDialog javascript prompt to a user; user may click OK to continue or Cancel to stop the save and stay on the page. Message can have at most approximately 484 characters or else it won't display.

Usage and Examples

Static Facade Object Override - example of overriding a static facade object
Handling Check Constraint Errors - case study of how to trap a check constraint error in code, and then present an informative error message to the end user.

Avectra.NetForum.Data.FacadeClass

See DynamicFacade with Virtual Field for another case study

A FacadeClass may have virtual fields that are added to a data object. This is done in code, not in metadata. You do this by creating a new Avectra.NetForum.Data.Field and then adding that field to a Avectra.NetForum.Data.DynamicData data object using its Avectra.NetForum.Data.DynamicData.AddField method.

Once the virtual field is added to the data object, then you can add this field as a Form Control to a Form, and its value can be parsed in code. Since this is a virtual field, and not a true database column, it is of course not available in SQL or in List Tables.

Example from the Avectra.NetForum.Components.CO.CO_Individual_X_Organization static facade class, in the InitializeObjects method using the ixo_primary field which is used to present a checkbox on the Individual Organization Relationship page to enable a user to select a primary relationship.

// Declare the DynamicData object
_oData = new DynamicData("co_individual_x_organization", "co_individual_x_organization_ext", 
"ixo","ixo", "ixo_key","ixo_key_ext", "ixo_delete_flag","Organization XRef");
 
/// snip...
 
// Add the data object to the FacadeClass
AddDataObject("ixo", _oData,"Organization XRef");
 
// Create a new virtual field and set properties
Field oF = new Field();
oF.Properties.Name = "ixo_primary";
oF.Value = "0";
oF.Properties.Description = "Primary Organization";
oF.Properties.ControlClass = "CheckBox";
oF.Properties.DataType = "av_flag";
oF.Properties.DefaultValue = "0";
oF.Properties.Hidden = false;
oF.Properties.NotEditable = false;
oF.Properties.Nullable = true;
oF.Properties.ReadOnlyEdit = false;
oF.Properties.Required = false;
oF.Properties.SortOrder = 100000;
 
// Add the Field to the data object
_oData.AddField(oF);

An alternate to a virtual field is to override the Avectra.NetForum.Data.FacadeClass.GetValue method to allow for getting the value of other fields. You can parse values in this way, but since you don't have an actual field, you cannot design it onto a form.

If you need to add a virtual field to an existing data object in a static facade object, you can call the Avectra.NetForum.Data.FacadeClass.GetDataObjectmethod (passing the 3-character prefix of the data object) to return the object to aAvectra.NetForum.Data.DataClass, as shown in this example:

[Serializable()]
class ABC_co_customer_x_address : CO_Customer_X_Address
{
protected override void InitializeObjects()
{
base.InitializeObjects();
 
            DataClass oCustomerAddress = this.GetDataObject("cxa");
 
            Field oF = new Field();
            oF.Properties.Name = "cxa_primary_meeting_place_flag";
            oF.Value = "0";
            oF.Properties.Description = "Primary Meeting Place";
            oF.Properties.ControlClass = "CheckBox";
            oF.Properties.DataType = "av_flag";
            oF.Properties.DefaultValue = "0";
            oF.Properties.Hidden = false;
            oF.Properties.NotEditable = false;
            oF.Properties.Nullable = true;
            oF.Properties.ReadOnlyEdit = false;
            oF.Properties.Required = false;
            oF.Properties.SortOrder = 100000;
 
            oCustomerAddress.AddField(oF);
}