Exercise: Create a UI Model on a Custom Data Form

This exercise is a continuation of the previous exercise. We will use the UI Model wizard to convert the custom Food Item Add Data Form to a UI Model-based form. The spec for this exercise, FoodItem.Add.xml, should already exist in the Blackbaud.CustomFx.Foodbank.Catalog project and should be loaded into the database.

Step 1 -  Start the UI Model Wizard.

Right-click the project the Blackbaud.CustomFx.Foodbank.UIModel project that we created in the previous exercise, and select Add\New Item….

To create a UI Model, simply add a new item to the project using the UI Model Wizard template. The name is irrelevant at this point, so just leave it as UI Model1.xml.

The UI Model Wizard launches. We provide the wizard with the following information:

The UI Model wizard performs the following:

Below is a diagram of the actions performed by the wizard:

Where Does My UI Model Code Live?

A UI Model Assembly lives on the server and contains our .NET strongly typed behavior code. The UI Model Assembly project also houses the user interface components such as HTML, JavaScript, cascading style sheets, etc. For Blackbaud Professional Services, third-party, and customer developed code, the compiled assembly .dll files will live within the vroot\bin\custom folder on the server and the HTML files will live within the vroot\browser\htmlforms\custom folder or sub-folder. 

The UI Model wizard generates the partial class in a "hidden" file. While you can easily locate the partial class by selecting Show All Files within your Visual Studio Solution Explorer, the "hidden" file provides "hide-protecting," and this prevents mishaps and provides a layer of abstraction from the generated code and your code. As a developer, you should not alter this code. Keep the generated partial class separate from your code to prevent the loss of your changes when the partial class is updated.

Step 2 -  Identify the generated code within your project.

To see the code generated partial class and wizard parameter XML file, click the Show All Files button within the Solution Explorer.

Navigate through your Blackbaud.CustomFx.FoodBank.UIModel assembly project and identify the files created by the wizard.

What Changes Are Made to the Spec?

Step 3 -  Review the changes to the spec.

In a spec that is used to generate a UI Model, we can see changes to the FormMetaData element. Specifically, any old FormUIComponent or WebUIComponent tags are removed and replaced with a WebUIComponent XML tag.

Note: Web Shell Readiness Alert. While a feature that utilizes a FormUIComponent element in the spec works in the ClickOnce Smart Client, the presence of the FormUIComponent element signifies that a conversion is necessary to view the feature in the Web Shell. A UI Model must be generated for the form field parameters before the feature will work in the Web Shell user interface. At a high level, a conversion is accomplished by first generating a UI Model and replacing the FormUIComponent element with the WebUIComponent element. For more information, see User Interface, Frequently Asked Questions, and Features that Require a Conversion to Webshell.

The Wizard Generates a Partial Class File and a Complementing Class File as Your New UI Model

The wizard generates two class files that make up the UI Model. The first is an Infinity platform-generated partial class file that comprises a strongly typed API from your spec. The second is an empty complementing class file "stub" that will contain the UI behavior .NET code that you create.

Step 4 -  Review the partial class.

Select the new Blackbaud.CustomFx.FoodBank.UIModel project and click the Show All Files button within the Solution Explorer to reveal hidden project files. Click the + button to the left of the newly generated FoodItemAddFormUIModel.vb class file. Open the partial class named FoodItemAddFormUIModel.CodeGen.vb. Notice the CodeGen name within the file name which denotes that the UI Model wizard generates this code.

Essentially, a UI Model is .NET partial class that is generated from the metadata in a spec that is loaded in the Infinity database. The partial class is generated from a UI Model wizard that comes with the Infinity SDK. A partial class enables software developers to split a .NET class definition into multiple physical class files. At compile time, the compiler combines both the generated partial class and your class into a single entity. The most compelling reason to use a partial class is to separate your application business logic from the designer-generated code.

Step 5 -  Examine the generated class and add simple behavior.

Select the new Blackbaud.CustomFx.FoodBank.UIModel project and open the partial class named FoodItemAddFormUIModel.vb.

The beginnings of the class file were created by the wizard. 

Since your class file is really an addition to the partial class, you have access to the code within the partial class. For example, we can modify the properties of one of the form fields defined by the partial class. Go ahead and add the code highlighted in green below to the FoodItemAddFormUIModel.vb class file.

Step 6 -  Build the UI Model assembly, deploy the DLL, and deploy the HTML.

Go ahead and build the assembly for the Blackbaud.CustomFx.FoodBank.UIModel project. Make sure the assembly resides within the vroot\bin\custom folder or sub-folder on the web server.

Next, ensure the HTML file is deployed to the vroot\browser\htmlforms\custom folder or sub-folder.

Step 7 -  Load the spec.

Since the UI Model wizard updated our Data Form Spec, we need to re-load it to ensure that the references to the UI Model assembly and HTML UI are reflected. 

Within Visual Studio, select Tools\LoadSpec to update the FoodItem.Add.xml spec in the database.

After we build and deploy our UI Model assembly to the web server and open the Food Item Add form, we will see that the caption and value changed on our description form field. 

Here is a link to the Food Bank Source Code.