Trait

A trait is an attribute of the visitor or visit that you can detect and assign a value to.

In order to create, use and test a new trait you need to define the following elements:

• A filter for detecting the trait on every request.
• A POJO to represent the trait itself and store all its attributes.
• A rule field to store the trait values for a given variant.
• A voter for comparing rule field values stored in jcr against detected values in the request.
• A value field to test trait values and get matching variants.
• A parameter converter to translate request parameter values into trait objects and the other way around.

We will learn each of this elements creating an example for user groups trait. The use case is to be able to create personalised content based on the group of the user logged in, so you can have different content for different types of users.

Trait class

First we need to define what the trait would represent. In this case we just want to store a user group name, so it will be class with only one string property:

/**
 * Simple POJO for an user group.
 */
public class UserGroup {

    public static final String EMPTY_VALUE = "empty";
    
    private String group;

    public UserGroup() {
    }

    public UserGroup(String group) {
        this.group = group;
    }
    
    public String getGroup() {
		return group;
	}

	public void setGroup(String group) {
		this.group = group;
	}
}

To register a trait in Magnolia, it has to be defined inside a folder called traits. Lets define it in our module:

Filter

In order to detect the user group of the user making the request, we need a filter. This filter will get the user group from the user in session and will return a trait object based on this group name:

• The constructor receives a trait collector which will store the trait detected.
• The detect method has the detection logic.
• The getTraitClass method returns the trait class.
• There are getters and setters for any configurable property of the filter.

/**
 * {@link UserGroup} trait filter that detects the user group based on current user.
 *
 * @see info.magnolia.personalization.trait.AbstractTraitDetectorFilter
 */
public class UserGroupDetectorFilter extends AbstractTraitDetectorFilter<UserGroup> {

    protected Map<String, Object> groups = new HashMap<String, Object>();

    @Inject
    public UserGroupDetectorFilter(Provider<TraitCollector> traitCollectorProvider) {
        super(traitCollectorProvider);
    }

    @Override
    public UserGroup detect(HttpServletRequest request, HttpServletResponse response) throws TraitDetectionException {

        User user = MgnlContext.getUser();
    	for (Map.Entry<String, Object> entry : groups.entrySet()){
    		String value = (String)entry.getValue();
    		if(user.inGroup(value)) {
    			return new UserGroup(value);
    		}
    	}
        return new UserGroup(UserGroup.EMPTY_VALUE);
    }

    @Override
    protected Class<UserGroup> getTraitClass() {
        return UserGroup.class;
    }

	public Map<String, Object> getGroups() {
		return groups;
	}

	public void setGroups(Map<String, Object> groups) {
		this.groups = groups;
	}

}

After creating the class you will need to register it as an active filter in the Magnolia filter chain:

Rule field

A rule field defines values for the trait when you choose an audience. The value stored here will be compared against the value detected by the filter.

Lets define the rule field in our module:

• The trait will be using a text field. You can define any field available in Magnolia.
• You can define transformers and converters as with any other field in Magnolia.

Voter

The voter decides whether the visitor or visit matches the rule or not. When the rule is met, personalised content is delivered.

The voter receives a trait collector which holds the traits detected, and also receives the rule field with the value configured in the audience. The voter's logic is to compare 2 trait values:

• The trait detected: This is being hold by the trait collector.
• The trait configured as a rule for an audience. This is being hold by the rule field.

Lets have a look at our voter for the user group trait:

• The rule field is a property of the class with a getter and setter.
• The bool method has the comparison logic.

/**
 * Voter for {@link UserGroup}.
 */
public class UserGroupVoter extends AbstractBoolVoter<TraitCollector> {
	
    private String ruleField;

    @Override
    protected boolean boolVote(final TraitCollector traitCollector) {
        if (traitCollector != null) {
            final UserGroup country = traitCollector.getTrait(UserGroup.class);
            if (country != null) {
                return StringUtils.equalsIgnoreCase(country.getGroup(), getRuleField());
            }
        }
        return false;
    }

    public String getRuleField() {
		return ruleField;
	}

	public void setRuleField(String ruleField) {
		this.ruleField = ruleField;
	}

	@Override
    public String toString() {
        return "userGroup=" + ruleField;
    }

}

The voter needs to be registered as a property of the trait in our module:

Value field

A value field defines values for the trait when you are using the Preview App. The value stored here will be compared against the values stored as rules.

Lets define the value field in our module:

• The trait will be using a text field. You can define any field available in Magnolia.
• You can define transformers and converters as with any other field in Magnolia.

Preview parameter converter

The preview parameter converter is used internally by the Preview App to translate the trait values filled in the app into trait objects in the trait collector so the voter can work as intended.

For the user group trait, the converter looks like this:

• The fromString method translates a string value into a trait object that can be handled by the voter.
• The toString method translates a trait object into a string than can be handled by the Preview App.

/**
 * Parameter converter for {@link UserGroup}.
 */
public class UserGroupParameterConverter implements PreviewParameterConverter<Object> {
	
	   @Override
	    public UserGroup fromString(String string) {
	        return new UserGroup(string);
	    }

	    @Override
	    public String toString(Object object) {
	        if (object instanceof String) {
	            if (UserGroup.EMPTY_VALUE.equals(object)) {
	                return null;
	            }
	            return (String) object;
	        }
	        if (object instanceof UserGroup) {
	            return ((UserGroup) object).getGroup();
	        }
	        return null;
	    }
}

The converter needs to be registered as a property of the trait configuration:

Trait Config

The complete configuration for the trait:

Test the trait with variants