Custom Label Design Guidelines

Custom Label Design Guidelines provide standards for whether you should create custom labels or edit/override existing custom labels. It also provides standards on clearly naming new custom labels. Custom labels are primarily used for messages, heading text, and description text on pages and cards in Community Hub.

When to Create a New Custom Label

If you are creating new Community Hub components, such as buttons and cards, you can go to the Custom Labels area of Setup and verify there is not already a custom label that contains the text you need. If there is no custom label that meets your need, you should create a new one.

Even if there is a custom label that contains the text you need, you can still consider creating a new one. Any time you decide to use an existing custom label, consider where it is already used and if it is likely to be changed later. Changing the text of a custom label affects all the places in Community Hub that reference that custom label. As an administrator, you have to determine the right balance of centralization when it comes to custom labels.

Examples:

• If the International Society for the Exceptionally Nimble has a branded name for one of their pages, such as "ISEN Portal", this is an ideal application of using a custom label across many components because, if the Marketing team decides to rebrand that page to "My ISEN," the administrator can easily update one custom label, and all buttons, cards, and page names referencing that text are updated. Since the old name, "ISEN Portal," is being phased out completely, it is safe to replace it for all components referencing it. 
• If you decide to use the existing "Submit" custom label on a new page, and then later override the "Submit" custom label text to "Finish" so it reads better on one of your other pages, you have now changed the text of multiple "Submit" buttons across Community Hub. The new term, "Finish," may not make sense in certain contexts. In this case, it's better to create a new custom label called "Finish" instead of overriding "Submit."

View a List of Components Using a Custom Label

When determining if you should use an existing custom label or create a new one, it is helpful to know which Community Hub components are using that custom label:

1. From Setup, enter Custom Metadata Types in the Quick Find box, then select Custom Metadata Types.

2. Click the name of the custom metadata type that matches the Community Hub component you want to review (Ex: Button).
3. Click Create New View.
4. Enter a View Name such as All with Custom Label.

5. Move Label from Available Fields to Selected Fields. There might be two Label fields. If so, include both (one is the component's label, which is typically already selected, and the other is the custom label).

   

   Optionally, you can also add a filter that filters on Label, just be sure to select the correct Label field.

6. Click Save.

7. In the list view, sort by the custom Label, find your custom label, and review which components are also using it.

When to Override a Custom Label  

Since a custom label can be referenced by multiple Community Hub components, be careful when overriding one.

Being aware of all components that use a custom label, and confident that you want to make that change in all those places, you should override the custom label. This is especially true of custom labels that are in a packaged app,  since they are not directly editable.

If you need to change a custom label that is not in a managed package, you can directly edit that custom label's Short Description and Value instead of overriding the label. This is the recommended approach for administrators.

If administrators have delegated management of label overrides to staff, however, custom label overrides is a viable option.

Whether you are an administrator or not, you can never edit the custom label's Name, which serves as the API name in Salesforce. Instead, create a new custom label and then remap all of your components to use the new custom label.

Naming

For custom labels, we recommend entering a Short Description in title case and Name in Pascal case with the format:

Pascal case excludes special characters, so the hyphen should only be included in the Short Description, not in the Name.

Specifically:

• For [value or short description], enter a value depending on the amount of text in the custom label's Value:
  • if Value is a single word or short phrase, enter the exact text entered in Value. For example, if Value is My ISEN, then also set Short Description to My ISEN.
  • If Value is long form text such as a sentence or paragraph, enter a short summary of the label's purpose. For example, if Value is Welcome to My ISEN, where you can view your membership status and manage profile information, then set Short Description to a brief summary such as My ISEN Page Description.
• For [- additional descriptor], which is optional, enter a hyphen followed by information that clarifies the usage of the custom label. This is particularly useful if the [value or short description] does not clearly identify where this custom label is used and there are similarly named custom labels. For example, if the International Society for the Exceptionally Nimble has a custom label with the Value I Agree and the administrator wants to clearly indicate to staff this custom label is used exclusively on their Volunteer Agreement page in Community Hub, the custom label's Short Description can be I Agree - Volunteer Agreement.

In Categories, you can optionally enter comma-separated words or phrases. This provides additional context about how or where the custom label is used, and can be used in list view filters. For example, all custom labels used on a My Volunteering page can have a category of My Volunteering if it is helpful to manage all My Volunteering custom labels in a custom list view.