Create an Add Data Form (SP)

This task walks through steps to create a new Add 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 Add Data Form (SP) Spec is shown in the steps.

1. From an existing Blackbaud AppFx Catalog Project, right-click the project and select Add > New Item. The Add New Item screen appears.

2. Select Blackbaud AppFx Catalog > Add Data Form Template Spec (SP).

3. From Name, enter a name such as Example.Add.xml or Example.Sp.Add.xml.

   

4. Click Add. The new spec appears in Solution Explorer and in the XML Editor.

   In the spec that appears in the XML Editor...

5. Leave the first three attributes of AddDataFormTemplate 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_adddataformtemplate"
     xmlns:common="bb_appfx_commontypes"
     ID="ef868a58-167b-407c-91c4-68da2d3f6991"

6. 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 Add 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 Add Data Form"
     Description="A data form for adding example records" 
     Author="Technical Training"

   To:

     Name="Example Add Data Form (custom)"
     Description="A data form for adding example records"
     Author="Technical Training"

7. 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="c46afaa2-a2b6-4d29-ad4d-1e8cf94984bd" 

8. 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"

9. Within the SPDataForm element, LoadImplementation and SaveImplementation are stubbed-out. This example will omit the LoadImplementation. To follow along, delete LoadImplementation from the spec. A walk-through for LoadImplementation is included in the task for creating an Edit Data Form (SP) and load implementations are discussed in Load Implementations. Save implementations are discussed in Save Implementations.

   The stubbed out SaveImplementation assumes three fields and a CONTEXTID. This example will omit the CONTEXTID, adjust the three fields, and add one more. Context is discussed in Context.

   Delete the @CONTEXTID parameter from the CREATE PROCEDURE parameters. There is another deletion related to this elsewhere in the spec. That will be discussed later.

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

10. 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.

11. Firstly adjust the parameters for the stored procedure such that this:

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

    Becomes:

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

12. And secondly adjust the INSERT statement such that this:

    	insert into dbo.TABLE1 (
    		ID,FIELD1,FIELD2,FIELD3,ADDEDBYID,CHANGEDBYID,DATEADDED,DATECHANGED
    		)
    	values (
    		@ID,@FIELD1,@FIELD2,@FIELD3,@CHANGEAGENTID,@CHANGEAGENTID,@CURRENTDATE,@CURRENTDATE
    		)

    Becomes:

    	insert into dbo.TABLE1 (
    		ID,SHORTNAME,LONGNAME,DESCRIPTION,ADDEDBYID,CHANGEDBYID,DATEADDED,DATECHANGED
    		)
    	values (
    		@ID,@SHORTNAME,@LONGNAME,@DESCRIPTION,@CHANGEAGENTID,@CHANGEAGENTID,@CURRENTDATE,@CURRENTDATE
    		)

13. Also adjust the table name in the INSERT statement to match the table name for the example table:

    insert into dbo.TABLE1 becomes insert into insert into dbo.[USR_EXAMPLE]

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

    create procedure dbo.USR_USP_DATAFORMTEMPLATE_ADD_EXAMPLE (
    	@ID uniqueidentifier = null output,
    	@CHANGEAGENTID uniqueidentifier = null,
    	@SHORTNAME nvarchar(10) = '',
    	@LONGNAME nvarchar(20) = '',
    	@DESCRIPTION nvarchar(max) = '',
    	@RATING decimal = 0
    	)
    as
    
    set nocount on;
    
    if @ID is null
    	set @ID = newid()
    
    if @CHANGEAGENTID is null
    	exec dbo.USP_CHANGEAGENT_GETORCREATECHANGEAGENT @CHANGEAGENTID output
    
    declare @CURRENTDATE datetime
    
    set @CURRENTDATE = getdate()
    
    begin try
    	-- handle inserting the data
    	insert into dbo.[USR_EXAMPLE] (
    		ID,SHORTNAME,LONGNAME,DESCRIPTION,RATING,ADDEDBYID,CHANGEDBYID,DATEADDED,DATECHANGED
    		)
    	values (
    		@ID,@SHORTNAME,@LONGNAME,@DESCRIPTION,@RATING,@CHANGEAGENTID,@CHANGEAGENTID,@CURRENTDATE,@CURRENTDATE
    		)
    end try
    
    begin catch
    	exec dbo.USP_RAISE_ERROR
    
    	return 1
    end catch
    
    return 0

15. Context is declared after SaveImplementation. Remember that @CONTEXTID was removed from the parameters in the stubbed-out CREATE PROCEDURE. Remove the Context section also. Context is discussed in Context.

16. 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>

17. 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 guidance about how to create a task to open an Edit Data Form, see Create a Task to Open an Edit Data Form.