11 Days of Salesforce Storefront Reference Architecture (SFRA) — Day 5: Using Custom Preferences
Tags: sfcc, sfra, salesforce
Published: 2020-05-19 05:26:39

---
title: 11 Days of Salesforce Storefront Reference Architecture (SFRA) — Day 5: Using Custom Preferences
published: true
date: 2020-05-08 14:41:37 UTC
tags: sfcc,sfra,salesforce
series: 11 Days of Salesforce Storefront Reference Architecture (SFRA)
canonical_url: https://medium.com/perimeterx/11-days-of-salesforce-storefront-reference-architecture-sfra-day-5-using-custom-preferences-be93737e30d3
---

### 11 Days of Salesforce Storefront Reference Architecture (SFRA) — Day 5: Using Custom Preferences

![](https://cdn-images-1.medium.com/max/1024/1*6ngBZHLN4VRBKuyJ1xMD9Q.jpeg)<figcaption>Photo by <a href="https://unsplash.com/@louishansel?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Louis Hansel</a> on <a href="https://unsplash.com/s/photos/options?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Unsplash</a></figcaption>

Our new magic [cartridge](https://dev.to/pxjohnny/11-days-of-salesforce-storefront-reference-architecture-sfra-day-4-creating-a-basic-cartridge-5a93-temp-slug-4805464) is (hopefully) running as expected, however, it's kinda boring right now. It is preconfigured and our site admins cannot change anything on it without code. This is where Custom Preferences comes in. Custom Preferences enable developers (i.e us) to make properties for modules we develop (i.e cartridges) configurable in the Business Manager!

### Creating The Custom Preferences Group

The easiest way to create new Custom Preferences (we will discuss importing existing ones later) is through the Business Manager. Custom Preferences are created on a site (storefront) level and are then grouped under a Custom Preferences group. Accessing a site’s custom preferences is done in the Merchant Tools section of the Business Manager.

We will start by creating a new Custom Preferences group called **MagicConfig,** which will hold all the custom preferences objects related to the Magic Cartridge we created yesterday:

1. Open your Business Manager, select the RefArch site and navigate to **Merchant Tools** > **Site Preferences** > **Custom Preferences**.
2. Click on **New** to create a new Custom Preferences group.
3. Type **Magic\_Config** for the new group ID, **MagicConfig** as the name, and click  **Add**.
4. Refresh the Custom Site Preference Groups page and you should see the new **MagicConfig** group ** 🎉**

![](https://cdn-images-1.medium.com/max/1024/1*CFwtIaU9WeaLim3z8sYYMQ.png)<figcaption>MagicConfig is now part of the Custom Site Preference Groups</figcaption>

### Adding a New Attribute

A custom preference group consists of different attributes that represent an object. SFCC allows an attribute to be part of two types of objects: **System** and **Custom**. A **system** object allows you to add attributes to a site-wide object that is later used in your storefront. Such objects can be Product, Coupon, Invoice, etc. In addition, **System** objects can also contain attributes for Site Preferences or a Service Profile. For our cartridge, we would like to add a Custom Preference that allows the site admin to set the background color for the cartridge template without needing to edit it directly or redeploy it. Any attribute that describes a Site Preference will be defined for the Site Preferences object.

To add a custom preference attribute to the Site Preferences object:

1. Open your Business Manager and navigate to **Administration** > **System Object Types**.
2. In the System Object Type List look for **SitePreferences** and click on it.
3. Here you can see a summary of this object type, including its description, customization support, and more:

![](https://cdn-images-1.medium.com/max/1024/1*6VuHR5EmfkumvBSkN90tHg.png)

> 🐘 If an object does not support customization, we will not be able to add new attributes to it or edit its grouping.

4. Click on the **Attribute Definitions** tab.

5. The list shown is of all of the attributes currently defined for the Site Preferences object. Click on the **New** button in the bottom right corner to add a new attribute.

6. Fill in the following and click  **Apply** :

- **ID** : MagicBackground
- **Display Name** : Magic Cartridge Background Color
- **Help Text** : A hexadecimal color value for the Magic cartridge background color.
- **Value Type** : String

7. You’ll now see the Attribute Definition Details page where you can set additional properties to the new attribute.

Congratulations! You just created your first attribute 🎊

### Populating MagicConfig

Like T. S. Eliot said “Home is where one starts from,” each of our attributes must be associated with a home. or rather, a Custom Preference group. As such, before we can use our new background color attribute, we need to bind it to a group.

1. Open your Business Manager and navigate to **Administration** > **System Object Types**.
2. In the System Object Type List look for **SitePreferences** and click on it.
3. Click on the **Attribute Grouping** tab.
4. Here you should see the **Magic_Config** group we created earlier. Under the **Attributes** column, click on  **Edit:**

![](https://cdn-images-1.medium.com/max/1024/1*q475-D74B5PJUgo_OchmwA.png)<figcaption>The Magic_Config Edit button is located under the Attributes column on the right side</figcaption>

5.In the ID text box type **MagicBackground** and click **Add**. This will bind the attribute to the group, enabling us to actually use it!

### Adding Support for MagicBackground in ISML

We are done setting up our custom attribute in the Business Manager but before we can actually use it we need to add support for it in our Magic Cartridge template.

1. Open the magic.isml template, located at thetemplates/default folder.
2. Under the **style** element add the following snippet:

{% gist https://gist.github.com/pxjohnny/7b32532c56ebf8780a47d657f89981f4.js %}

- isprint — an element that allows us to specify a value to display.
- The value of isprint — As you might have noticed we used a dynamic variable for the value of isprint: dw.system.Site.current.preferences.custom.MagicBackground. What does this big scary line mean?  
- **dw.system**  — namespace of the object where the **Site** object resides  
- **Site**  — an object referencing a storefront.  
- **current**  — an object referencing the current site (storefront) the user is on.  
- **preferences**  — an object referencing the site’s preferences.  
- **custom**  — an object referencing the custom preferences object of the general site preferences.  
- **MagicBackground**  — the ID of our custom attribute.
- encoding — The encoding type the element will use for its value.

3.Upload the changes to SFCC by runningnpm run uploadCartridge from the root folder of the cartridge.

### Go Wild 🌈

We are now ready to test our new custom attribute!

1. Open your Business Manager, select the RefArch site and navigate to **Merchant Tools** > **Site Preferences** > **Custom Preferences**.
2. Click on **Magic\_Config.** Here you will meet the custom attribute we created earlier for the background color **.**
3. Enter a value for the color, for example, **#000** , and click  **Save**.
4. Navigate back to the Magic controller (if you need a refresher on the URL, have a look at [Day 4](https://dev.to/pxjohnny/11-days-of-salesforce-storefront-reference-architecture-sfra-day-4-creating-a-basic-cartridge-5a93-temp-slug-4805464)) and watch the magic!

![](https://cdn-images-1.medium.com/max/1024/1*Bk8hykOmfYvTGfrZQtI7IQ.png)

![](https://cdn-images-1.medium.com/max/1024/1*jGg6zEJ5rZc6uJdGMkYraQ.png)<figcaption>Before and after shots (the default background is white)</figcaption>

And there you have it, a custom preference attribute that allows the storefront admin to change the background color of our custom cartridge without needing to use code or deployment 🎉

If you are now thinking “Johnny, that is awesome and all, but I want to call outside sources from my cartridge to get or send data!” then patience, young grasshopper **,** come back tomorrow to meet the Services Framework.

As always, looking forward to your comments either here or on [Twitter](https://twitter.com/fullstackj) 😎

* * *