Force.com Apex Code Developer's Guide
j
No Results
Search Tips:
- Please consider misspellings
- Try different search keywords
Newer Version Available
Custom Settings Methods
Custom settings are similar to custom
objects and enable application developers to create custom sets of
data, as well as create and associate custom data for an organization,
profile, or specific user. All custom settings data is exposed in
the application cache, which enables efficient access without the
cost of repeated queries to the database. This data can then be used
by formula fields, validation rules, Apex, and the SOAP API.
Usage
Custom settings methods are all instance methods, that is, they are called by and operate on a particular instance of a custom setting. There are two types of custom settings: hierarchy and list. The methods are divided into those that work with list custom settings, and those that work with hierarchy custom settings.
For more information on creating custom settings in the Salesforce user interface, see “Custom Settings Overview” in the Salesforce online help.
Custom Setting Examples
The following example uses a list custom setting called Games. Games has a field called GameType. This example determines if the value of the first data set is equal to the string PC.
1List<Games__C> mcs = Games__c.getall().values();
2boolean textField = null;
3if (mcs[0].GameType__c == 'PC') {
4 textField = true;
5}
6system.assertEquals(textField, true);The following example uses a custom setting from Country and State Code Custom Settings
Example. This example demonstrates that the getValues and getInstance methods list custom setting
return identical values.
1swfobject.registerObject("clippy.codeblock-1", "9");Foundation_Countries__c myCS1 = Foundation_Countries__c.getValues('United States');
2String myCCVal = myCS1.Country_code__c;
3Foundation_Countries__c myCS2 = Foundation_Countries__c.getInstance('United States');
4String myCCInst = myCS2.Country_code__c;
5system.assertEquals(myCCinst, myCCVal);Hierarchy Custom Setting Examples
In the following example, the hierarchy custom setting GamesSupport has a field called Corporate_number. The code returns the value for the profile specified with pid.
1GamesSupport__c mhc = GamesSupport__c.getInstance(pid);
2string mPhone = mhc.Corporate_number__c;The following example shows how to use hierarchy custom settings methods. For getInstance, the example shows how field values that aren't set for a specific user or profile are returned from fields defined at the next lowest level in the hierarchy. The example also shows how to use getOrgDefaults.
Finally, the example demonstrates how getValues returns fields in the custom setting record only
for the specific user or profile, and doesn't merge values from other
levels of the hierarchy. Instead, getValues returns null for any fields
that aren't set. This example uses a hierarchy custom setting called
Hierarchy. Hierarchy has two fields: OverrideMe and DontOverrideMe. In addition, a user named
Robert has a System Administrator profile. The organization, profile,
and user settings for this example are as follows:
- Organization settings
- OverrideMe: Hello
- DontOverrideMe: World
- Profile settings
- OverrideMe: Goodbye
- DontOverrideMe is not set.
- User settings
- OverrideMe: Fluffy
- DontOverrideMe is not set.
The following example demonstrates the result of the getInstance method if Robert calls
it in his organization:
1Hierarchy__c CS = Hierarchy__c.getInstance();
2System.Assert(CS.OverrideMe__c == 'Fluffy');
3System.assert(CS.DontOverrideMe__c == 'World');If Robert passes his user ID specified by RobertId to getInstance, the results are the same.
This is because the lowest level of data in the custom setting is
specified at the user level.
1Hierarchy__c CS = Hierarchy__c.getInstance(RobertId);
2System.Assert(CS.OverrideMe__c == 'Fluffy');
3System.assert(CS.DontOverrideMe__c == 'World');If Robert passes the System Administrator profile ID specified by SysAdminID to getInstance, the result is different.
The data specified for the profile is returned:
1Hierarchy__c CS = Hierarchy__c.getInstance(SysAdminID);
2System.Assert(CS.OverrideMe__c == 'Goodbye');
3System.assert(CS.DontOverrideMe__c == 'World');When Robert tries to return the data set for the organization using getOrgDefaults, the result is:
1Hierarchy__c CS = Hierarchy__c.getOrgDefaults();
2System.Assert(CS.OverrideMe__c == 'Hello');
3System.assert(CS.DontOverrideMe__c == 'World');By using the getValues method,
Robert can get the hierarchy custom setting values specific to his
user and profile settings. For example, if Robert passes his user
ID RobertId to getValues, the result is:
1Hierarchy__c CS = Hierarchy__c.getValues(RobertId);
2System.Assert(CS.OverrideMe__c == 'Fluffy');
3// Note how this value is null, because you are returning
4// data specific for the user
5System.assert(CS.DontOverrideMe__c == null);If
Robert passes his System Administrator profile ID SysAdminID to getValues, the result is:
1Hierarchy__c CS = Hierarchy__c.getValues(SysAdminID);
2System.Assert(CS.OverrideMe__c == 'Goodbye');
3// Note how this value is null, because you are returning
4// data specific for the profile
5System.assert(CS.DontOverrideMe__c == null);Country and State Code Custom Settings Example
This example illustrates using two custom setting objects for storing related information, and a Visualforce page to display the data in a set of related picklists.
In the following example, country and state codes are stored in two different custom settings: Foundation_Countries and Foundation_States.
The Foundation_Countries custom setting is a list type custom
setting and has a single field, Country_Code.
The Foundation_States custom setting is also a List type
of custom setting and has the following fields:
- Country Code
- State Code
- State Name
The Visualforce page shows two picklists: one for country and one for state.
1swfobject.registerObject("clippy.codeblock-9", "9");<apex:page controller="CountryStatePicker">
2 <apex:form >
3 <apex:actionFunction name="rerenderStates" rerender="statesSelectList" >
4 <apex:param name="firstParam" assignTo="{!country}" value="" />
5 </apex:actionFunction>
6
7 <table><tbody>
8 <tr>
9 <th>Country</th>
10 <td>
11 <apex:selectList id="country" styleclass="std" size="1"
12 value="{!country}" onChange="rerenderStates(this.value)">
13 <apex:selectOptions value="{!countriesSelectList}"/>
14 </apex:selectList>
15 </td>
16 </tr>
17 <tr id="state_input">
18 <th>State/Province</th>
19 <td>
20 <apex:selectList id="statesSelectList" styleclass="std" size="1"
21 value="{!state}">
22 <apex:selectOptions value="{!statesSelectList}"/>
23 </apex:selectList>
24 </td>
25 </tr>
26 </tbody></table>
27 </apex:form>
28</apex:page>
29The Apex controller CountryStatePicker finds the values entered into the custom settings, then returns
them to the Visualforce page.
1swfobject.registerObject("clippy.codeblock-10", "9");public with sharing class CountryStatePicker {
2
3// Variables to store country and state selected by user
4 public String state { get; set; }
5 public String country {get; set;}
6
7 // Generates country dropdown from country settings
8 public List<SelectOption> getCountriesSelectList() {
9 List<SelectOption> options = new List<SelectOption>();
10 options.add(new SelectOption('', '-- Select One --'));
11
12 // Find all the countries in the custom setting
13 Map<String, Foundation_Countries__c> countries = Foundation_Countries__c.getAll();
14
15 // Sort them by name
16 List<String> countryNames = new List<String>();
17 countryNames.addAll(countries.keySet());
18 countryNames.sort();
19
20 // Create the Select Options.
21 for (String countryName : countryNames) {
22 Foundation_Countries__c country = countries.get(countryName);
23 options.add(new SelectOption(country.country_code__c, country.Name));
24 }
25 return options;
26 }
27
28 // To generate the states picklist based on the country selected by user.
29 public List<SelectOption> getStatesSelectList() {
30 List<SelectOption> options = new List<SelectOption>();
31 // Find all the states we have in custom settings.
32 Map<String, Foundation_States__c> allstates = Foundation_States__c.getAll();
33
34 // Filter states that belong to the selected country
35 Map<String, Foundation_States__c> states = new Map<String, Foundation_States__c>();
36 for(Foundation_States__c state : allstates.values()) {
37 if (state.country_code__c == this.country) {
38 states.put(state.name, state);
39 }
40 }
41
42 // Sort the states based on their names
43 List<String> stateNames = new List<String>();
44 stateNames.addAll(states.keySet());
45 stateNames.sort();
46
47 // Generate the Select Options based on the final sorted list
48 for (String stateName : stateNames) {
49 Foundation_States__c state = states.get(stateName);
50 options.add(new SelectOption(state.state_code__c, state.state_name__c));
51 }
52
53 // If no states are found, just say not required in the dropdown.
54 if (options.size() > 0) {
55 options.add(0, new SelectOption('', '-- Select One --'));
56 } else {
57 options.add(new SelectOption('', 'Not Required'));
58 }
59 return options;
60 }
61}