Create an Edit Data Form (SP)

This task walks through steps to create a new Edit 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 Edit 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 > Edit Data Form Template Spec (SP).
From Name, enter a name such as Example.Edit.xml or Example.Sp.Edit.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 EditDataFormTemplate 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_editdataformtemplate" xmlns:common="bb_appfx_commontypes" ID="cac61459-93e8-40ff-8346-785279a9accb"
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 Edit 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 Edit Data Form" Description="A data form for editing example records" Author="Technical Training"
To:
Name="Example Edit Data Form (custom)" Description="A data form for editing 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="cd7dd1e0-a7b8-4904-8d25-9a8a5b5f4b66"
The last three 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" FormHeader="Add an example"
To:
RecordType="Example (custom)" common:SecurityUIFolder="Example (custom)" FormHeader="Add an example"
Within the SPDataForm element, LoadImplementation and SaveImplementation are stubbed-out. Load implementations are discussed in Load Implementations. Save implementations are discussed in Save Implementations. These stubbed implementations assume three fields. In the load implementation, 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, @TSLONG bigint = 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:

Load implementation parameters

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

Save implementation parameters

	@ID uniqueidentifier,
	@CHANGEAGENTID uniqueidentifier = null,
	@FIELD1 nvarchar(10),
	@FIELD2 nvarchar(20),
	@FIELD3 nvarchar(max)

Become:

Load implementation parameters

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

Save implementation parameters

	@ID uniqueidentifier,
	@CHANGEAGENTID uniqueidentifier = null,
	@SHORTNAME nvarchar(10),
	@LONGNAME nvarchar(20),
	@DESCRIPTION nvarchar(max)

And secondly adjust the SELECT and UPDATE statements in the load implementation and save implementation respectively. Change the field names and the table name.

This:

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

Becomes:

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

And this:

	update dbo.TABLE1
	set FIELD1 = @FIELD1,
		FIELD2 = @FIELD2,
		FIELD2 = @FIELD3,
		CHANGEDBYID = @CHANGEAGENTID,
		DATECHANGED = @CURRENTDATE
	where ID = @ID

Becomes:

	update dbo.USR_EXAMPLE
	set SHORTNAME = @SHORTNAME,
		LONGNAME = @LONGNAME,
		DESCRIPTION = @DESCRIPTION,
		CHANGEDBYID = @CHANGEAGENTID,
		DATECHANGED = @CURRENTDATE
	where ID = @ID

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

Load implementation

create procedure dbo.USR_USP_DATAFORMTEMPLATE_EDITLOAD_EXAMPLE (
	@ID uniqueidentifier,
	@DATALOADED bit = 0 output,
	@TSLONG bigint = 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 these, in case the select returns no rows
set @DATALOADED = 0
set @TSLONG = 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.  Also note that we fetch the TSLONG so that concurrency
-- can be considered.
select @DATALOADED = 1,
	@TSLONG = TSLONG,
	@SHORTNAME = SHORTNAME,
	@LONGNAME = LONGNAME,
	@DESCRIPTION = DESCRIPTION,
  @RATING = RATING
from dbo.USR_EXAMPLE
where ID = @ID

return 0;

Save implementation

create procedure dbo.USR_USP_DATAFORMTEMPLATE_EDIT_EXAMPLE (
	@ID uniqueidentifier,
	@CHANGEAGENTID uniqueidentifier = null,
	@SHORTNAME nvarchar(10),
	@LONGNAME nvarchar(20),
	@DESCRIPTION nvarchar(max),
  @RATING decimal
	)
as
set nocount on;

if @CHANGEAGENTID is null
	exec dbo.USP_CHANGEAGENT_GETORCREATECHANGEAGENT @CHANGEAGENTID output

declare @CURRENTDATE datetime

set @CURRENTDATE = getdate()

begin try
	-- handle updating the data
	update dbo.USR_EXAMPLE
	set SHORTNAME = @SHORTNAME,
		LONGNAME = @LONGNAME,
		DESCRIPTION = @DESCRIPTION,
    RATING = @RATING,
		CHANGEDBYID = @CHANGEAGENTID,
		DATECHANGED = @CURRENTDATE
	where ID = @ID
end try

begin catch
	exec dbo.USP_RAISE_ERROR

	return 1
end catch

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 Edit Data Form, see Translation Function Spec and Search List Spec.