Customising the Content panel with customUi.json

With the ability to create ever customisable and intricate templates comes the need to manage the information exposed to the end user of the template.

Removing unnecessary properties, grouping related properties and renaming groups and properties are all useful features exposed by the Custom UI settings.

Custom UI is a JSON schema which allows the manipulation and modification of Content properties, groups and collections. Need to only show video options when video is enabled? Custom UI can achieve this. Need to rename a property to be more user friendly, again, Custom UI can handle it.

Capabilities:

  • Define Rules to show and hide other content properties
  • Create and define groups to group content properties and content groups
  • Set a display name for content properties and groups
  • Configure the order of content groups and properties

To configure a Custom UI, first you will need to upload a customUi.json file. At the very least this must consist of an empty JSON object.
Download an example customUi.json file.

{}

Each piece of functionality in the customUi.json file is defined as a property of this object. In turn, each of these properties has it’s members declared in an array.

The supported properties are:

{
    "rules": [ … ],
    "display-groups": [ … ],
    "content-properties": [...] 
}

Rules

Often with complex templates there are many properties exposed in the content panel. We can use customUi.json to filter only the relevant information that the user needs to access.

Individual Content Properties

Let’s start with a simple example. Let’s only show the Video Source Property of a template when the Use Video option is set to true:

{
    "rules": [
        {
            "show" : [
                "CONTENT_PROPERTIES['baseProperties']['Video Source']"
            ],
            "when": [
                {
                    "property": "CONTENT_PROPERTIES['baseProperties']['Use Video']",
                    "equals": true
                }
          ]
        }
    ]
}

We can see in the example above, that each rule is defined by a javascript object. This object contains two keys, "show" and "when". This translates to show this property when this condition is met.

The "show" key accepts an array of condition objects with "property" and "[condition]" keys. (Condition keys can be ‘equals’, ‘greaterthan’, ‘contains’ etc. see Operators)

We always access the content properties via the CONTENT_PROPERTIES constant which will ‘return’ an object containing all content properties.

We can bury down further using bracket notation.

If you are accessing a single content property, you will need to access the "baseProperties" object.

Content Groups

If you are accessing a Content Group you can replace "baseProperties" with the Content Group name as in the When property of the example below. The same can be done when referencing any property.

{
    "rules": [
        {
            "show" : [
                "CONTENT_PROPERTIES['baseProperties']['Video Source']"
            ],
            "when": [
                {
                    "property": "CONTENT_PROPERTIES['General Settings']['Use Video']",
                    "equals": true
                }
          ]
        }
    ]
}

It may be that you want to hide an entire content group based on a selected property. Using the same scenario again, in the example below, we can show all video properties in the ‘Video Settings’ Content Group only when the ‘Use Video’ property is set to true.

{
    "rules": [
        {
            "show" : [
                "CONTENT_PROPERTIES['Video Settings']"
            ],
            "when": [
                {
                    "property": "CONTENT_PROPERTIES['General Settings']['Use Video']",
                    "equals": true
                }
          ]
        }
    ]
}

Operators

To enable you to express your logic, customUi.json supports several logic operators in the "when" [condition] object key. These include:

Operator Name Supported Data Type
equals string, boolean, number
notequals string, boolean, number
lessthan number
greaterthan number
contains string

Multiple Arguments

Multiple items (arguments) can also be passed to either the "show" or "when" properties. If multiple items are passed to the "show" property, all these Content Properties / Content Groups will be shown if the "when" condition is met.

If multiple items are passed to the "when" property, they are evaluated as an AND (&&) operator. This means all conditions must be met in order to show the items in the ‘show’ property.

{
    "rules": [
        {
            "show" : [
                "CONTENT_PROPERTIES['Video Dimensions']",
                "CONTENT_PROPERTIES['Video Source Files']",
                "CONTENT_PROPERTIES['Video Poster Settings']"
            ],
            "when": [
                {
                    "property": "CONTENT_PROPERTIES['General Settings']['Use Video']",
                    "equals": true
                },
                {
                    "property": "CONTENT_PROPERTIES['App Settings']['Video Poster Type']",
                    "notequals": "None"
                }
            ]
        }
    ]
}

A warning when using show & hide rules

Based on the properties you choose to hide and show, we optimise our configuration file appropriately. If a property is hidden in the UI it is deemed not needed and, hence, removed from the ad configuration when the ad is served. This enables the ad to be served quicker to the page. 

This means that dependencies on these omitted content properties may cause logic in your code to break, so always check for the existence of a Content Property in your ad code before using it.  

Display Groups

One long list of Content Properties and Content Groups can often be a bit verbose. The display groups property of customUi.json not only allows you to group Content Groups under a common name but also allows you to give this group a name.

In addition, the Content Group UI is tidied up giving the content panel a cleaner feel.

Again, let’s start with a simple example. If we have a Content Group with the name "General" and we want to name this to something more descriptive, say, "General Settings" we can pass an object to the Display Groups array defining this:

{
    "display-groups": [
        {
            "group-name" : "General Settings",
            "target-group" : "General",
            "order" : 1 
        }
    ]
}

You’ll also notice in the example above an "order" property. This allows you to define the order of the display groups from a 0 based index through to whatever number you like.

Imagine we have several Content Groups pertaining to Video. We may want to group all these options under a common group, "Video Settings". The example below demonstrates creating a new Display Group and adding the existing Content Groups to it.

{
    "display-groups": [
        {
                "group-name" : "Video Settings",
                "order" : 1,
                "properties" : [
        {
            "property" : "CONTENT_PROPERTIES['Video Dimensions']",
            "display-name" : "Dimensions",
            "order" : 0
        },
        {
            "property" : "CONTENT_PROPERTIES['Video Source']",
            "display-name" : "Source",
            "order" : 1
        },
        {
            "property" : "CONTENT_PROPERTIES['Video Poster Image']",
            "display-name" : "Poster Image",
            "order" : 2
        }
    ]
}

You’ll notice in the example above we pass an array of "Property" objects to the "Properties" property of the individual "Display Group" property (still with me?!).

This "Property" object supports multiple keys including the basic "property" key which defines the Content Group you want to add to the Display Group. The Content Groups are accessed / defined in the same way as in the Rules we explored above.

Additionally we have a "display-name" key which allows you to re-name the Content Group;  in-line with it’s new siblings perhaps. In the above example we have removed the recurring "Video" prefix as all our Content Groups are under the "Video Settings" Display Group.

Lastly we have the "order" key again which allows you to set a custom order in which the Content Groups will display.

If you already have a Content Group and you just want to add other Content Groups to it, you can do this as well. Using the same properties as above as an example:

{
    "display-groups": [
        {
            "group-name" : "Video Dimensions",
            "target-group" : "Video Dimensions",
            "order" : 1,
            "properties" : [    
        {
            "property" : "CONTENT_PROPERTIES['Video Source']",
            "display-name" : "Source",
            "order" : 0
        },
        {
            "property" : "CONTENT_PROPERTIES['Video Poster Image']",
            "display-name" : "Poster Image",
            "order" : 1
        }
    ]
}

Sometimes Content Collections can also become unwieldy. Although it is not possible to set an individual Content Collection as a Display Group, it is possible to group the properties within a Content Collection to provide more order.

See the example below where we group the Content Collection properties into Content Groups and assign the main Content Collection as a child of a new Content Group.

 {
    "display-groups": [
        {
            "group-name":"Gallery",
            "order":0,
            "properties": [
                {    "property" : "CONTENT_PROPERTIES['Gallery Items']",
                    "display-name" : "Items",
                    "order" : 0
                }
            ] 
        },
        {
            "group-name" : "Image Settings",
            "target-collection" : "Gallery Items",
            "order" : 0,
            "properties" : [    
                {
                    "property" : "CONTENT_PROPERTIES['Image File']",
                    "display-name" : "File",
                    "order" : 0
                },
                {
                    "property" : "CONTENT_PROPERTIES['Image Clickthrough']",
                    "display-name" : "Clickthrough",
                    "order" : 1
                }
            ]
        }
    ]
}

This will create a new Display Group, nested in the Content Collection with the supplied name, "Image Settings" and with the properties defined.

Renaming Content Properties

It may be necessary to rename Content Properties in a template. Such a scenario may arise where you don’t have access to the code base but want to change a Content Property name to something more meaningful. Alternatively, you may want to add further language support for your template.

CustomUi.json allows you to change individual property names to whatever you want.

The behaviour here changes slightly as demonstrated below. Instead of CONTENT_PROPERTIES representing all Content Properties of the ad as with the previous rules, the CONTENT_PROPERTIES object instead represents the Content Group passed in the "group-name" property.

"content-properties": [
    {
        "group-name": "Module 1 Image",
        "show-content-hub": true,
        "properties": [
            {
          	    "property": "CONTENT_PROPERTIES['Image file']",
                "order": 1,
                "display-name": "Image File"
            },
            {
                "property": "CONTENT_PROPERTIES['Image Url']",
                "order": 0,
                "display-name": "Image URL"
            }
        ]
    }
]

The above rules are mostly aesthetic. Assigning existing Content Groups to a Display Group or renaming a Content Property will not affect the underlying code. References in your code to Content Properties and Groups will remain unaffected.

Feedback and Knowledge Base