Pull Personalized Content — $dotcontent.pullPersonalized

You may create personalized content pulls in dotCMS that allow you to retrieve content personalized for each user based on information about the user, their preferences, and their previous browsing behavior. dotCMS includes a built-in method, $dotcontent.pullPersonalized(), which automatically pulls and sorts content based on dotCMS Personalization features. In addition, you may create your own customized content pull to select and sort content based on these and any other criteria you wish.

The pullPersonalized Method

The pullPersonalized method ($dotcontent.pullPersonalized()) allows you to retrieve content personalized for the user by sorting the content items so the items which best match the user's preferences appear at the top of the listing.

Parameters

There are three different ways to call pullPersonalized, each with different parameters.

• pullPersonalized( query, limit )
• pullPersonalized( query, limit, secondarySort )
• pullPersonalized( query, limit, offset, secondarySort )

The following table explains each of the parameters:

Results Sorting

Content returned by pullPersonalized() is automatically sorted using the personalization information stored in the Visitor object. This is done by adding parameters to the ElasticSearch query which automatically give greater weight to content items with Tags that match the Visitor's assigned Persona and accrued tags. Specifically, content is weighted based on the following:

Modifying Sorting Weights

By default, the Visitor's Assigned Persona is weighted with a value of 100. This weight is compared against the accrued tags counts, so in most cases, this will ensure that any content tagged with the Key Tag of the Assigned Persona will always be returned at the top of the search results.

However you may increase or decrease the weighting of the Assigned Persona tag by modifying the PULLPERSONALIZED_PERSONA_WEIGHT property in the dotmarketing-config.properties file.

Note: It is strongly recommended that all changes to the dotmarketing-config.properties file be made via a properties file extension.

PULLPERSONALIZED_PERSONA_WEIGHT=100

Note: You may also control which tags are accrued to the Visitor object, to change or limit the accrued tag counts. For more information, please see the Controlling Accrued Tags section of the Visitors documentation.

For more information on how queries are sorted when using search term weighting, please see the Sorting Content Pulls by Score documentation.

Creating a Custom Personalized Content Pull

The pullPersonalized() method is a convenience method provided to make it easy for you to provide personalized content to your site users. It is intended to enable personalization without any need for coding or customization, so the way content is weighted and ranked is not designed to be customized.

However you can use Velocity code to create your own custom content pull, incorporating any user information or content available to you, and weighting the tags and content using any criteria you wish. The following examples demonstrate how to implement custom personalized content pulls using Velocity code.

Example 1: Reproduce the pullPersonalized Method

The following Velocity code example performs a content pull that mimics the way the pullPersonalized method weights and ranks content. You may use this example to create your own custom content pull, modifying the code appropriately to change how content is weighted or to add or remove content from the scoring.

Notes:

• The $query, $limit, $offset, and $secondarySort variables in the below code correspond to each of the equivalent parameters above, and are assumed to have been set before the following code is executed.
• The *^ notation appended to the name of each tag sets a scoring weight.
  • The query uses the final scores of matching content to sort the returned content, so the content that best matches the query terms (tags) with the highest score will appear first in the list of returned content. For more information, please see the Sorting Content Pulls by Score documentation.

#set($maxBoost = 10)

#if($visitor.accruedTags.size() > 0)
    #set($parsedTag, $visitor.accruedTags[0].split(":"))
    #set($tagCount = 0)
    $tagCount.parseInt($parsedTag[1])
    #set($maxBoost = $maxBoost + $tagCount)
#end

#if($visitor.persona.size > 0)
    #set($query = $query + " tags:" + $visitor.persona.keyTag.toLowerCase() + "*^" + $maxBoost)
#end

#if($visitor.accruedTags.size() > 0)
    #foreach($tag in $visitor.accruedTags)
        #set($parsedTag, $tag.split(":"))
        #set($tagCount = 0)
        $tagCount.parseInt($parsedTag[1])
        #set($tagCount = $tagCount + 1)
        #set($query = $query + " tags:" + $parsedTag[0].toLowerCase() + "*^" + $tagCount)
    #end
#end

$dotcontent.pull($query,$limit,$offset,$secondarySort)

Example 2: Boost Tags for the Currently Assigned Persona

This example modifies the query from the previous example to give greater scoring weight to tags which are included in the Visitor's currently assigned persona.

#set($maxBoost = 10)

#if($visitor.accruedTags.size() > 0)
    #set($parsedTag, $visitor.accruedTags[0].split(":"))
    #set($tagCount = 0)
    $tagCount.parseInt($parsedTag[1])
    #set($maxBoost = $maxBoost + $tagCount)
#end

#if($visitor.persona.size > 0)
    #set($query = $query + " tags:" + $visitor.persona.keyTag.toLowerCase() + "*^" + $maxBoost)
#end

#if($visitor.accruedTags.size() > 0)
    #foreach($tag in $visitor.accruedTags)
        #set($parsedTag, $tag.split(":"))
        #set($tagCount = 0)
        $tagCount.parseInt($parsedTag[1])
        #if($velocity.persona.otherTags.toString().contains($parsedTag[0].toString()))
            #set($tagCount = $tagCount * 2)
        #end
        #set($tagCount = $tagCount + 1)
        #set($query = $query + " tags:" + $parsedTag[0].toLowerCase() + "*^" + $tagCount)
    #end
#end

$dotcontent.pull($query,$limit,$offset,$secondarySort)

Note:

• This example is nearly identical to the previous example.
  • The only change is that the following 3 lines have been added into the final #if block in Velocity code:

    #if($velocity.persona.otherTags.toString().contains($parsedTag[0].toString()))
        #set($tagCount = $tagCount * 2)
    #end
    

Additional Elements for Custom Content Pulls

Please also read the following documentation for additional information you may wish to use to implement your own personalized content pulls:

• Retrieving the Visitor Object
• Accessing Rules from Velocity Code