UI Model for Data Forms

Data forms may require presentational logic. For example, a data form may require an event handler to enable or disable form fields based upon a value selected within a drop-down control. A data form may require a “date completed” form field to be enabled only when the status drop-down has been set to “completed”. Or, before the user interface is closed, a data form may need to shuttle values from UI fields to the form fields that are tied to the save implementation.

The foundation for user interface behavioral logic and event handlers is the UI Model. A UI Model is generated using a UI Model wizard. A UI Model consists of two .NET class files:

  • A partial public class file which represents a user interface model of the data form’s form fields, events, and state

  • A public class file where presentational code resides

At compile time both class files are combined to represent a single, logical class. The code lives within a .NET assembly and is deployed to the web server. A prerequisite to any UI Model is a well defined spec where the form fields and implementations are working correctly. Before using a UI Model to enhance a data form's presentational logic, solid business logic for the data form should be established.

Within Visual Studio, a UIModel wizard can be used to create the beginnings of the UIModel from a well-defined Data Form Spec. In addition to generating the code, the wizard will modify the Data Form Spec by adding a UIModel element within a WebUIComponent element within the data form’s FormMetaData element. For more information about how to create a UI Model project and how to run the UI Model wizard, see Create a UI Model for an Add Data Form, Create a UI Model for an Edit Data Form, or Create a UI Model for a View Data Form.

<WebUIComponent>
 <UIModel AssemblyName="Blackbaud.AppFx.Event.UIModel.dll"
  ClassName="Blackbaud.AppFx.Event.UIModel.EventTaskEditFormUIModel" />
   <WebUI>
    <ExternalResource Url="browser\htmlforms\event\EventTaskEditForm.html" />
   </WebUI>
</WebUIComponent>

After the UI Model wizard has generated a code model of the data form, you can add code for a desired behavior. Here is sample code that responds to the ValueChanged event of the Status form field that is emitted from the data form.

Public Class EventTaskEditFormUIModel

    Private Sub EventTaskEditFormUIModel_Loaded(ByVal sender As Object, ByVal e As Blackbaud.AppFx.UIModeling.Core.LoadedEventArgs) Handles Me.Loaded
        UpdateDateCompletedState()
        _owneridsearchaction.SearchFieldOverrides.Add(New FieldOverride With {.FieldId = "EVENTTASK_EVENTID", .Hidden = True, .DefaultValueText = Me.EVENTID.Value.ToString()})

    End Sub

    Private Sub _statuscode_ValueChanged(ByVal sender As Object, ByVal e As UIModeling.Core.ValueChangedEventArgs) Handles _statuscode.ValueChanged
        UpdateDateCompletedState()
    End Sub

    Private Sub UpdateDateCompletedState()
        Dim completed = (Me.STATUSCODE.Value = STATUSCODES.Completed)

        Me.DATECOMPLETED.Enabled = completed
        REMINDERS.Enabled = Not completed

        If completed Then
            Me.DATECOMPLETED.Value = Date.Today
        Else
            Me.DATECOMPLETED.Value = Nothing
        End If

    End Sub

End Class

At run time, when a user changes the status to Completed, the Date Completed field becomes enabled. When a date is entered and Status is changed back to Active, the date disappears and the Date completed field is disabled.