Working with Field Sets

You can use dynamic bindings to display field sets on your Visualforce pages. A field set is a grouping of fields. For example, you could have a field set that contains fields describing a user’s first name, middle name, last name, and business title. If the page is added to a managed package, administrators can add, remove, or reorder fields in a field set to modify the fields presented on the Visualforce page without modifying any code. Field sets are available for Visualforce pages on API version 21.0 or above. You can have up to 50 field sets referenced on a single page. An sObject can have up to 2,000 field sets.

Each field set can have up to 25 fields through lookup relationships. Fields can only span one level away from the entity.

Note

Working with Field Sets Using Visualforce

Field sets can be directly referenced in Visualforce by combining the $ObjectType global variable with the keyword FieldSets. For example, if your Contact object has a field set called properNames that displays three fields, your Visualforce page can reference the field data through the following iteration:

1<apex:page standardController="Contact">
2    <apex:repeat value="{!$ObjectType.Contact.FieldSets.properNames}" var="f"> 
3        <apex:outputText value="{!Contact[f]}" /><br/>
4    </apex:repeat>
5</apex:page>

You can also choose to render additional information, such as field labels and data types, through the following special properties on the fields in the field set:

Property Name	Description
`DBRequired`	Indicates whether the field is required for the object
`FieldPath`	Lists the field’s spanning info
`Label`	The UI label for the field
`Required`	Indicates whether the field is required in the field set
`Type`	The data type for the field

For example, you can access the labels and data types for the fields in properNames like this:

1<apex:page standardController="Contact">
2    <apex:pageBlock title="Fields in Proper Names">
3        <apex:pageBlockTable value="{!$ObjectType.Contact.FieldSets.properNames}" var="f">
4            <apex:column value="{!f}">
5                <apex:facet name="header">Name</apex:facet>
6            </apex:column> 
7            <apex:column value="{!f.Label}">
8                <apex:facet name="header">Label</apex:facet>
9            </apex:column> 
10            <apex:column value="{!f.Type}" >
11                <apex:facet name="header">Data Type</apex:facet>
12            </apex:column> 
13        </apex:pageBlockTable> 
14    </apex:pageBlock> 
15</apex:page>

If this Visualforce page is added to a managed package and distributed, subscribers can edit the properNames field set. The logic for generating the Visualforce page remains the same, while the presentation differs based on each subscriber’s implementation. To reference a field set from a managed package, you must prepend the field set with the organization’s namespace. Using the markup above, if properNames comes from an organization called Spectre, the field set is referenced like this:

1{!$ObjectType.Contact.FieldSets.Spectre__properNames}

Working with Field Sets Using Apex

Fields in a field set are automatically loaded when your Visualforce page uses a standard controller. When using a custom controller, you need to add the required fields to the SOQL query for the page. Apex provides two Schema objects that allow you to discover field sets and the fields they contain, Schema.FieldSet and Schema.FieldSetMember. For information about these two system classes, see the Lightning Platform Apex Code Developer’s Guide.

Sample: Displaying a Field Set on a Visualforce Page

This sample uses Schema.FieldSet and Schema.FieldSetMember methods to dynamically get all the fields in the Dimensions field set for the Merchandise custom object. The list of fields is then used to construct a SOQL query that ensures those fields are available for display. The Visualforce page uses the MerchandiseDetails class as its controller.

1public with sharing class MerchandiseDetails {
2
3    public Merchandise__c merch { get; set; }
4    
5    public MerchandiseDetails() {
6        this.merch = getMerchandise();
7    }
8
9    public List<Schema.FieldSetMember> getFields() {
10        return SObjectType.Merchandise__c.FieldSets.Dimensions.getFields();
11    }
12
13    private Merchandise__c getMerchandise() {
14        String query = 'SELECT ';
15        for(Schema.FieldSetMember f : this.getFields()) {
16            query += f.getFieldPath() + ', ';
17        }
18        query += 'Id, Name FROM Merchandise__c LIMIT 1';
19        return Database.query(query, AccessLevel.USER_MODE);
20    }
21}

The Visualforce page using the above controller is simple:

1<apex:page controller="MerchandiseDetails">
2    <apex:form >
3
4      <apex:pageBlock title="Product Details">
5          <apex:pageBlockSection title="Product">
6              <apex:inputField value="{!merch.Name}"/>
7          </apex:pageBlockSection>
8      
9          <apex:pageBlockSection title="Dimensions">
10              <apex:repeat value="{!fields}" var="f">
11                  <apex:inputField value="{!merch[f.fieldPath]}" 
12                      required="{!OR(f.required, f.dbrequired)}"/>
13              </apex:repeat>
14          </apex:pageBlockSection>
15  
16        </apex:pageBlock>
17
18    </apex:form>  
19</apex:page>

One thing to note about the above markup is the expression used to determine if a field on the form should be indicated as being a required field. A field in a field set can be required by either the field set definition, or the field’s own definition. The expression handles both cases.

Field Set Considerations

Fields added to a field set can be in one of two categories:

The order in which a developer lists displayed fields determines their order of appearance on a Visualforce page.

As a package developer, keep the following best practices in mind:

Subscribers with installed field sets can add fields that your page didn’t account for. There is no way to conditionally omit some fields from a field set iteration, so make sure that any field rendered through your field set works for all field types.
We recommend that you add only non-essential fields to your field set. This ensures that even if a subscriber removes all fields in the field set, Visualforce pages that use that field set still function.

Field sets are available for Visualforce pages on API version 21.0 or above.

Note

See Also