Open topic with navigation

Make Search Criteria Persistent for a Search List

Version: This material pertains to version 3.0 of Blackbaud CRM SDK.

When you create a Search List Spec, you can now designate persistent search fields that will retain search criteria from previous searches when users return to the search screen. These persistent search fields allow the users to exit the search screen and then return later for another search without re-entering their previous search criteria.

To designate persistent fields, you insert the PersistentFields element near the end of the Search List Spec and then insert the new PersistentFieldID element to specify the fields.

For example, you can edit the Search List Spec that we created in Build a Search List (SP) Spec and a Translation Function Spec so that after users enter food bank names or select food bank types, these search criteria remain in place when they return to the screen.

Until you make the Name and Food Bank Type fields persistent, they are blank when users open the Food Bank Search screen.

To designate the search fields as persistent, open the FoodBanks.Search.xml spec that we created in Build a Search List (SP) Spec and a Translation Function Spec, and at the end of the spec, insert the PersistentFields and PersistentFieldID elements as illustrated in the following code sample.

	<PersistentFields>
		<PersistentFieldID>NAME</PersistentFieldID>
		<PersistentFieldID>FOODBANKTYPE</PersistentFieldID>
	</PersistentFields>

With these elements in place, the Name and Food Bank Type fields retain previous search criteria when users open the Food Bank Search screen. For example, if a user searches for food banks with "East" in the name and with a type of "Type 1," then the next time that user opens the Food Bank Search screen, those search criteria are already in place so that the user can just click Searchto see the search results again.

Note: A user's search criteria in persistent fields remains in place until the user clears the individual fields or clicks Clear to reset all search parameters.

Here is the complete Search List Spec with the persistent fields designated at the end:

<SearchListSpec 
    xmlns="bb_appfx_searchlist"
    xmlns:common="bb_appfx_commontypes"
    ID="3eceea4c-cf42-4938-9cf1-c7c77ebc7dc9"
    Name="Food Bank Search"
    Description="Search list for food banks."
    Author="Technical Training"
    RecordType="Food Bank"
    TranslationFunctionID="66d00b36-8c81-4327-84fa-3265e9888b29">

	<!-- describe the SP used to fetch the results from the given filters.  
  Note that the @MAXROWS parameter is required, and should be 
	used to limit the number of rows returned to a reasonable number. -->
	<SPSearchList SPName="USR_USP_SEARCHLIST_FOODBANK">
		<common:CreateProcedureSQL>
			<![CDATA[
create procedure dbo.USR_USP_SEARCHLIST_FOODBANK
(
	@NAME nvarchar(100) = null,
  @FOODBANKTYPE uniqueidentifier = null,
	@MAXROWS smallint = 500
)
as
	set @NAME = COALESCE(@NAME,'') + '%' ;
  /* set @FOODBANKTYPE = COALESCE(@FOODBANKTYPE,'') + '%' ; */

	select top(@MAXROWS)
		FB.ID,
		C.KEYNAME as NAME,
		FBTC.DESCRIPTION as FOODBANKTYPE
	from 
		dbo.CONSTITUENT C
	inner join
		dbo.USR_FOODBANK FB on C.ID = FB.CONSTITUENTID
	left join
		dbo.USR_FOODBANKTYPECODE FBTC on FB.FOODBANKTYPECODEID = FBTC.ID
	where
		 (C.KEYNAME like @NAME) 
     AND ((@FOODBANKTYPE is null) or (FBTC.ID = @FOODBANKTYPE))
	order by 
		C.NAME asc
			] ]>
		</common:CreateProcedureSQL>
	</SPSearchList>

	<!-- describe the filter fields for the search screen -->
	<common:FormMetaData>
		<common:FormFields>
			<common:FormField FieldID="NAME" Caption="Name" DataType="String" MaxLength="100" />
      <common:FormField FieldID="FOODBANKTYPE" Caption="Food Bank Type" MaxLength="100"  Required="true">
        <common:CodeTable CodeTableName="USR_FOODBANKTYPECODE"/>
      </common:FormField>
		</common:FormFields>

       

		<!-- indicate the client-side component for the filter user interface -->
		<!--<common:FormUIComponent FormUIComponentType="CustomComponent">
			<common:CustomComponentID AssemblyName="REPLACE_WITH_ASSEMBLYNAME" ClassName="REPLACE_WITH_FULLCLASSNAME" />
		</common:FormUIComponent>-->
    
    <!-- Switching over to the default WebUI instad of the Win Form UI for the filter user interface -->
    <common:WebUIComponent>
      <common:UIModel AssemblyName="Blackbaud.CustomFx.FoodBank.UIModel.dll" ClassName="Blackbaud.CustomFx.FoodBank.UIModel.FoodBankSearchUIModel" />
        <common:WebUI>
          <common:ExternalResource Url="browser/htmlforms/custom/blackbaud.customfx.foodbank/FoodBankSearch.html" />
      </common:WebUI>
    </common:WebUIComponent>
  </common:FormMetaData>

   <!-- also describe the output fields for the search screen -->
	<Output>
		<OutputFields>
			<OutputField FieldID="ID" Caption="ID" DataType="Guid" IsHidden="true" />
			<OutputField FieldID="NAME" Caption="Name" DataType="String" />
			<OutputField FieldID="FOODBANKTYPE" Caption="Type" DataType="String"  />
		</OutputFields>
	</Output>
			
	<PersistentFields>
		<PersistentFieldID>NAME</PersistentFieldID>
		<PersistentFieldID>FOODBANKTYPE</PersistentFieldID>
	</PersistentFields>

</SearchListSpec>