Magnolia 5.5 reached end of life on November 15, 2019. This branch is no longer supported, see End-of-life policy.
This tutorial takes you through the process of creating a custom trait.
For this version of this tutorial - you should use a Magnolia Enterprise Pro bundle of the 5.5.x series, which must be 5.5.3 or higher, and it must contain the module magnolia-personalization-components
. You can use magnolia-enterprise-pro-webapp-5.5.16.war (the webapp) or magnolia-enterprise-pro-demo-bundle-5.5.16-tomcat-bundle.zip as a base.
A trait is an attribute or property of a visitor or visit, such as age or gender, that you can use to personalize content.
We create a trait that detects the visitor's operating system. Depending on the detected user agent, we serve the visitor a page with a personalized component. We create two component variants named "WINDOWS" and "OS-X" for a Text and image component.
The trait extracts the operating system from the User-Agent in the HTTP header:
ftp://mgnl.travel/maps-offline/windows.zip
.ftp://mgnl.travel/maps-offline/osx.zip
.ftp://mgnl.travel/maps-offline/other-systems.zip
.
A trait is deployed with a Magnolia module. Create a module first. Choose from these options depending on your skill level:
This option gives you a ready-made project that you can customize to your needs.
Choose this option if you know how to work with a Magnolia project and Git, and want to examine the code locally in your IDE.
Clone the documentation-trait-tutorial
repository.
git clone http://git.magnolia-cms.com/git/documentation/documentation-trait-tutorial.git
After having cloned the repo, you can check out the tagged version for the tag named documentation-trait-tutorial-1.3
:
git checkout documentation-trait-tutorial-1.3
Import the project into your IDE. Here's what the project looks like in IntelliJ IDEA:
Choose this option if you run Magnolia in your IDE, but don't plan to work on the code.
Add the project as a dependency in the POM files of your Magnolia bundle.
For Enterprise Edition bundles:
In the dependencyManagement
section of the EE-bundle parent POM file, add a dependency
element with a version number:
<dependency> <groupId>info.magnolia.documentation</groupId> <artifactId>documentation-trait-tutorial</artifactId> <version>1.3</version> </dependency>
In the dependencies
section of the enterprise-webapp POM file, add a dependency
element without a version number:
<dependency> <groupId>info.magnolia.documentation</groupId> <artifactId>documentation-trait-tutorial</artifactId> </dependency>
If you use IMB WebSphere or Oracle WebLogic, add the
dependency
element in the appropriate POM file of your webapp of choice.
If you are using a custom bundle, add the dependency
element with a version number in the POM file of your customized bundle.
Choose this option if you are new to Magnolia and don't have a development environment (IDE). You can use the trait but won't be able to look at the code.
<CATALINA_HOME>/webapps/<contextPath>/WEB-INF/lib
folder. Typically this is <CATALINA_HOME>/webapps/magnoliaAuthor/WEB-INF/lib
.documentation-trait-tutorial
module.Any module can register a trait. Magnolia observes the
traits
folder in your module configuration and adds new traits to a trait registry. Registered traits are then displayed to editors in the user interface.
Here's the userAgent
trait.
Node name | Value |
---|---|
modules | |
documentation-trait-tutorial | |
traits | |
userAgent | |
ruleField | |
valueField | |
converterClass | info.magnolia.documentation.examples.personalization.useragent.UserAgentParameterConverter |
defaultPreviewTrait | true |
traitClass | info.magnolia.documentation.examples.personalization.useragent.UserAgent |
voterClass | info.magnolia.documentation.examples.personalization.useragent.UserAgentVoter |
Properties:
<trait name>
| required Trait name. Choose a name that is easy for editors to understand such as |
| required Field used to define permitted values for the trait. See Rule field below. |
| required Field used to enter a single value to test personalized content delivery. See Value field below. |
| required Converter class which must implement |
| required Trait class. Doesn't have to explicitly implement any interface. Usually it is just a plain Java object which allows you to specify the trait and its characteristics. |
| required Voter class which must extend |
| optional, default is Adds the trait to the Preview app. Set this property to |
| optional, default is If the trait is expected to remain the same for all requests in the current session, you can set the value to |
A rule field defines values for the trait when you choose an audience. For example, you need two rule fields to define a date range: one for start date and another for end date. Magnolia uses the input entered into the rule field(s) to construct a voter. The voter then decides whether the visitor or visit matches the rule or not. When the rule is met, personalized content is delivered.
The rule field is displayed to users in the Choose audience dialog:
Choose a field definition class that lets the user specify the permitted values. In some cases, a simple text field is enough (country). In others, for example where you need the user to select a value (new visitor, registered visitor, logged-in visitor), a select field is appropriate. For more complex fields, use a composite field. See List of fields for more.
userAgent
rule field:
Node name | Value |
---|---|
userAgent | |
ruleField | |
class | info.magnolia.ui.form.field.definition.TextFieldDefinition |
transformerClass | info.magnolia.personalization.ui.SimpleTraitValueTransformer |
type | String |
Properties:
ruleField | required Rule field node |
| required Field definition class . The field must be known to the system. If you introduce a new field and only want it available in your module, configure it in the |
| required Transformer class which must implement |
| required/optional Field type. In this case it is a bean property of the superclass ( |
A value field is for previewing variants. The field is displayed to users in the Preview app when viewing the page as a visitor:
When you enter a value that matches the rule, for example "Macintosh" in the image above, the voter tests the value against the rule and Magnolia displays the content variant associated with the value.
userAgent
value field:
Node name | Value |
---|---|
userAgent | |
valueField | |
class | info.magnolia.ui.form.field.definition.TextFieldDefinition |
type | String |
Properties:
valueField
| required Value field node. |
| required Field definition class . See Rule field (above) and Custom fields if you need to create a new field. |
| required/optional Field type. In this case it is a bean property of the superclass ( |
Once you have registered the trait, provide a TraitDetectorFilter
and register it in the filter chain to make sure the appropriate variant is served.
UserAgentDetectorFilter
registration in the filter chain.
Node name | Value |
---|---|
server | |
filters | |
context | |
contentType | |
userAgent | |
class | info.magnolia.documentation.examples.personalization.useragent.UserAgentDetectorFilter |
<more filters> |
Properties:
filters | required Filters node |
| required Filter name. Name the filter after your trait. Ideally name the node to match the trait registration node. In our example the filter name is |
| required Class that implements |
Make sure the filter is in the right position in the chain. Filters are executed in the order they are registered in the chain, from top to bottom. You want to position the filter right after the contentType
filter.
When installing a module, you can define the position with ModuleVersionHandler#getExtraInstallTasks
.
public class PersonalizationExamplesModuleVersionHandler extends DefaultModuleVersionHandler { @Override protected List<Task> getExtraInstallTasks(InstallContext installContext) { List<Task> tasks = new ArrayList<Task>(); tasks.add(new FilterOrderingTask("userAgent", new String[]{"contentType"})); return tasks; } }
In the example above the configuration tree is simplified. Other filters may also want to be right after contentType
. In a production environment it may look like this:
Now you can create component variants and choose an audience using the new trait.
The documentation-trait-tutorial
module installs an example page named maps-download
that contains two custom variants of the Text and image component:
Windows variant
OS-X variant
Original
It is not possible to specify an audience for the original. The original acts as fallback (default) content when no variants match the visitor.
You can test the personalized variants using a browser plugin or on different computers running Windows and OS-X. User agent switcher add-ons that allow you to spoof and mimic various user agents are available for Firefox, Chrome/Chromium, and Opera.
You should now be able to see different renderings of the page containing the personalized variants of the Text and image component depending on the user agent.
Windows user agent
OS-X user agent
Other user agents