ParameterSection Element

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

Starting with version 4.0, you can include the ParameterSection element on page specs to pass parameters from UI widgets to list builders. Previously, this element was already available on page specs to pass parameters from UI widgets to other UI widgets or data lists.

The ParameterSection element allows you to create UI widgets and list builders that work together to update the list builders based on parameters from the widgets. When users select or enter data in the widgets, the program passes that data to the corresponding list builders and then updates the lists.

On page specs, you insert the ParameterSection element within the ListBuilder element and then provide a GUID in the ID attribute for the UI widget section that passes parameters to the list builder. Next, you insert the FieldMappings element and its child FieldMapping element to map a field from the UI widget the list builder. To map additional fields, you can include additional FieldMapping elements.

Within the FieldMapping element, you specify the widget field that provides the parameter value in the ParameterField element, and then you specify the list builder field that receives the value in the DestinationField element.

<ParameterSection ID="c3b173fa-9697-403c-9008-8ef5a4b34f60">
 <FieldMappings>
  <FieldMapping>
   <ParameterField>SPECIFY_SOURCE_FIELD_FROM_UIWIDGET</ParameterField>
   <DestinationField>SPECIFY_TARGET_FIELD_IN_LISTBUILDER</DestinationField>
  </FieldMapping>
</ParameterSection>

In Blackbaud CRM, this functionality is in place on the Information library page where you manage queries and KPIs. On the left side of the page, a view form widget displays folders to organize queries and KPIs. And on the right, a list builder displays the queries or KPIs in the selected folder.

When users select a folder in the widget, the widget passes a parameter for that folder to the list builder, which then filters the list based on the parameter. The Information library page uses the ParameterSection element to pass these parameters from the widget to the list builder so that users can filter the list based on selections in the widget.

In Design Mode, you can view the XML for this page to see how this is implemented. On the Information library page, toggle Design Mode on and click View XML at the top of the page.

Within the Tab element for the Queries tab, the first Section element creates a section to display the widget. The Section element's ID attribute provides a GUID to identify the section, while the child UIWidget element's ID attribute provides a GUID for the UI widget to display in the section. The ParemeterSection element's ID attribute requires the first GUID for the UI widget section, not the second GUID for the UI widget itself.

<Tabs>
 <Tab Caption="Queries" ID="4fff8057-0b45-4759-b150-e5afc1194314" CaptionResourceKey="$$queries" LayoutUrl="browser/htmlforms/platform/informationlibrary/informationlibraryquerieslayout.html">
  <Sections>
   <Section ID="c3b173fa-9697-403c-9008-8ef5a4b34f60" HideRefresh="true">
    <UIWidget ID="431cb61b-f957-4e25-9f9c-65d80999d5dd" AutoHeight="true" />
    <Actions>
     <Action ID="702b86c4-82ba-4f84-ae3a-f4889a8d40f3" Caption="Manage folders" ImageKey="CATALOG:Blackbaud.AppFx.Platform.Catalog,Blackbaud.AppFx.Platform.Catalog.folder_gear_16.png" CaptionResourceKey="$$manage_folders">
      <ShowDataForm DataFormID="954a9c40-79c7-4f83-aac5-532359a1bec9" xmlns="bb_appfx_commontypes">
       <PostActionEvent>
        <RefreshPage />
       </PostActionEvent>
      </ShowDataForm>
     </Action>
    </Actions>
   </Section>

The second Section element within the Tab element creates a section to display the list builder. In this section, the ListBuilder element includes the child ParameterSection element, and that element's ID attribute provides the GUID for the widget section that passes parameters to the list builder. As you can see below, this GUID matches the GUID from the first Section element's ID attribute.

Within the ParameterSection element, the FieldMappings element contains the child FieldMapping elements that map fields from the UI widget to the list builder. The first FieldMapping element's ParameterField element indicates that the widget's NODEID field provides a parameter value, while the corresponding DestinationField element indicates that the list builder's NODEID field receives that value. Meanwhile, the second FieldMapping element's ParameterField element indicates that the widget's GROUPBY field provides a parameter value, while the corresponding DestinationField element indicates that the list builder's GROUPBY field receives that value.

   <Section ID="ea7ad125-fb7d-42e0-a6f1-f5107eea0764" Caption="Queries" CaptionResourceKey="$$queries">
    <ListBuilder QueryViewID="2043b264-918e-4c28-8b6c-250b62b0106b" AutoDisplayFilters="true" AllowSave="false" AllowCancel="true">
     <RequiredColumns>
      <Column Name="ID" />
      <Column Name="ISFAVORITE" />
      <Column Name="QUERY_TYPE" />
      <Column Name="ISBROWSABLE" />
      <Column Name="MOBILIZE" />
      <Column Name="OWNERID" />
      <Column Name="USERCANEDIT" />
      <Column Name="OTHERSCANMODIFY" />
      <Column Name="GROUPEDBY" />
     </RequiredColumns>
     <RenderStyle>
      <StandardView>
       <DetailViewForm ViewDataFormID="d1400925-8a10-4796-83eb-15573c50ab56" />
      </StandardView>
     </RenderStyle>
     <ParameterSection ID="c3b173fa-9697-403c-9008-8ef5a4b34f60">
      <FieldMappings>
       <FieldMapping>
        <ParameterField>NODEID</ParameterField>
        <DestinationField>NODEID</DestinationField>
       </FieldMapping>
       <FieldMapping>
        <ParameterField>GROUPBY</ParameterField>
        <DestinationField>GROUPBY</DestinationField>
       </FieldMapping>
      </FieldMappings>
     </ParameterSection>
    </ListBuilder>

Tip: For another example of how to implement the ParameterSection element for list builders, seeUse ParameterSection Element to Pass a Parameter from Widget to a List Builder.