List Component

Component Attributes

The ListComponent has the following attributes.

Embed ListComponent on a Visualforce Page

The following are the requirements you need to comply when embedding the ListComponent on a Visualforce page:

• The ListComponent includes an attribute, options, which is an instance of the ListComponentOptions class that specifies the component configuration. The ListComponentOptions object must be built in an Apex class that is the controller (or extension) of the page containing the ListComponent.
• jQuery is used for DOM manipulation and UI behaviors. To avoid conflicts with other JavaScript libraries that use the jQuery default "$" variable on the page, the ListComponent calls jQuery.noConflict() and assigns the "$jq" as the variable shortcut to the jQuery() method.
• The component must be placed within the <apex:form> and </apex:form> tags, and any buttons or other UI elements that call the ListComponentController's global methods must be inside the same form container as the component.
• The component is defined with the layout="none" option, so the component should be wrapped in block-level HTML elements, such as <div> or <td>. 
• The data table is rendered with a basic HTML table structure, and it does not use Visualforce tags like <apex:pageBlockTable> or <apex:dataTable>. This allows for simpler overriding of the table CSS.

Access the ListComponentController Instance

In the ParentController virtual class, there is a virtual method called registerController. This method is called by the ListComponentController after it has completed its initialization. It can be overriden in your page controller to receive each instance of the ListComponentController that is on your page. The method takes both a ListComponentController and a String parameter, the value of the instanceName options. It is recommended that you store the ListComponentController instances in a map keyed by the instanceName.

ListComponetController ​Plug-Ins

The ListComponentController exposes the following interface classes that can be implemented to handle actions a user can perform with the ListComponent:

• Query
• Selection Handling
• Update
• Post-update
• Exception

The concrete implementations of these interfaces are placed in your page controller (or any other class) and their names are passed to the ListComponentOptions object as Strings at runtime. 

In addition to other parameters, each of the plug-in methods takes an instance of ListComponentController.ParentController. When the plug-in methods are called, this parameter is passed to the parentController option from the ListComponentOptions object that your controller passed into the ListComponent. This gives your plug-in implementation access to all of the publicly-accessible methods and properties of your page controller. 

ListComponentController Global Methods and Properties

By default, the ListComponent provides a number of UI features that can be displayed or hidden via the ListComponentOptions class properties, or optionally used in your own UI:

• a pagination-based navigation interface for paging through records
• a row of buttons for the "edit", "inlineEdit", "multiSelect", and "singleSelect" modes
• a search box and buttons, rendered above the data table by default

The ListComponentController methods for these features are exposed globally so that they can be called by custom Visualforce UI controls.

// This example assumes that there is a Visualforce page that has this class as its controller or extension, 
// and that page embeds the ListComponent.
public class MyListClass extends ListComponentController.ParentController {
  public ListComponentOptions theOptions { get; set; }
  private Map<String,ListComponentController> listControllerMap; 

  public MyListClass() {
    this.theOptions = new ListComponentOptions();
    this.theOptions.objectName = 'Account';
    this.theOptions.fieldSetName = 'ListTest';
    this.theOptions.parentController = this;
    this.theOptions.instanceName = 'MyList';
    listControllerMap = new Map<String,ListComponentController>();
  }

  public override void registerController(ListComponentController lcc, String instanceName) {
    this.listControllerMap.put(instanceName, lcc);
  }

  public PageReference nextPage() {
    ListComponentController lcc = this.listControllerMap.get(this.theOptions.instanceName);
    return lcc.next();
  }
}

Custom CSS Notes

• "listComponent" is the default value for the instanceName option. When using multiple list components on a page, the instanceName value you give to each one will replace "listComponent" in the markup.
• Data rows (<tr>) in the table have an element id in the format {instanceName}:{record id}.
• Data cells (<td>) in the table have an element id in the format {instanceName}:{record id}:{field name}.
• In the "edit" mode, input controls inside each of the data cells are rendered automatically by Salesforce based on the underlying data type, using the apex:inputField tag. For example, text fields are rendered as <input type="text" ...>.
• The row containing the "defaultButtonCell" is not rendered when the hideActionButtons and hidePaginationNav options are set to true.
• The row containing the "defaultSearchCell" is not rendered when the hideSearch option is set to true.

Custom JavaScript Notes

Use the jQuery CSS selector pattern matching (http://api.jquery.com/category/selectors/) to manipulate elements, bind events to specific data cells, or bind events to groups based on the element id. For example:

• In a ListComponent using a field set from the Account object where the AnnualRevenue field is included, to bind to all AnnualRevenue text boxes:​
  • jQuery("[id$='\\:AnnualRevenue']").children(":input[type=text]");
• In a ListComponent using a field set from the Account object where the Industry field is included, to bind to all Industry select elements (picklists):
  • jQuery("[id$='\\:Industry']").children("select");

ListComponent Markup Structure

<div class="listComponentPanel" id="listComponent:listComponentPanel">
  <table class="outerTable" id="listComponent:outerTable">
    <tbody>
      <tr>
        <td id="listComponent:defaultSearchCell" style="text-align: right;">
          <!-- default search box and buttons, can be hidden via the list component options -->
        </td>
      </tr>

      <tr id="listComponent:dataGridRow">
        <td>
          <table class="innerTable bPageBlock" id="listComponent:innerTable">
            <thead>
              <tr>
                <th class="textField">Account ID</th>
                <th class="textField">Account Name</th>
                <th class="numericField">Annual Revenue</th>
                <th class="numericField">Created Date</th>
                <!-- additional fields -->
              </tr>
            </thead>

            <tbody>
              <tr class="dataRow" id="listComponent:001i0000008Oah1AAC">
                <td class="dataCell textField readOnly" id="listComponent:001i0000008Oah1AAC:Id"><!-- data, etc. --></td>
                <td class="dataCell textField" id="listComponent:001i0000008Oah1AAC:Name"><!-- data, etc. --></td>
                <td class="dataCell numericField" id="listComponent:001i0000008Oah1AAC:AnnualRevenue"><!-- data, etc. --></td>
                <!-- additional fields -->
              </tr>
              <!-- more data rows -->
            </tbody>

          </table>
        </td>
      </tr>

      <tr>
        <td id="listComponent:defaultButtonCell" style="text-align: center;">
          <!-- default pagination navigation and update/submit buttons, can be hidden via a ListComponent option -->
        </td>
      </tr>
    </tbody>
  </table>
</div>