Simple Data Lists Overview
A simple data list is a query-driven drop-down list box. In its most basic form, a simple data list consists of a stored procedure implementation to retrieve a value, label pair to be rendered as a drop-down list box as part of a form field within the user interface.
<SimpleDataListSpec
xmlns="bb_appfx_simpledatalist"
xmlns:common="bb_appfx_commontypes"
ID="bd0f0cc1-cc60-42e2-b592-f000b4fdfbf4"
Name="Food Item Simple Data List"
Description="Simple data list for food items."
Author="Technical Training">
<SPSimpleList SPName="USR_USP_SIMPLEDATALIST_FOODITEM">
<common:CreateProcedureSQL >
<![CDATA[
create procedure dbo.USR_USP_SIMPLEDATALIST_FOODITEM as
select
ID as VALUE,
NAME as LABEL
from
dbo.USR_FOODITEM
order by
NAME
]]>
</common:CreateProcedureSQL>
</SPSimpleList>
</SimpleDataListSpec>
Utilize a Simple Data List within a Form Field Collection
In the example below, we utilize the Food Item Simple Data List within a collection of form fields.
Below are the form fields for the data form with the simple data list highlighted in yellow within the collection.
<c:FormMetaData FixedDialog="true">
<c:FormFields>
<c:FormField FieldID="CONSTITUENTID" Caption="Constituent" Description="The food bank either receives food donations from this constituent or distributes food to this constituent." DataType="Guid" Required="true">
<c:SearchList SearchListID="23c5c603-d7d8-4106-aecc-65392b563887" EnableQuickFind="true" />
</c:FormField>
<c:FormField FieldID="FOODBANKTXTYPECODE" DataType="TinyInt" Caption="Transaction Type" Description="Enter Receive if the food bank is receiving a donation from the constituent. Enter Distribute if the food bank is distributing food to the constituent in need." DefaultValueText="0" Required="true">
<c:ValueList>
<c:Items>
<c:Item>
<c:Value>0</c:Value>
<c:Label>Receive</c:Label>
</c:Item>
<c:Item>
<c:Value>1</c:Value>
<c:Label>Distribute</c:Label>
</c:Item>
</c:Items>
</c:ValueList>
</c:FormField>
<c:FormField FieldID="TXDATE" DataType="Date" Required="true" Caption="Transaction Date" />
<c:FormField FieldID="RECEIPTPRINTED" DataType="Boolean" Caption="Receipt Printed" />
<c:FormField FieldID="FOODITEMS" DataType="XML" Caption="Food Items">
<c:Collection>
<c:Fields>
<c:FormField FieldID="FOODITEMID" Caption="Food item" DataType="Guid">
<c:SimpleDataList SimpleDataListID="bd0f0cc1-cc60-42e2-b592-f000b4fdfbf4" />
</c:FormField>
<c:FormField FieldID="FOODITEMAMOUNT" Caption="Amount" DataType="Money" />
<c:FormField FieldID="QUANTITY" Caption="Quantity" DataType="Integer" />
</c:Fields>
</c:Collection>
</c:FormField>
</c:FormFields>
<c:WebUIComponent>
<c:UIModel AssemblyName="Blackbaud.CustomFx.FoodBank.UIModel.dll" ClassName="Blackbaud.CustomFx.FoodBank.UIModel.FoodBankTransactionHeaderAddForm2UIModel" />
<c:WebUI>
<c:ExternalResource Url="browser/htmlforms/custom/blackbaud.customfx.foodbank/FoodBankTransactionHeaderAddForm2.html" />
</c:WebUI>
</c:WebUIComponent>
<c:UIFields>
<c:FormField FieldID="ADDFOODITEMLABEL" Caption ="Add Food Item" ReadOnly="true" DataType="String"/>
</c:UIFields>
<c:UIActions>
<c:UIAction ActionID="ADDFOODITEM" Caption="+" Description="Add Food Item">
<c:ShowAddForm DataFormInstanceID="b911e219-42f2-4b64-9f02-d9e2ff899799" />
</c:UIAction>
</c:UIActions>
</c:FormMetaData>Parameters within a Simple Data List
Simple data lists can contain a Parameters tag (yellow highlight below), which include form field metadata that maps to parameters within the logic within the simple data list (green highlights). The form fields listed within a Parameters tag typically map to the form fields where the simple data list resides.
STATE ABBREVIATION LIST (SIMPLE DATA LIST)
<?xml version="1.0" encoding="utf-16"?>
<SimpleDataListSpec xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" ID="7fa91401-596c-4f7c-936d-6e41683121d7" Name="State Abbreviation List" Description="Returns abbreviations for all states for the given country (or all countries if no country supplied)." Author="Blackbaud Product Development" TranslationFunctionID="12040dba-4ff1-47d0-a1b0-fc40b7627d0f" NoSecurityRequired="true" xmlns="bb_appfx_simpledatalist">
<DependencyList xmlns="bb_appfx_commontypes">
<Dependency CatalogAssembly="Blackbaud.AppFx.Platform.Catalog.dll" CatalogItem="Blackbaud.AppFx.Platform.Catalog.UFN_STATE_GETABBREVIATION.xml" />
</DependencyList>
<SPSimpleList SPName="USP_SIMPLEDATALIST_STATE_ABBREVIATION">
<CreateProcedureSQL xmlns="bb_appfx_commontypes">
create procedure dbo.USP_SIMPLEDATALIST_STATE_ABBREVIATION
(
@INCLUDEINACTIVE bit = 0,
@COUNTRYID uniqueidentifier = null,
@USEDEFAULTCOUNTRY bit = 1
) as
set nocount on;
if @COUNTRYID is null and @USEDEFAULTCOUNTRY = 1
exec @COUNTRYID = dbo.UFN_COUNTRY_GETDEFAULT;
select
ID as VALUE,
ABBREVIATION as LABEL
from dbo.STATE
where (ACTIVE = 1 or @INCLUDEINACTIVE = 1) and (COUNTRYID = @COUNTRYID or @COUNTRYID is null)
order by ABBREVIATION
</CreateProcedureSQL>
</SPSimpleList>
<LookupView ViewName="V_SIMPLEDATALIST_STATE_ABBREVIATION">
<ViewSQL>
select ABBREVIATION [LABEL] from dbo.STATE where ACTIVE = 1;
</ViewSQL>
</LookupView>
<Parameters>
<FormMetaData xmlns="bb_appfx_commontypes">
<FormFields>
<FormField FieldID="INCLUDEINACTIVE" DataType="Boolean" Caption="Include inactive" DefaultValueText="0" />
<FormField FieldID="COUNTRYID" DataType="Guid" Caption="Country" />
<FormField FieldID="USEDEFAULTCOUNTRY" DataType="Boolean" Caption="Use default country" DefaultValueText="1" />
</FormFields>
</FormMetaData>
</Parameters>
</SimpleDataListSpec>
Web API
Simple data lists can also be used by one of the Infinity Web APIs to retrieve a simple list of data. The AppFxWebService.asmx can manipulate simple data lists. For an example of how to use an out-of-the-box simple data list with one of the Blackbaud.AppFx.*.WebAPIClient.dll, see Blackbaud.AppFx.*.WebAPIClient.dlls.