Create a View Data Form (SP)

This task walks through steps to create a new View Data Form (SP) Spec with the Add New Item wizard and to adjust the spec for a specific table. The Table Spec that corresponds to this View Data Form (SP) Spec is shown in the steps.

From an existing Blackbaud AppFx Catalog Project, right-click the project and select Add > New Item. The Add New Item screen appears.
Select Blackbaud AppFx Catalog > View Data Form Template Spec (SP).
From Name, enter a name such as Example.View.xml or Example.Sp.View.xml.
Click Add. The new spec appears in Solution Explorer and in the XML Editor.

In the spec that appears in the XML Editor...
Leave the first three attributes of ViewDataFormTemplate as-is. The first two are namespace declarations for schema related to the spec type. The third is an ID for the feature, a GUID or uniqueidentifier generated by the Add New Item wizard. ID should be unique for every spec. The root element attributes for data forms are discussed in Root Element Attributes.
xmlns="bb_appfx_viewdataformtemplate" xmlns:common="bb_appfx_commontypes" ID="c4400b6b-db85-4111-9388-021a31ae712f"
Adjust the next three attributes as necessary. The Add New Item wizard creates a Name and Description based on the filename entered in the Name field of the Add New Item screen. Author is inferred from a setting established when the Blackbaud Infinity SDK is installed.

Note: To avoid future conflicts in the event Blackbaud adds an Example record type, add (custom) to the end of Name, RecordType, and SecurityUIFolder. If the (custom) suffix is not satisfactory for display, the NameUIOverride attribute can be used in addition to adding (custom). The Table Spec that corresponds to this View Data Form is described later in this task. The Name attribute for TableSpec is adjusted to Example (custom) in the Table Spec for the same reason.

Change these attributes:
Name="Example View Data Form" Description="A data form for viewing example records" Author="Technical Training"
To:
Name="Example View Data Form (custom)" Description="A data form for viewing example records" Author="Technical Training"
DataFormInstanceID is an additional ID. DataFormInstanceID is discussed in Root Element Attributes. But remember that most features refer to data forms by DataFormInstanceID and not ID.
DataFormInstanceID="6673f03d-3b3e-4d42-9975-d31e90e41d93"
The last two attributes can also be adjusted. Again, the wizard infers each based on the filename entered in the Name field of the Add New Item screen. But to avoid future conflicts in the event Blackbaud adds an Example record type, add the (custom) suffix.

Change these attributes:
RecordType="Example" common:SecurityUIFolder="Example"
To:
RecordType="Example (custom)" common:SecurityUIFolder="Example (custom)"
Within the SPDataForm element, the View Data Form implementation is stubbed-out. The stubbed implementations assume three fields. Every parameter except @ID is an output parameter, meaning those will be returned by the stored procedure and loaded to the form.
@ID uniqueidentifier, @DATALOADED bit = 0 output, @FIELD1 nvarchar(10) = null output, @FIELD2 nvarchar(20) = null output, @FIELD3 nvarchar(max) = null output
At this point, take some time to examine the Table Spec and table that relates to this Add Data Form. This Table Spec has few embellishments. The fields on the data form's stored procedure for the save implementation and the form fields on the Add Data Form will correspond to the fields on this Table Spec. Notice the Name attribute of TableSpec matches the RecordType for the Add Data Form.
```
<TableSpec
	xmlns="bb_appfx_table"
	xmlns:common="bb_appfx_commontypes"
	ID="4455ac1b-c6f0-4a56-b708-77942a823811"
	Name="Example (custom)"
	Description="Stores information about example records (custom)"
	Author="Technical Training"
	Tablename="USR_EXAMPLE"
	IsBuiltIn="false"
	>

  <Fields>
    <TextField Name="SHORTNAME" Length="10"/>
    <TextField Name="LONGNAME" Length="20"/>
    <MemoField Name="DESCRIPTION"/>
    <DecimalField Name="RATING" />
  </Fields>

</TableSpec>
```
The spec created by the wizard is configured for three fields: FIELD1, FIELD2, and FIELD3. The data types for these: nvarchar(10), nvarchar(20), and nvarchar(max) correspond to the data types established by the platform for SHORTNAME, LONGNAME, and DESCRIPTION when the example Table Spec is loaded. Therefore, in the Add Data Form Spec, FIELD1, FIELD2, and FIELD3 can be changed to SHORTNAME, LONGNAME, and DESCRIPTION. For now, just change those in the Transact-SQL embedded in SaveImplementation.

Note: It is easier to edit Transact-SQL in an editor that validates and provides assistance for the language. For example, you can open a query editor in SQL Server Management Studio that is tied to a Blackbaud Infinity database. Once you have created the CREATE PROCEDURE statement, you can paste it into the spec.

Firstly adjust the parameters in each stored procedure such that these:

  @ID uniqueidentifier,
  @DATALOADED bit = 0 output,
  @FIELD1 nvarchar(10) = null output,
  @FIELD2 nvarchar(20) = null output,
  @FIELD3 nvarchar(max) = null output

Become:

  @ID uniqueidentifier,
  @DATALOADED bit = 0 output,
  @SHORTNAME nvarchar(10) = null output,
  @LONGNAME nvarchar(20) = null output,
  @DESCRIPTION nvarchar(max) = null output

And secondly adjust the SELECT statement. Change the field names and the table name.

This:

  select  @DATALOADED = 1,
          @FIELD1 = FIELD1,
          @FIELD2 = FIELD2,
          @FIELD3 = FIELD3
  from dbo.TABLE1
  where ID = @ID

Becomes:

  select  @DATALOADED = 1,
          @SHORTNAME = SHORTNAME,
          @LONGNAME = LONGNAME,
          @DESCRIPTION = DESCRIPTION
  from dbo.USR_EXAMPLE
  where ID = @ID

In those same places, add the decimal parameter and field.

create procedure dbo.USR_USP_DATAFORMTEMPLATE_VIEW_EXAMPLE
(
  @ID uniqueidentifier,
  @DATALOADED bit = 0 output,
  @SHORTNAME nvarchar(10) = null output,
  @LONGNAME nvarchar(20) = null output,
  @DESCRIPTION nvarchar(max) = null output,
  @RATING decimal = null output
)
as
	set nocount on;
	
	-- be sure to set this, in case the select returns no rows
	set @DATALOADED = 0;
	
	-- populate the output parameters, which correspond to fields on the form.  Note that
	-- we set @DATALOADED = 1 to indicate that the load was successful.  Otherwise, the system
	-- will display a "no data loaded" message.
  select  @DATALOADED = 1,
          @SHORTNAME = SHORTNAME,
          @LONGNAME = LONGNAME,
          @DESCRIPTION = DESCRIPTION,
          @RATING = RATING
  from dbo.USR_EXAMPLE
  where ID = @ID
	
	return 0;

Adjust FormMetaData as follows. These form fields map to the parameters in the save implementation. FormMetaData is discussed in Form Metadata.

  <common:FormMetaData>
    <common:FormFields>

      <common:FormField FieldID="SHORTNAME"
                        Caption="Short name"
                        DataType="String"
                        MaxLength="10" />

      <common:FormField FieldID="LONGNAME"
                        Caption="Long name"
                        DataType="String"
                        MaxLength="20" />

      <common:FormField FieldID="DESCRIPTION"
                        Caption="Description"
                        DataType="String" />

      <common:FormField FieldID="RATING"
                        Caption="Rating"
                        DataType="Decimal"
                        MinValue="0"
                        MaxValue="10" />

    </common:FormFields>
  </common:FormMetaData>

Save the spec, load it, and open it. The Table Spec must also be loaded. To access the data form, you can create a task to open the form. For development, you can use LoadSpec. For CLR forms, the assembly must also be copied to vroot\bin. For deployments, you can use the Catalog Browser.

LoadSpec

How is the Infinity Platform Extended and Customized?

For a Translation Function Spec and a Search List Spec to support opening this View Data Form, see Translation Function Spec and Search List Spec.