Salesforce Custom Labels

Custom labels can be a powerful ally for your code. I have only recently started incorporating them into my code as a best practice.

When custom labels were first released they provided a means to allow custom text to be translated for multi-lingual support. That still is their primary function and many times when scoping a project one of the questions asked is do we need to support multiple languages. Mainly because there is a cost in time and resources in order to make sure that you have proper custom labels defined and that the translations are implemented and tested.

For the most part the team has only been asked to support english. However, I have always found hard coding the text displayed to users in my code to be wrong. It just feels wrong. In my head as I am coding the text string my conscience is telling me I shouldn't be doing this.

I have tried in the past to use a custom object which worked really well but it meant coding an object that knew how to read the custom labels and there was a performance hit in terms of having to query the labels. Now, much of the performance hit can be avoided by using a singleton design pattern that only queries the labels once which is the basic implementation behind custom labels but you lose out on what makes custom labels so valuable.

The Pros:

• Code base is prepared for multi-lingual support. If you work for a global or enterprise company you should expect that one day you will need to support multiple languages
• Common error messages or help text can be reused
• Ability to use a label in Apex Code and Visualforce Pages
• Allows the text to be maintained by a system administrator rather than a developer
• Data integrity is enforced if a delete attempt is made on the label and it is referenced by a Visualforce page or Apex Code
• Readability of code and pages is improved by the use of custom label properties

The Cons:

• Salesforce.com instance must have the Translation Workbench enabled
• Increased time to develop and coordinate with development team to ensure that custom labels are not used inappropriately
• Limit of 1,000 characters and up to 5,000 custom labels. If developing for a large org you must take care to ensure the labels are manageable and utilized

I am sure that you may have some other pros and cons concerning custom labels and I welcome any suggests but the above are what come to mind at the moment. So now on to some tips should you decide that custom labels is for you.

Naming Custom Labels

Naming custom labels can be pretty stressful. You want to choose a name that properly represents the text yet is not long winded so that you are not typing a sentence every time you attempt to use the label on your pages or code. While I haven't centered on a naming convention just yet (or ever) I did decide on some basic rules:

• Avoid using unnecessary prefixes such as the name of classes or pages that use the label. This should allow your labels to be more accessible for re-use
• Use underscores to space out keywords, which will make the text more readable in your code and pages.
• Try to stay under four words to name your custom label. You may have instances where you need more but four words should be plenty to provide context
• Use categories to group your labels rather than attempting to group labels by name

Using Custom Labels

There isn't anything complicated about using custom labels. They are really easy to reference and they won't eat up your query limits if you happen to implement a custom solution.

One particular use case that is heavy on my mind is providing text to be displayed that needs to include information that is gathered at runtime. For instance, you might have a custom error message that instructs the user to contact support or maybe you are returning an error that indicates an error with a value or specific field. You could assume that you will always append the additional text at the end of the custom label message but that isn't always grammatically correct and can vary from language to language.

So the technique that I have centered on to solve for this is to make use of the string.format method. This method allows you to create a format pattern that will allow you to inject your variables in a specific area of the string.

For example:

The value you entered for field '{0}' is incorrect. Please correct this value and try again.

As you may notice there is a special character string that will be replaced with the text that you specify in code or in an outputText field. Here is an example of how to do that:

string.format(System.Label.My_Custom_Label, new string[] {'Account Name'});

As you may have noticed the format method takes an array of strings. This allows you to replace multiple values in a format string.

For instance, you may define a text string as:

The value '{0}' is not valid for field {1}'

Where the numbers represent the index of the string in the array. So the following code would yield the text:

The value 'My value' is not valid for field Account Name"

string.format(System.Label.My_Custom_Label, new string[] {'My value', 'Account Name'});

Let me know if you have any pros, cons, or other suggestions or tips when using custom labels.