Use ParameterSection Element to Pass a Parameter from Widget to a List Builder

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

The ParameterSectionelement allows you to set up UI widgets and list builders that work together by passing parameters from the widgets to update the list builders.

This element is useful for scenarios where you want to allow users to filter list builders based on values that they enter in widgets, and the Kitchen Sink includes a sample to illustrate how the element works.

To view the sample, go to the Kitchen Sink and click List builder under List builder. On the List Builderpage, select the UIWidget Parameter Section tab to view a widget that passes a parameter to a list builder.

In the UI Widget section's Min age widget fields, you can enter a minimum age. When you click Apply, the widget passes the value that you entered to the list builder, and the List Builder section filters the list to only display entries if the values in the Age column that are greater than the minimum age from the widget.

On the page spec for the List Builderpage, the Tabs element includes two Tab elements for the Standard ListBuilder tab and the UIWidget Parameter Section tab. Within the second Tab element, the Sections element includes two Section elements, one for the UI Widget section and one for the List Builder section.

In this first Section element, the 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 to identify the source of the parameter value, not the second GUID for the UI widget itself.

<Tab ID="5B64D7D7-ED72-4142-B985-37CB5C7298FC" Caption="UIWidget Parameter Section">
 <!-- define the sections for this tab -->
 <Sections>
  <Section ID="9BEA1E81-D527-4248-92EA-6ADB49D0B1CF" Caption="UI Widget">
   <UIWidget ID="C668E54F-E7FB-4600-8367-35F7E372341F"></UIWidget>
  </Section>

Within the second Section element, the ListBuilder element defines the list builder for the section, and its child ParameterSection element specifies the parameter to pass from the UI widget to the list builder.

  <Section ID="D2F41F19-69C4-4B9D-AAA3-748D6EC71032" Caption="List Builder"> 
   <ListBuilder QueryViewID="b902bd80-2cef-4362-acce-8f7e776439ee" AutoDisplayFilters="true" >
    <RenderStyle>
     <StandardView>
     </StandardView>
    </RenderStyle>
    <ParameterSection ID="9BEA1E81-D527-4248-92EA-6ADB49D0B1CF" HideOwnFilters="true">
     <FieldMappings>
      <FieldMapping>
       <ParameterField>MINAGE_WIDGET</ParameterField>
       <DestinationField>MINAGE</DestinationField>
      </FieldMapping>
     </FieldMappings>
    </ParameterSection>
   </ListBuilder>
  </Section>
 </Sections>
</Tab>

In the ParameterSection element, the ID attribute provides the GUID from the ID attribute for the UI Widget section to indicate the source of the parameter to pass to the list builder. Meanwhile, the HideOwnFilters attribute is set to "true" to hide the standard filters in the UI Widget section.

Next, the FieldMappings element contains the FieldMapping element to map a field from the UI widget to the list builder.

Within the FieldMapping element, the ParameterField element specifies the widget field that provides a parameter value, and the DestinationField element specifies the list builder field that receives the value. In the Kitchen Sink sample, the widget's MINAGE_WIDGET field provides the value from the UI widget while the list builder's MINAGE field receives the value for the list builder.

Tip: For more information about the ParameterSection element for list builders, see ParameterSection Element.