The 5.7 branch of Magnolia reached End-of-Life on December 31, 2023, as specified in our End-of-life policy. This means the 5.7 branch is no longer maintained or supported. Please upgrade to the latest Magnolia release. By upgrading, you will get the latest release of Magnolia featuring significant improvements to the author and developer experience. For a successful upgrade, please consult our Magnolia 6.2 documentation. If you need help, please contact info@magnolia-cms.com.

Related topics:

This first step in creating a custom cookie trait is to add custom options and values to the preconfigured cookies trait in the Personalization Traits module.

The cookies trait is configured in  /modules/personalization-traits/traits/cookies and the  configuration includes a  rule and value field. 

This page of the tutorial shows you how to configure these fields for a cookie named  visits . Please read Cookies trait configuration before you begin.


You can import the XML files provided in the Download configuration files section if you prefer not to configure manually.

Configuring the rule field

The rule field defines values for the trait when you choose an audience. The input entered into the rule field(s) is used to construct a voter. The voter decides if the visitor or visit matches the rule. When the rule is met, Magnolia delivers personalized content.

The rule field options display in the Choose audience dialog in the Pages app. See Personalizing a component for how to access the dialog.

There are two steps to configuring the rule field:

  1. Add the new cookie as an option in the switchable field.
  2. Add the new cookie options in the select field.

Here is the final rule field that the configurations below produce.

Adding the switchable field option  

Options in the switchable field display in the Choose audience dialog when the user selects Visits in the Cookie field.

To activate the switchable field, in the dialog click Pick trait > Cookie or + > Cookie (if an additional trait exists).

To add the visits option in /modules/personalization-traits/traits/cookies/ruleField/options :

  1. Add a new content node, visits. This is the internal name of the switchable field option.
  2. Add two properties to the visits node:
    1. label= Visits: The label displayed in the field.
    2. value= visits: The option value stored in the repository.

The configuration should look like this:

Node nameValue

 
cookies


 
ruleField


 
options


 
visits


 
label

Visits

 
value

visits

 
weatherLocality


 
tourType


Adding the select field options

Options in the select field display in the dropdown in the Visits field.

To add the visits options, in /modules/personalization-traits/traits/cookies/ruleField/fields :

  1. Add a  visits/options node structure.
  2. In the /options node: 
    1. Add one content node for each option. Our options are one, two, three, four and any. These are the internal names of the options.
    2. Add two properties to each option node:
      1. label= <Option label>: The label displayed in the field. 
      2. value= <Option value>: The option value stored in the repository.
  3. Optionally, add a sortOptions property to /visits node and set the value to false. This ensures that the options render in configuration order and not alphabetically.

The configuration should look like this:

Node nameValue

 
cookies


 
ruleField


 
options


 
fields


 
visits


 
options


 
one


 
label

One

 
value

1

 
two


 
label

Two

 
value

2

 
three


 
label

Three

 
value

3

 
four


 
label

Four

 
value

4

 
any


 
label

Any

 
value

any

 
class

info.magnolia.ui.form.field.definition.SelectFieldDefinition

 
defaultValue

any

 
sortOptions

false

 
tourType


 
weatherLocality


 
class

info.magnolia.ui.form.field.definition.SwitchableFieldDefinition

 
transformerClass

info.magnolia.personalization.cookie.CookieFieldTransformer

Configuring the value field

The value field defines the options that display in the Preview app. The field is used to preview variants when testing personalized content delivery.

Here's the final value field that the configuration below produces.

The value field is an  Option group field.  The option values should match the option configurations in the rule field. 

To add the value field options, in /modules/personalization-traits/traits/cookies/valueField :

  1. Add one content node for each option configured in the rule field. These are the internal names of the options. The node name is arbitrary. Configure one option for each option configured in the rule field
  2. Add two properties to each option node:
    1. label= <Option label>: The label displayed in the field. 
    2. value= <<Rule field name>:<Rule field option value>>: The option value stored in the repository.
  3. Optionally, add a sortOptions property to /valueField node and set the value to false. This ensures that the options render in configuration order and not alphabetically.

The configuration should look like this:

Node nameValue

 
cookie


 
ruleField


 
valueField


 
options


 
visitsOne


 
label

Visits: One

 
value

visits=1

 
visitsTwo


 
label

Visits: Two

 
value

visits=2

 
visitsThree


 
label

Visits: Three

 
value

visits=3

 
visitsFour


 
label

Visits: Four

 
value

visits=4

 
visitsAny


 
label

Visits: Any

 
value

visits=any

 
tourTypeAny


 
...


 
class

info.magnolia.ui.form.field.definition.OptionGroupFieldDefinition

 
multiselect

true

 
sortOptions

false

Download configuration files

As an alternative to manual configuration you can import these XMLs: