{"id":378,"date":"2021-03-25T20:22:44","date_gmt":"2021-03-26T04:22:44","guid":{"rendered":"http:\/\/www.antunkarlovac.com\/blog\/?p=378"},"modified":"2021-05-04T02:36:41","modified_gmt":"2021-05-04T10:36:41","slug":"using-custom-site-preferences-in-sfcc","status":"publish","type":"post","link":"https:\/\/www.antunkarlovac.com\/blog\/2021\/03\/25\/using-custom-site-preferences-in-sfcc\/","title":{"rendered":"Using Custom Site Preferences in SFCC"},"content":{"rendered":"

This is a guide for creating custom site preferences for use with Salesforce Commerce Cloud. Site preferences let users of Business Manger (BM) define settings that are used in code. For information visit\u00a0korucaredoula<\/a><\/span> .<\/p>\n

You can see available site preferences in Merchant Tools \/ Site Preferences \/ Custom Preferences<\/strong>. They are organized by groups (e.g. per cartridge).<\/p>\n

Creating New Preferences<\/strong>
\nFirst create a group for your set of preferences in BM by going to Merchant Tools \/ Site Preferences \/ Custom Preferences<\/strong> and clicking New<\/strong>. If you simply need to add a new preference to an existing group, skip this step.<\/p>\n

The next steps are a bit roundabout. Firstly, you have to go to Administration > Site Development > System Object Types<\/strong>, and select SitePreferences<\/strong> from the list. To add preference to your new group, for each one you’ll do the following:<\/p>\n

    \n
  1. First create the attribute: Select the Attribute Definitions<\/strong> tab, click New<\/strong>, and define your new site preference (attribute), then click Apply<\/strong>. Use an ID that will be unique, since that will be the identifier you use for your preference in code.<\/li>\n
  2. Then add it to your group: Go back to Site Preferences – Attribute Definitions<\/strong>, select the Attribute Grouping<\/strong> tab, find the group you created (it may be at the bottom of the list), and then click Edit<\/strong>. Search for your newly-created attribute, and click Add<\/strong>.<\/li>\n<\/ol>\n

    When you create the attribute, you can select the Value Type – boolean, string, date, enum, etc., and define options and select a default option, if applicable:<\/p>\n

    \"enum_options\"<\/p>\n

    Accessing Preferences in Code<\/strong>
    \nOnce you have defined your preference, you can access it in JavaScript like so:<\/p>\n

    \r\nvar System = require('dw\/system');\r\nvar site = System.Site.getCurrent();\r\nvar customPreferenceValue = site.getCustomPreferenceValue('myPreferenceID').getValue();\r\n<\/pre>\n
    NOTE: If your preference has a simple type (e.g. string, boolean) just use site.getCustomPreferenceValue(‘myPreferenceID’) – you don’t need the getValue() method.<\/p>\n
    A tidy way to organize this is to have a helper file in your cartridge:<\/p>\n
    \r\n\/\/ FILE: int_mycartridge\/cartridge\/config\/myCartridgePreferences.js\r\nvar System = require('dw\/system');\r\n\r\nfunction getPreferences() {\r\n    var prefs = {};\r\n    var site = System.Site.getCurrent();\r\n    prefs.myPreferenceID = site.getCustomPreferenceValue('myPreferenceID').getValue();\r\n    \/\/ ... other preferences\r\n    return prefs;\r\n}\r\n\r\nmodule.exports = getPreferences();\r\n<\/pre>\n
    … which you can then use in a JS file:<\/p>\n
    \r\nvar prefs = require('~\/cartridge\/config\/myCartridgePreferences');\r\n\/\/ prefs.myPreferenceID is now available\r\n<\/pre>\n
    … or an ISML template:<\/p>\n
    \r\n<isscript>\r\n    var prefs = require('~\/cartridge\/config\/myCartridgePreferences');\r\n    \/\/ prefs.myPreferenceID is now available\r\n<\/isscript>\r\n<\/pre>\n
    Exporting Preferences<\/strong>
    \nAfter manually setting-up your preferences in BM, export the XML files and store in your cartridge so that they are in source control. First you’ll need to export the meta data.<\/p>\n
      \n
    1. Go to Administration > Site Development > Import & Export<\/strong><\/li>\n
    2. Click Export<\/strong> under Meta Data<\/li>\n
    3. Choose System object type definitions and click Export<\/strong><\/li>\n
    4. Download the XML file locally<\/li>\n<\/ol>\n
      Next create the following file in your cartridge (assuming your cartridge’s folder is int_my_cartridge):<\/p>\n
      int_my_cartridge\/metadata\/meta\/system-objecttype-extensions.xml<\/p>\n
      You’ll need to manually<\/em> copy\/paste just the content from the export that’s relevant to your file. It’ll look something like this, where “….” will have details about your attribute:<\/p>\n
      \r\n<?xml version="1.0" encoding="UTF-8"?>\r\n<metadata xmlns="http:\/\/www.demandware.com\/xml\/impex\/metadata\/2006-10-31">\r\n    <type-extension type-id="SitePreferences">\r\n        <custom-attribute-definitions>\r\n            <attribute-definition attribute-id="myPreferenceID">\r\n                ....\r\n            <\/attribute-definition>\r\n            <attribute-group group-id="MyGroup">\r\n                <display-name xml:lang="x-default">My Group<\/display-name>\r\n                <attribute attribute-id="myPreferenceID"\/>\r\n            <\/attribute-group>\r\n        <\/group-definitions>\r\n    <\/type-extension>\r\n<\/metadata>\r\n<\/pre>\n","protected":false},"excerpt":{"rendered":"
      This is a guide for creating custom site preferences for use with Salesforce Commerce Cloud. Site preferences let users of Business Manger (BM) define settings that are used in code. For information visit\u00a0korucaredoula . You can see available site preferences in Merchant Tools \/ Site Preferences \/ Custom Preferences. They are organized by groups (e.g. … Continue reading Using Custom Site Preferences in SFCC<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":[],"categories":[17],"tags":[],"_links":{"self":[{"href":"https:\/\/www.antunkarlovac.com\/blog\/wp-json\/wp\/v2\/posts\/378"}],"collection":[{"href":"https:\/\/www.antunkarlovac.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.antunkarlovac.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.antunkarlovac.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.antunkarlovac.com\/blog\/wp-json\/wp\/v2\/comments?post=378"}],"version-history":[{"count":10,"href":"https:\/\/www.antunkarlovac.com\/blog\/wp-json\/wp\/v2\/posts\/378\/revisions"}],"predecessor-version":[{"id":406,"href":"https:\/\/www.antunkarlovac.com\/blog\/wp-json\/wp\/v2\/posts\/378\/revisions\/406"}],"wp:attachment":[{"href":"https:\/\/www.antunkarlovac.com\/blog\/wp-json\/wp\/v2\/media?parent=378"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.antunkarlovac.com\/blog\/wp-json\/wp\/v2\/categories?post=378"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.antunkarlovac.com\/blog\/wp-json\/wp\/v2\/tags?post=378"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}