Sample: Access the Parent Model

The new UIModel is very helpful when you add fields to existing product forms. Also, the Data Form Addin Spec is helpful when you add logic to existing product forms. But what if you need to do both? Well, you can access the parent forms model and attach events. The purpose of this page is to describe how to do this.

To demonstrate this, I have an example build where we want to set a custom text form called Favorite Color, which is just a one-to-one extension of the constituent with a text field. Here is the Table Spec to help illustrate.

<TableSpec
 
      xmlns="bb_appfx_table"
 
      xmlns:common="bb_appfx_commontypes"
 
      ID="ae9765e2-eb28-41fe-951a-25ce6667ff71"
 
      Name="Constituent Favorite Color"
 
      Description="Table to store a constituent's favorite color."
 
      Author="Blackbaud Professional Services"
 
      Tablename="USR_CONSTITUENTFAVORITECOLOR"
 
PrimaryKeyAsForeignKeyTablename="CONSTITUENT"
 
      >
 
 
 
      <Fields>
 
        <TextField Name="COLOR" Length="100" Required="true" />
 
      </Fields>
 
</TableSpec>

When you extend forms, to access the underlying parent model, you need to unbox the HostModel to the parent model's class. To do this, you need to first include a reference to the parent model library.

Imports Blackbaud.AppFx.Constituent.UIModel.Individual

From there, you can create a class variable to store the reference to the HostModel type. This comes into play later when you access the underlying values of the form.

Imports Blackbaud.AppFx.Constituent.UIModel.Individual
 
Public Class ConstituentFavoriteColorAddDataFormUIModel
 
Private _parentModel As IndividualSpouseBusinessAddFormUIModel

Next, you need to add your custom event to an existing field. In this example, I want to hook into the ValueChanged event for the GENDERCODE field. My event handler then sets my favorite color value.

Imports Blackbaud.AppFx.Constituent.UIModel.Individual
 
 
 
Public Class ConstituentFavoriteColorAddDataFormUIModel
 
 
 
    Private _parentModel As IndividualSpouseBusinessAddFormUIModel
 
 
 
    Private Sub ConstituentFavoriteColorAddDataFormUIModel_HostModelChanged(ByVal sender AsObject, ByVal e As Blackbaud.AppFx.UIModeling.Core.HostModelChangedEventArgs) HandlesMe.HostModelChanged
 
        If _parentModel Is Nothing Then
 
            _parentModel = DirectCast(Me.HostModel, IndividualSpouseBusinessAddFormUIModel)
 
        End If
 
        If Me.HostModel IsNot Nothing Then
 
            AddHandler _parentModel.GENDERCODE.ValueChanged, AddressOf GENDERCODE_ValueChanged
 
        Else
 
            RemoveHandler _parentModel.GENDERCODE.ValueChanged, AddressOf GENDERCODE_ValueChanged
 
        End If
 
    End Sub
 
 
 
    Private Sub GENDERCODE_ValueChanged(ByVal sender As Object, ByVal e AsBlackbaud.AppFx.UIModeling.Core.ValueChangedEventArgs)
 
        If _parentModel.GENDERCODE.Value = IndividualSpouseBusinessAddFormUIModel.GENDERCODES.Male Then
 
            COLOR.Value = "Blue"
 
        ElseIf _parentModel.GENDERCODE.Value = IndividualSpouseBusinessAddFormUIModel.GENDERCODES.Female Then
 
            COLOR.Value = "Pink"
 
        End If
 
    End Sub
 
End Class

Some important notes here: You may notice that I add the event handler and remove the handler during the HostModelChanged event. This is because the HostModel isn't set until after the Loaded event. This HostModelChanged is called when the form is built and when it is torn down. Garbage collection should dispose of the handler but to be safe I explicitly called it.

To give the complete example, here is the add form that uses this model.

<AddDataFormTemplateSpec
 
    xmlns="bb_appfx_adddataformtemplate"
 
    xmlns:common="bb_appfx_commontypes"
 
    ID="4cd41313-dc1b-4ce1-a37a-205eec1f27c1"
 
    Name="Constituent Favorite Color Add Data Form"
 
    Description="Data form extension for a constituent's favorite color."
 
    Author="Blackbaud Professional Services"
 
    DataFormInstanceID="aa71fbac-92a8-4c51-8c0c-c1bc9b4f46ec"
 
    RecordType="Constituent"
 
    common:SecurityUIFolder="Constituent">
 
 
 
      <SPDataForm>
 
            <SaveImplementationSPName="USR_USP_DATAFORMTEMPLATE_ADD_CONSTITUENTFAVORITECOLOR">
 
                  <common:CreateProcedureSQL>
 
                        <![CDATA[
 
create procedure dbo.USR_USP_DATAFORMTEMPLATE_ADD_CONSTITUENTFAVORITECOLOR
 
(
 
    @ID uniqueidentifier = null output,
 
      @CONSTITUENTID uniqueidentifier,
 
@CHANGEAGENTID uniqueidentifier = null,
 
      @COLOR nvarchar(100) = ''
 
)
 
as
 
 
 
set nocount on;
 
 
 
if @ID is null
 
    set @ID = newid()
 
 
 
if @CHANGEAGENTID is null 

    exec dbo.USP_CHANGEAGENT_GETORCREATECHANGEAGENT @CHANGEAGENTID output
 
 
 
declare @CURRENTDATE datetime
 
set @CURRENTDATE = getdate()
 
 
 
begin try
 
      -- handle inserting the data
 
      insert into dbo.USR_CONSTITUENTFAVORITECOLOR
 
            (ID, COLOR, ADDEDBYID, CHANGEDBYID, DATEADDED, DATECHANGED)
 
    values
 
            (@CONSTITUENTID, @COLOR, @CHANGEAGENTID, @CHANGEAGENTID, @CURRENTDATE, @CURRENTDATE)
 
     

end try
 
 
 
begin catch
 
    exec dbo.USP_RAISE_ERROR
 
    return 1
 
end catch
 
 
 
return 0                     

                        ]]>
 
                  </common:CreateProcedureSQL>
 
            </SaveImplementation>
 
      </SPDataForm>
 
 
 
      <Context ContextRecordType="Constituent" RecordIDParameter="CONSTITUENTID" />
 
 
 
      <common:FormMetaData FixedDialog="true">
 
            <common:FormFields>
 
                  <common:FormField FieldID="COLOR" Caption="Favorite color"DataType="String" MaxLength="100" />
 
            </common:FormFields>
 
 
 
        <common:WebUIComponent>
 
            <common:UIModel AssemblyName="UIModel.dll"ClassName="UIModel.ConstituentFavoriteColorAddDataFormUIModel" />
 
            <common:WebUI>
 
                <common:DefaultWebUI />
 
            </common:WebUI>
 
        </common:WebUIComponent>       

      </common:FormMetaData>
 
 
 
    <common:DataFormExtension DataFormInstanceID="1f9671b3-6740-447c-ad15-ef2718c0e43a"RenderStyle="Tab" TabCaption="Favorite Color" />
 
</AddDataFormTemplateSpec>