Today let’s take a look at a way of leveraging the CMSUserWebAPI in order to serve custom content to registered users on your site. The basic premise is quite simple: check for certain user roles in a loop, and conditionally pull content into a widget. For the sake of argument, we’ll assume you’re already versed in setting up user registration in dotCMS. This tutorial will be set up around the idea of displaying ads to different users, but you could ultimately use it for any kind or format of content.

To start, we’ll set up a structure for advertising. This could just as easily be Web Page Content, or content that is hard coded into the widget. In this case, by creating the structure, it gives us some control over things like run dates, groupings, etc. This is just a suggestion for such a structure, you might add or remove fields to suit your needs. A couple comments: Ad Groups could be a custom field fed from another structure where you define the individual groups (such as header banner ads, sidebar ads, footer ads, interstitials, etc). You could also add a field for impressions, if you charge for a set number of views on an ad, and compare that against the results of #getNumViews("$identifier") before showing the ad. Both the checkboxes listed are just “Yes” fields that could allow you some control to override functionality.

Ad Structure Configuration

Ad Structure Configuration

Once you have the structure, toss some ads in to it so you have some content to work with. If you are using ad groups, you’ll need to build those in to your template/container/widget. The ad group set for that area will then be incorporated into your pull for that area. When I say “build the ad group in,” all I mean is setting up the space in your HTML (see example below). Alternatively, you may just pull ads based on size restrictions, or whatever other conditions you want to apply.

View of user roles

View of user roles

With that done, we’ll make some user roles. These will be applied to users based on whatever criteria you deem necessary. Perhaps you have paid accounts, or simply “honor” levels that are earned after a period of time. Under the user role manager, we’ll make a root role call “Ad View Levels” with two children: Level 1 Ads and Level 2 Ads. These will reflect which ads on your site users see. These can be completely arbitrary designations based on what you want. In our case, we’ll define the roles as follows:

  • CMS Anonymous – View All Ads
  • Level 1 Ads – View Some Ads
  • Level 2 Ads – View No Ads

Now, we can start defining our Velocity blocks that will control the ad display. Depending on how you are showing ads (or whatever content) you can selectively make these blocks as complex or simply as necessary.  With three levels like what I’ve listed, some blocks would have a second check, while others don’t, based on what Level 1 is allowed to ignore or not.

To set up your code, we start by seeing if the user is logged in. Then we check the roles, then if necessary, show the ad. To simplify things, we’ll mostly separate the two steps in our code into the logic and the HTML, that way you don’t even get an empty ad block when it’s not included. There would simply be nothing in the DOM from the ads at all. So, here’s the basic logic.

Logic Block:

#set($showAds = true)
#set($showNumAds = 2)
    #if($cmsuser.isUserRole($user, "Level 2 Ads"))
        ## DISABLE ADS
        #set($showAds = false)
    #elseif($cmsuser.isUserRole($user, "Level 1 Ads"))
        #set($showNumAds = 1)

First, we assume by default (in other words, for CMS Anonymous users) that we want to show ads. We also say the default is to show two ads. Then, we check to see if a user is logged in and determine which level they are. For Level 2 users, just disable the display block. For Level 1 users, we’ll show them an ad here, but we’ll set it to only show one instead of two.

HTML Block:

<div id="adGroup1">
    #foreach($ad in $dotcontent.pull('+structureName:Advertising +Advertising.adGroup:1',$showNumAds,'random'))
    <div id="ad1-${velocityCount}" class="ad">
        <a href="${ad.targetUri}" target="_blank">
            <img src="${ad.adImage.getResizeUri(125,125)}" alt="${ad.advertiser}" height="125" width="125" />
    </div>  <!-- ${esc.h}ad1-${velocityCount} .ad -->
</div>  <!-- ${esc.h}adGroup1 -->

In the display block, the first thing we do is see if $showAds was disabled. If not, start up the HTML. Then do the content pull based on the ad group (in this case, we hard coded group 1 into the query, but it could just as easily be a variable with the whole pulling mechanism done as a macro if you have a lot of ad groups and don’t want to maintain this code everywhere), using the number variable for whether or not to pull one or two ads. From there, show the ad, use the target URI, and push the image through the image resizer to make sure it fits the space right.

There are a number of ways besides ads this could be used. Premium content, special promo codes, sneak peaks at content, or show administrative debug info without being in Edit Mode. Play with different applications, and pay attention to what other tools are available in the user API. If you want to see some other examples, be sure to review our previous post on user accounts.

Photo Credit: AttributionNoncommercialNo Derivative Works Some rights reserved by kelvin255

No comments yet.

Leave a Reply