October 2, 2010

Editing Custom Labels in Force.com IDE !

Custom Labels are key to create multilingual Salesforce apps. Developers usually move their page/class to Custom Labels in two steps

  1. The first cut of the page/class is developed using hard coded English labels & messages. This helps in speeding up development time, as switching between IDE & “Custom Label” UI, for each label and message for sure slows development speed.
  2. In second cut, developers usually scan all the pages and classes for any hardcoded English labels/messages. Custom Label is created for each such hardcoded label/message and replacements are done with the Custom Label full api name.

Though this approach speeds the development time, still I feel creating custom labels from UI is time consuming. So to save time, I suggest use Force.com IDE(Eclipse) to directly update/create new labels, and replace the hard coded English text.

How to get Custom Labels in Force.com IDE ?

By default Custom Labels are not downloaded into Force.com project. How to get custom labels into your project depends, if

  • You are creating a new force.com project, or
  • You’re working on existing force.com project

Getting Labels in New Force.com Projects !

In new Force.com project wizard, after entering login/pass you will land up on following screen. Select second option “Selected metadata components:” and hit “Choose” button, this will open a dialog to select metadata components.

 image

In the next dialog, together with classes, pages, resources & triggers etc, make sure “CustomLabels” is selected as shown below. Selecting “CustomLabels” will download them to your force.com project.

image

After completing the above wizard, you will see new source folder named “labels” in your force.com project, as shown below (in red circle). Notice, their is new XML resource named “CustomLabels.labels” in  your force.com project. This is the one, we will use for editing/creating custom labels.

image 

Getting Labels in Existing Force.com Projects !

In case you already working on a force.com project, you can still get “Custom Labels” resource in your project. Here are the steps

  1. Go to Navigator or Project/Package Explorer and right click the force.com project to which you want to add Custom Labels.
  2. In the popup menu, select Force.com and in the next sub-popup menu select “Add/remove metadata components”, as shown below: image
  3. In the next dialog, hit “Add/Remove” button to open the Metadata Selection Dialog image 
  4. Again, as with new force.com project, ensure that “labels”>”CustomLabels” is selected. As shown below:image
  5. On completing this and next dialogs, you will be prompted for project refresh(as shown below). Hit “Yes” button image
  6. After completing the above wizard, you will see new source folder named “labels” in your force.com project, as shown below (in red circle). Notice, their is new XML resource named “CustomLabels.labels” in  your force.com project. This is the one, we will use for editing/creating custom labels.

    image 

Manipulating Labels from Force.com IDE !

To start open the resource “CustomLabels.labels” in Force.com IDE. You will see XML editor with all your custom labels. For demoing in this post, I previously created one custom label from UI, so my XML looks like this :

<?xml version="1.0" encoding="UTF-8"?>
<CustomLabels xmlns="http://soap.sforce.com/2006/04/metadata">
    <labels>
        <fullName>foo_screen_title</fullName>
        <categories>titles</categories>
        <language>en_US</language>
        <protected>true</protected>
        <shortDescription>foo screen title</shortDescription>
        <value>My FOO Screen Title</value>
    </labels>
</CustomLabels>

As you can see this XML structure is pretty simple, you will get a <labels> tag per Custom Label. The key attributes here are

  • Full Name : This is used in API like Visualforce($Label.foo_screen_title) and Apex(System.Label.foo_screen_title) for referring the custom label. You can change this value, by editing text inside the <fullName>…</fullName> tag.
  • Value  : This is the default value displayed for custom label. You can change this value, by editing text inside <value>…</value> tag

Edit custom labels via Force.com IDE

To edit you can change any value inside of the <labels> tag. Once you are done, save CustomLabels.labels file to replicate the changes in your org.

Note : Changing <fullName> of existing label, will create a new label for that name.

Create new custom labels via Force.com IDE

For ex. if I need a new custom label named “bar_screen_title” with value “My BAR Screen Title”, I can just copy the “foo_screen_title” <labels> XML tag from above example and create a new one with attributes required, as shown below :

<?xml version="1.0" encoding="UTF-8"?>
<CustomLabels xmlns="http://soap.sforce.com/2006/04/metadata">
    <labels>
        <fullName>foo_screen_title</fullName>
        <categories>titles</categories>
        <language>en_US</language>
        <protected>true</protected>
        <shortDescription>foo screen title</shortDescription>
        <value>My FOO Screen Title</value>
    </labels>
    <labels>
        <fullName>bar_screen_title</fullName>
        <categories>titles</categories>
        <language>en_US</language>
        <protected>true</protected>
        <shortDescription>bar screen title</shortDescription>
        <value>My BAR Screen Title</value>
    </labels>
</CustomLabels>

Just save this XML file to replicate the new labels in your Salesforce org.

Note

  • Refresh the CustomLabels.labels resource, before making any change and after saving this file. Salesforce re-organizes the xml some times, so its good to always work on latest from Salesforce.
  • If you haven’t created any Custom Labels, you will get no <labels> tag to use as template in “CustomLabels.labels” resource. So I recommend creating at least one via salesforce web interface.

Benefits of having Custom Labels in Force.com IDE !

  • You can text search the “CustomLabels.labels” xml with IDE. Searching for required labels and peeking into details is time consuming on web interface.
  • You can edit/create labels and copy the full api names quickly to your Visualforce and Apex code.
  • Easy to copy multiple labels quickly from one Org to other. You can just open the labels xml file for both org and do a cross org copy/paste of labels easily.
  • Its much faster the web interface to work on labels, specially changing and creating multiple labels at once.

 

Have more thoughts and tips/tricks on this topic, please comment !!