List Component

Overview

The List component is used to present the user with a list of records returned by a Data Set. Refreshing the data set will refresh the list.

List component capabilities

  • Display a list of records
  • Display any fields in any order
  • Make any column of the list sortable by the end user
  • Make any column clickable
  • Optionally, configure a reference field to be updated with the ID of the clicked record whenever an item is clicked
    • Choose either a virtual reference field, or a real reference field from a data set that returns a single parent record of all the list items.
  • Optionally, if updating a non-virtual reference field, configure a “New Item” button to create a new record for the list and link it to the parent record
  • Optionally, define conditions for display of the “New Item” button, if configured
  • Optionally and separately for each column, configure an internal or external URL to which the user will be redirected on click of an item in that column
  • Optionally, configure parameters with dynamic or static values to be embedded into the above URLs upon redirect
  • Optionally, configure conditions under which list items are clickable

List Component Functionality Description

Optionally, when a list item is clicked, a reference (lookup) field is updated with the ID of the selected record. This reference field may be either a Virtual reference field or a data set reference field in a data set containing the parent of the list items.

This reference field can be used to control (refresh) a separate data set that can return any record(s) that reference the ID of the clicked record. For example, you can use a list to set a virtual field that refreshes a data set that returns the selected record with any number of its fields, or to refresh a data set that returns child records of the selected record. For example, clicking on an item in a list of Contact records can set a virtual field that will refresh a second data set displayed as a list of Notes attached to the selected Contact, or a list of the selected contact’s EDA relationships, or of the Contact’s CampaignMemberships, or any other sObject that looks up to the clicked item.

  • Virtual reference fields refresh data sets very quickly, without refreshing the page, when a list item is clicked. They can be used to quickly display a list of records related to the list item that was clicked.
  • Data set reference fields refresh the entire page when a list item is clicked, and are therefore slower.

Once a record is chosen, a reference (lookup) field is updated. This allows Data Sets which reference this reference field in their criteria to be filtered by the selected record.

The component must be placed in a one column section.

List Component Configuration Controls

When you drag a list component onto a page and double click to open the List Configuration dialog, you configure it as follows.

Left Column Controls

  1. Source Data Set Name: Choose the data set which contains the records to be listed.
  2. Fields Displayed in Table: After you choose the data set, the fields from that data set appear in this section. Select fields from the data set to display as columns in the list of records.
  3. Selected Fields: When you have chosen fields, you may set Custom Labels for each field, which will be a column in the list table.
  4. Sort: You can order the columns of the list table by moving the selected fields up and down with the arrows under the SORT heading. Click on a field to select it, then click one of the arrows to move it up or down.
  5. Custom Label: You can label each column in the list.
  6. F) Sort Column: A check in this checkbox on the Selected Fields table will enable the end user to sort the list on this column by clicking the arrow next to it in the column header.
  7. G) Clickable Field: Checking this box on any field will make it a clickable field. When the user clicks an item in this column, then the “Target Field to Update” will be updated (see below).
  8. H) Clickable Configuration: You may click this button on any clickable column to configure the optional redirect that will take place on clicking. In the dialog that opens, choose whether the redirect will be internal or external; if you choose Internal, then you can choose from a dropdown any of the Env’s pages; if you choose external, then you must type in a URL. Optionally, you may configure parameters to be passed with the redirect URL; you can choose to put any field from any data set into a parameter; if you use a field from the Source Data Set (A, above) then the parameter value will come from the item (record) clicked. if you don’t configure the redirect, then when the user clicks this column, there will be no redirect, but the “Target Field to Update” will always be updated when any field is clicked.
  9. I) Descriptive Text: Enter instructional text which will appear above the list of Child records.
  10. J) Description (Admin): For reference by administrators. Explain the role the lIst component plays on the page for the benefit of your successor admins.
  11. K) Clickability: You can make the clickability of the list items conditional on criteria. You can use the Source Data Set to refer in your conditions to the field values of each item (record) in the list.
  12. L) List Button Rendered: Set conditions under which the “Create New Application” button will be visible. Only the Child object data set will be available. The criteria that is chosen is applied to all records in the Data Set. For example, if the criteria is the following:
    • Data set: Application
    • Criteria Field: Admissions Status
    • Operator: equals
    • Value: File Closed

    Then the button will only appear if all Application (child) records have an Admissions Status value of File Closed. If one or more are not in that status, the button will not render.

  13. Rendered: Set conditions for rendering the entire component.

Right Column Controls

Clickable Field Behavior group

  1. Target Data Set to update — Choose either:
    • The "Virtual Field" data set, or
    • A data set that is a parent object of the Source Data Set (A, above) and that contains a reference field that looks up to an item in the list (the “selected” child record)
  2. O) Target Field to Update: — Choose either:
    • A Virtual reference field that looks up to the same sObject as the Source Data Set (A, above) , or
    • A real (non-virtual) reference field in the parent data set, which will be updated with the ID of the record that the user clicks in the list

    Create New Record Configuration group

    Available only if a real (non-Virtual) reference field is chosen in “Target Field to Update” (O, above) These fields are optional as a group: you can leave them all blank, or you can fill them all in.

  3. Master/Related Object Field: Select the Child object field which looks up to the Parent object.
  4. "Create New" Button Label: Specify the label of the button which will create a Child object record.
  5. "Create New" Button URL: Specify the url of the page where the Create New Application button should redirect to. A forward slash (/) can be used if no redirection is needed. Use a relative URL, because the url will automatically include your base Salesforce domain name and community, for example:https://formbuilderrx.na30.force.com/TestCommunity/apex/

    Relative page URLs can be quickly retrieved from the Page Builder tab by clicking the Copy URL icon beside the page name.

Example Updating a Real (non-virtual) Reference Field

Consider the ERx Core data model that has a Contact with multiple child Application records that lookup to it. A lookup to Application on the Contact, in turn, specifies the single Active Application Record. This is the application that will be displayed on the pages of the Community. The List component presents the user with a list of Applications. When an application is clicked, the Active Application Record field on the Contact updates to reference this new application, which will now also be referenced on all the pages.

In this example, since there are many Applications to one Contact, we would refer to the Applications as the Child object and the Contact as the Parent object.

Before creating this component, there should be two data sets created. First, there should be a child object data set on the Application sObject which contains the fields you want to display on the list of Application records, including the field that looks up to the parent Contact object. Any Child object field configured as a lookup to the Parent object may be referenced for use in this component, but normally this would be the Application’s Applicant field. Be sure that the record Criteria(s) for this data set are set to retrieve all of the records that need to be listed on the page, that is, all the applications that belong to the logged in Contact/Portal User.

Secondly, there should be a Parent object (Contact) data set which must contain a lookup to the Child object designating the active or selected child record; any Parent object field configured as a lookup to the Child object may be used, but normally this would be the Contact’s Active Application Record” field.

Here is how your List Configuration would look:

Note that the Academic Program column is configured to redirect to a page showing detailed information on the program. Therefore the “Clickable Configuration” dialog for Academic Program looks like this:

Example Updating a Virtual Reference Field

Consider the EDA data model, where the Contact can have multiple Relationship records looking up to it. You would like to display a list of the logged in Contact’s relationships and when the user clicks on a relationship, you would like to display beneath the list, various fields of information from the Relationship record. You display the related contact’s name in one of the list columns and when the user clicks a name, they are redirected to a page that displays many fields of data from the related Contact record.

In this case, to populate the list, you will need a data set on sObject EDA Relationship to return all of the logged in Contact’s relationship records. The list’s columns might display the values of these Relationship fields: Relationship Key, Related Contact, Relationship Type, Relationship Status. You will need to define a Virtual Field of type Reference that looks up to the EDA Relationship object, to be populated by the list component when the user clicks on a list item. This virtual field should be placed on the page but not rendered. It should be set to control another Data Set that retrieves the selected relationship record.

Your page will look like this: