Add Custom Site Properties

You can add custom properties to sites in the form of name/value pairs. These properties are stored with the site and are made available to scripts and components on the site's pages. These can help to parameterize or customize the site without having to change the underlying scripts and component code.

For example custom properties can be used to change the page background color, refine search results, populate lists, and in general control site-dependent variables.

Custom site properties are added using the settings panel when editing a site.

  1. Open a site for editing.

  2. Click Settings icon in the sidebar and then click Site Properties Site Properties.

  3. Click Add.
  4. Enter a name and value for the custom site property. You can add up to 50 custom site properties. There is a 200 character limit on the name field and a 2000 character limit to the value field.

    Custom Site Properties

  5. Click the X next to a name/value pair to delete it.
  6. When you are finished adding or removing your custom site properties, click Commit.

Note:

Changes are not merged with existing custom site properties. Committing changes to custom site properties overwrites any existing custom site properties in the base site.

Once defined, custom site properties can be used in scripting throughout the site and site components, for example in the footer or in the Additional Query String field in components supporting SCSMacro expansion, such as content list, or through tokens in title and paragraph components.

This scripting works with the SCSRenderAPI during runtime and while designing. Also, the custom site property values are available to layout and component code in the template compiler via the SCSCompileAPI. This API has a new function analogous to the SCSRenderAPI, getCustomSiteProperty, the allows layout and component code to read the value of a custom section property.

For example, let's say you want to define a custom section layout that uses the SCSRenderAPI to call and retrieve custom site properties for the header, contact name and contact email. The following script builds an HTML string using custom site properties that gets appended to the DOM.

define([
    'jquery'
], function( $ ){
    'use strict';

    function SectionLayout( params ) {
    }
    SectionLayout.prototype = {
        render: function( parentObj ) {
            var html = '';

            try {
                html += '<div>';
                    html += '<h1>' + SCSRenderAPI.getCustomSiteProperty('SiteGreeting') + '</h1>;
                    html += '<div>For more information, contact <a href="mailto:' + SCSRenderAPI.getCustomSiteProperty('ContactEmail')
                        '"> + SCSRenderAPI.getCustomSiteProperty('ContactName') + '</a></div>';
                html += '</div>';
                $(parentObj).append( html );
            } catch( e ) {
                console.error( e );
            }
        },
    };

Custom properties are preserved when creating a template from a site with added custom site properties and when creating a site from a template that has custom site properties.