Data Form AddIns

Data Form AddIns are a type of catalog spec available as part of the SDK. Data Form AddIns enable adding user interface behavior to an existing UI Model data form. Data Form AddIns only work with forms that use a UI Model.

Creating a Data Form AddIn

From Visual Studio with the SDK installed, open the catalog project to which to add the Data Form AddIn and select Add > New Item. The Add New Item screen appears.
From Name, enter a name that corresponds to the data form to extend. For example enter IndividualAddForm.AddIn.xml.
Click Add. The Loaded Data Form Instance Search screen appears. Search for the existing form.

Highlight the form and click Select.

The spec appears in Visual Studio. A Visual Basic file that contains a partial class appears in a Visual Basic editor. For example given the previous steps, the file would be IndividualAddForm.AddIn.vb and the partial class would be this:

Partial Public NotInheritable Class IndividualAddFormAddIn

    Private Sub OnInit()
        'This method is called when the UI model is created to allow any initialization to be performed.
    End Sub

End Class

That file can be edited. However another Visual Basic file that contains generated code in a partial class is also created. The partial class that contains generated code should not be edited. That file would look like this:

'------------------------------------------------------------------------------
' <auto-generated>
'     This code was generated by Blackbaud.AppFx.SDKVSWizards.dll
'     Version:  3.0.516.0
'     Date:  07/08/2013 1:47:04 PM
'
'     Changes to this file may cause incorrect behavior and will be lost if
'     the code is regenerated.
' </auto-generated>
'------------------------------------------------------------------------------

Partial Public NotInheritable Class IndividualAddFormAddIn
    Inherits Blackbaud.AppFx.UIModeling.Core.RootModelAddIn(Of Global.Blackbaud.AppFx.Constituent.UIModel.Individual.IndividualAddFormUIModel)

    Friend WithEvents MODEL As Global.Blackbaud.AppFx.Constituent.UIModel.Individual.IndividualAddFormUIModel
    Friend WithEvents [LASTNAME] As Global.Blackbaud.AppFx.UIModeling.Core.StringField
    Friend WithEvents [FIRSTNAME] As Global.Blackbaud.AppFx.UIModeling.Core.StringField
    Friend WithEvents [MIDDLENAME] As Global.Blackbaud.AppFx.UIModeling.Core.StringField
    Friend WithEvents [MAIDENNAME] As Global.Blackbaud.AppFx.UIModeling.Core.StringField
    Friend WithEvents [NICKNAME] As Global.Blackbaud.AppFx.UIModeling.Core.StringField
    Friend WithEvents [MARITALSTATUSCODEID] As Global.Blackbaud.AppFx.UIModeling.Core.CodeTableField
    Friend WithEvents [TITLECODEID] As Global.Blackbaud.AppFx.UIModeling.Core.CodeTableField
    Friend WithEvents [TITLE2CODEID] As Global.Blackbaud.AppFx.UIModeling.Core.CodeTableField
    Friend WithEvents [SUFFIXCODEID] As Global.Blackbaud.AppFx.UIModeling.Core.CodeTableField
    Friend WithEvents [SUFFIX2CODEID] As Global.Blackbaud.AppFx.UIModeling.Core.CodeTableField
    Friend WithEvents [GENDERCODE] As Global.Blackbaud.AppFx.UIModeling.Core.ValueListField(Of Blackbaud.AppFx.Constituent.UIModel.Individual.IndividualAddFormUIModel.GENDERCODES)
    Friend WithEvents [BIRTHDATE] As Global.Blackbaud.AppFx.UIModeling.Core.FuzzyDateField
    Friend WithEvents [PICTURE] As Global.Blackbaud.AppFx.UIModeling.Core.BinaryField
    Friend WithEvents [PICTURETHUMBNAIL] As Global.Blackbaud.AppFx.UIModeling.Core.BinaryField
    Friend WithEvents [WEBADDRESS] As Global.Blackbaud.AppFx.UIModeling.Core.WebAddressField
    Friend WithEvents [ADDRESS_ADDRESSTYPECODEID] As Global.Blackbaud.AppFx.UIModeling.Core.CodeTableField
    Friend WithEvents [ADDRESS_COUNTRYID] As Global.Blackbaud.AppFx.UIModeling.Core.SimpleDataListField(Of Guid)
    Friend WithEvents [ADDRESS_ADDRESSBLOCK] As Global.Blackbaud.AppFx.UIModeling.Core.StringField
    Friend WithEvents [ADDRESS_CITY] As Global.Blackbaud.AppFx.UIModeling.Core.StringField
    Friend WithEvents [ADDRESS_STATEID] As Global.Blackbaud.AppFx.UIModeling.Core.SimpleDataListField(Of Guid)
    Friend WithEvents [ADDRESS_POSTCODE] As Global.Blackbaud.AppFx.UIModeling.Core.SearchListField(Of String)
    Friend WithEvents [ADDRESS_DONOTMAIL] As Global.Blackbaud.AppFx.UIModeling.Core.BooleanField
    Friend WithEvents [ADDRESS_DONOTMAILREASONCODEID] As Global.Blackbaud.AppFx.UIModeling.Core.CodeTableField
    Friend WithEvents [PHONE_PHONETYPECODEID] As Global.Blackbaud.AppFx.UIModeling.Core.CodeTableField
    Friend WithEvents [PHONE_NUMBER] As Global.Blackbaud.AppFx.UIModeling.Core.PhoneField
    Friend WithEvents [EMAILADDRESS_EMAILADDRESSTYPECODEID] As Global.Blackbaud.AppFx.UIModeling.Core.CodeTableField
    Friend WithEvents [EMAILADDRESS_EMAILADDRESS] As Global.Blackbaud.AppFx.UIModeling.Core.EmailAddressField
    Friend WithEvents [SKIP_ADDING_SECURITYGROUPS] As Global.Blackbaud.AppFx.UIModeling.Core.BooleanField
    Friend WithEvents [ZIPLOOKUPCOUNTRIES] As Global.Blackbaud.AppFx.UIModeling.Core.CollectionField(Of Blackbaud.AppFx.Constituent.UIModel.Individual.IndividualAddFormZIPLOOKUPCOUNTRIESUIModel)
    Friend WithEvents [JOBTITLE] As Global.Blackbaud.AppFx.UIModeling.Core.StringField
    Friend WithEvents [OMITFROMVALIDATION] As Global.Blackbaud.AppFx.UIModeling.Core.BooleanField
    Friend WithEvents [DPC] As Global.Blackbaud.AppFx.UIModeling.Core.StringField
    Friend WithEvents [CART] As Global.Blackbaud.AppFx.UIModeling.Core.StringField
    Friend WithEvents [LOT] As Global.Blackbaud.AppFx.UIModeling.Core.StringField
    Friend WithEvents [COUNTYCODEID] As Global.Blackbaud.AppFx.UIModeling.Core.CodeTableField
    Friend WithEvents [CONGRESSIONALDISTRICTCODEID] As Global.Blackbaud.AppFx.UIModeling.Core.CodeTableField
    Friend WithEvents [LASTVALIDATIONATTEMPTDATE] As Global.Blackbaud.AppFx.UIModeling.Core.DateField
    Friend WithEvents [VALIDATIONMESSAGE] As Global.Blackbaud.AppFx.UIModeling.Core.StringField
    Friend WithEvents [CERTIFICATIONDATA] As Global.Blackbaud.AppFx.UIModeling.Core.IntegerField
    Friend WithEvents [VALIDATIONCOUNTRIES] As Global.Blackbaud.AppFx.UIModeling.Core.CollectionField(Of Blackbaud.AppFx.Constituent.UIModel.Individual.IndividualAddFormVALIDATIONCOUNTRIESUIModel)
    Friend WithEvents [SKIP_ADDING_SITES] As Global.Blackbaud.AppFx.UIModeling.Core.BooleanField
    Friend WithEvents [INFOSOURCECODEID] As Global.Blackbaud.AppFx.UIModeling.Core.CodeTableField
    Friend WithEvents [AGE] As Global.Blackbaud.AppFx.UIModeling.Core.StringField
    Friend WithEvents [INVALIDAGEIMAGE] As Global.Blackbaud.AppFx.UIModeling.Core.StringField
    Friend WithEvents [PERSONALGROUP] As Global.Blackbaud.AppFx.UIModeling.Core.GroupField
    Friend WithEvents [CONTACTGROUP] As Global.Blackbaud.AppFx.UIModeling.Core.GroupField
    Friend WithEvents [PRIMARYCONTACTSOURCEGROUP] As Global.Blackbaud.AppFx.UIModeling.Core.GroupField
    Friend WithEvents [VALIDATEADDRESSACTION] As Global.Blackbaud.AppFx.UIModeling.Core.ShowCustomFormUIAction
    Friend WithEvents [FORMHEADER] As Global.Blackbaud.AppFx.UIModeling.Core.StringField

    Public Overrides Sub Init()

        Me.MODEL = Me.HostModel
        Me.[LASTNAME] = Me.HostModel.[LASTNAME]
        Me.[FIRSTNAME] = Me.HostModel.[FIRSTNAME]
        Me.[MIDDLENAME] = Me.HostModel.[MIDDLENAME]
        Me.[MAIDENNAME] = Me.HostModel.[MAIDENNAME]
        Me.[NICKNAME] = Me.HostModel.[NICKNAME]
        Me.[MARITALSTATUSCODEID] = Me.HostModel.[MARITALSTATUSCODEID]
        Me.[TITLECODEID] = Me.HostModel.[TITLECODEID]
        Me.[TITLE2CODEID] = Me.HostModel.[TITLE2CODEID]
        Me.[SUFFIXCODEID] = Me.HostModel.[SUFFIXCODEID]
        Me.[SUFFIX2CODEID] = Me.HostModel.[SUFFIX2CODEID]
        Me.[GENDERCODE] = Me.HostModel.[GENDERCODE]
        Me.[BIRTHDATE] = Me.HostModel.[BIRTHDATE]
        Me.[PICTURE] = Me.HostModel.[PICTURE]
        Me.[PICTURETHUMBNAIL] = Me.HostModel.[PICTURETHUMBNAIL]
        Me.[WEBADDRESS] = Me.HostModel.[WEBADDRESS]
        Me.[ADDRESS_ADDRESSTYPECODEID] = Me.HostModel.[ADDRESS_ADDRESSTYPECODEID]
        Me.[ADDRESS_COUNTRYID] = Me.HostModel.[ADDRESS_COUNTRYID]
        Me.[ADDRESS_ADDRESSBLOCK] = Me.HostModel.[ADDRESS_ADDRESSBLOCK]
        Me.[ADDRESS_CITY] = Me.HostModel.[ADDRESS_CITY]
        Me.[ADDRESS_STATEID] = Me.HostModel.[ADDRESS_STATEID]
        Me.[ADDRESS_POSTCODE] = Me.HostModel.[ADDRESS_POSTCODE]
        Me.[ADDRESS_DONOTMAIL] = Me.HostModel.[ADDRESS_DONOTMAIL]
        Me.[ADDRESS_DONOTMAILREASONCODEID] = Me.HostModel.[ADDRESS_DONOTMAILREASONCODEID]
        Me.[PHONE_PHONETYPECODEID] = Me.HostModel.[PHONE_PHONETYPECODEID]
        Me.[PHONE_NUMBER] = Me.HostModel.[PHONE_NUMBER]
        Me.[EMAILADDRESS_EMAILADDRESSTYPECODEID] = Me.HostModel.[EMAILADDRESS_EMAILADDRESSTYPECODEID]
        Me.[EMAILADDRESS_EMAILADDRESS] = Me.HostModel.[EMAILADDRESS_EMAILADDRESS]
        Me.[SKIP_ADDING_SECURITYGROUPS] = Me.HostModel.[SKIP_ADDING_SECURITYGROUPS]
        Me.[ZIPLOOKUPCOUNTRIES] = Me.HostModel.[ZIPLOOKUPCOUNTRIES]
        Me.[JOBTITLE] = Me.HostModel.[JOBTITLE]
        Me.[OMITFROMVALIDATION] = Me.HostModel.[OMITFROMVALIDATION]
        Me.[DPC] = Me.HostModel.[DPC]
        Me.[CART] = Me.HostModel.[CART]
        Me.[LOT] = Me.HostModel.[LOT]
        Me.[COUNTYCODEID] = Me.HostModel.[COUNTYCODEID]
        Me.[CONGRESSIONALDISTRICTCODEID] = Me.HostModel.[CONGRESSIONALDISTRICTCODEID]
        Me.[LASTVALIDATIONATTEMPTDATE] = Me.HostModel.[LASTVALIDATIONATTEMPTDATE]
        Me.[VALIDATIONMESSAGE] = Me.HostModel.[VALIDATIONMESSAGE]
        Me.[CERTIFICATIONDATA] = Me.HostModel.[CERTIFICATIONDATA]
        Me.[VALIDATIONCOUNTRIES] = Me.HostModel.[VALIDATIONCOUNTRIES]
        Me.[SKIP_ADDING_SITES] = Me.HostModel.[SKIP_ADDING_SITES]
        Me.[INFOSOURCECODEID] = Me.HostModel.[INFOSOURCECODEID]
        Me.[AGE] = Me.HostModel.[AGE]
        Me.[INVALIDAGEIMAGE] = Me.HostModel.[INVALIDAGEIMAGE]
        Me.[PERSONALGROUP] = Me.HostModel.[PERSONALGROUP]
        Me.[CONTACTGROUP] = Me.HostModel.[CONTACTGROUP]
        Me.[PRIMARYCONTACTSOURCEGROUP] = Me.HostModel.[PRIMARYCONTACTSOURCEGROUP]
        Me.[VALIDATEADDRESSACTION] = Me.HostModel.[VALIDATEADDRESSACTION]
        Me.[FORMHEADER] = Me.HostModel.[FORMHEADER]

        OnInit()

    End Sub

    Partial Private Sub OnInit()
    End Sub

End Class

As with other specs, there is an XML portion. The XML does not require additional editing. The XML for the spec would look like this:

<DataFormAddInSpec
	xmlns="bb_appfx_dataformaddin"
	xmlns:common="bb_appfx_commontypes"
	ID="27ca4143-80cd-4758-b471-3aec3242f5e2" 
	Name="Individual Add Form AddIn"
	Description="An addin for the Individual Add Form data form" 
	Author="Technical Training"
	DataFormInstanceID="1986f0cf-efb6-48b3-afde-950b57562434"
	>

	<DataFormAddIn AssemblyName="Custom.AppFx.AddInExample.Catalog"
                 ClassName="Custom.AppFx.AddInExample.Catalog.IndividualAddFormAddIn" />

</DataFormAddInSpec>

The OnInit() procedure created by the wizard is one place where custom form behavior can be defined. For example to hide the Title Code field, this can be added:

Partial Public NotInheritable Class IndividualAddFormAddIn

    Private Sub OnInit()
        'This method is called when the UI model is created to allow any initialization to be performed.
        Me.MODEL.TITLECODEID.Visible = False
    End Sub

End Class

To use the AddIn, the XML spec must be loaded and the assembly must be deployed. Just loading the spec via LoadSpec from Visual Studio will not deploy the assembly. The project must be built and the assembly must be copied to the vroot\bin folder. Once the AddIn is loaded and deployed, the form can be tested.