Learn dotCMS

dotCMS and Mobile Techniques: Notes from Boot Camp 2011

Michael Fienen — Thu, 18 Aug 2011 15:56:36 +0000

At dotCMS Boot Camp 2011, I was invited to come and talk about mobile implementation techniques using dotCMS. Luckily, this isn’t as much as issue with trying to pull off clever dotCMS tricks as it is just knowing good mobile techniques. Below are a number of links and examples from my talk. This isn’t so much about a full blown tutorial, as much as it is just a quick reference for those that attended my session. A more complete tutorial will come at a later date.

Mobile Detection Using the Clickstream

By accessing the user’s clickstream data, and pulling out the isMobile() flag, we can create a conditional environment to do redirects, apply different stylesheets, change layout, etc.

## GET CLICKSTREAM SO WE CAN CHECK OUT THE DEVICE
#set($clickstream  = $session.getAttribute('clickstream'))
## IS THIS A MOBILE DEVICE?
#if($clickstream.mobileDevice && $clickstream.mobileDevice == 'true')
  ## GET THE REDIRECT COOKIE
  #set($goToMobile = $cookietool.get('goToMobile').value)
  #if($goToMobile == 'true')
    ## SEND THE USER TO THE MOBILE SITE, THIS MUST BE DONE BEFORE
    ## ANY DATA IS SENT TO THE BROWSER
    #$response.sendRedirect('http://m.yoursite.com/')
  #else
    ## IF IT'S MOBILE, BUT THEY WANT THE NORMAL SITE, SEE IF IT
    ## SHOULD BE DISPLAYED LIKE MOBILE OR LIKE NORMAL
    #set($displayMobile = $cookietool.get('displayMobile').value)
  #end
#end

By setting a cookie at the same time as the check, you can prevent users from having to go through the selection each time if they prefer the normal site over the mobile site. You could set the cookie with some simple JavaScript.

Creating a Mobile Template

Creating a mobile template is no different from any other template. If you’re using a framework like jQuery Mobile, you can build all the necessary parts right into the template.

## Container: General Template Includes
#parseContainer('e97bda22-33e8-4b9d-9508-0aefb4c899d6')



  
  
  
  

  $!{pageTitle}

  
  
  
  

  
  




  
    $!{pageTitle}
  


  
    ##Body Container 1
    #parseContainer('93cf710e-fbbb-4d32-a5fb-974dcac38c96')
  


  
    Copyright ©2011

jQuery Mobile and the #navigation() Macro

If you want to use the #navigation() macro and take advantage of jQuery Mobile tooling, you just need to add a little extra JavaScript into the mix to ensure the list is picked up and styled correctly. A single line of JavaScript will get you rolling.


  #navigation(1 1)

By using the .attr() method, we can add in any of the data-roles or other attributes that can be used to control how the list navigation looks and behaves as a result of jQuery Mobile. (Note: as seen in the above example, when writing code inline on the page and referencing ID’s, I replace all #s with ${esc.h}. This is the Velocity tool for printing out a hash, and is good for preventing accidental collisions in normal velocity code.)

Building a News Page

In this example, I pull in a list of recent news headlines and spit them out readily formatted for my jQuery Mobile stylesheet (Note: My code uses 1.7 syntax. However the principle remains unchanged for 1.9.)

#set($lastArticleDate = '0')
#set($today = $date.format('MM/dd/yyyy HH:mm:ss',$date.getDate()))
## FILTER DOWN TO A SPECIFIC SET OF NEWS CATEGORIES
#set($newsCatList = $categories.getChildrenCategoriesByKey('sections'))
#set($newsCats = "+(")
#foreach($cat in $newsCatList)
  #set($newsCats = "${newsCats}c${cat.inode}c:on ")
#end
#set($newsCats = "${newsCats})")
#set($query = "+structureInode:5 ${newsCats} +date1:[1/1/2010 00:00:00 TO ${today}] +languageId:1* +deleted:false +live:true")
#pullContent("${query}" '10' "date1 desc")


  The latest campus news from public relations.



#foreach($article in $list)
  ## SET DATE FOR COMPARISON
  #set($thisArticleDate = $date.format('EEEE, MMMM d, yyyy',$article.NewsPublishDate))
  ## IF CURRENT DATE IS DIFFERENT THAN THE LAST ARTICLE, PRINT OUT A DATE DIVIDER
  #if($thisArticleDate != $lastArticleDate)
	${thisArticleDate}
  #end
	${article.NewsHeadline}
  #set($lastArticleDate = $date.format('EEEE, MMMM d, yyyy',$article.NewsPublishDate))
#end

Links, Tools, and Resources

I mentioned several sites and tools when talking about mobile, here are many of them:

jQuery Mobile – A JavaScript framework that extends jQuery and helps add a number of mobile features to your site.
PhoneGap – Utility for compiling a web app into a wrapper so that you can deploy it as a native app for a number of mobile platforms.
Android SDK – Free SDK for Android that comes with a mobile phone simulator, useful for testing.
CSS Media Queries & Using Available Space – Guide to how to implement CSS media queries for changing CSS rules based on display conditions reported by the browser.
jQuery Mobile Google Maps Examples – Nice list of ways to build on jQuery Mobile with Google Maps (i.e. pulling content from a buildings structure to populate a map)

Legacy Form Submission Security Patch

Michael Fienen — Mon, 27 Jun 2011 13:00:35 +0000

A while back, it was exposed that if using the legacy form submission struts path (e.g. /sendEmail, /submitWebForm, etc), a spammer could remotely invoke the tool and use it to send spam emails to people. While this wasn’t exactly a bug in the strictest sense, it could prove to be a headache for users should their server be targeted.

Enter costarica.com. Thanks to their effort, a patch has been made available (for 1.9) that will force the server check the referring HTTP request against a list of approved server names and IPs. As a result, attempts to access the tool directly will be denied – the tool has to be invoked by a request originating from your site. This has been set up as a plugin for easy installation.

Instructions:

Edit conf/plugin.properties to include your list of approved hostname (you’ll have to do this each time you add or remove hosts in dotCMS)
Copy the plugin to the plugins/ folder of your dotCMS installation
Shut down dotCMS
Do an ant clean-plugins deploy-plugins
Start up dotCMS

[ DOWNLOAD Legacy Form Submission Security Patch 1.0 for dotCMS 1.9 ]

JSON and AJAX and XML, Oh My!

Michael Fienen — Tue, 22 Feb 2011 18:49:17 +0000

A question that has been coming up with some regularity lately has to do with doing dynamic, AJAX based work with the content engine in dotCMS. For some time, dotCMS has offered DWR as a means of handling those needs, but ultimately, DWR is a cumbersome, limited tool. In the end, there are two other ways of getting similar results which are much easier for most people to implement.

Since we’re going to ignore the existence of DWR, you’re going to need to be familiar with something like jQuery for doing AJAX work. You’re not going to get away from using JavaScript (it’s… you know… sort of integral to the whole concept of AJAX), but we can at least use something that’s more common and familiar. It doesn’t have to be jQuery, but that’s what I’ll be using here.

Calling a Proxy Page

This is the simplest way of handling AJAX needs. First, we’ll assume that you already know the context that the AJAX response is going to be used in. In that case, we’ll return some actual HTML ready to be inserted into a page. Set up a purely blank template if you don’t already have one (e.g. it has no other HTML on the page besides that supplied from its container), and include a single container. Now, make a page with that template, add a Simple Widget, and code it out to pull some content.

## CHECK TO SEE IF A CATEGORY FILTER WAS SUPPLIED
#if($UtilMethods.isSet($request.getParameter('cat')) && $request.getParameter('cat').length() > 0)
	#set($queryParams = " +categories:${request.getParameter('cat')}")
#end
## PULL THE LIST OF PRODUCT CONTENTLETS
#set($productList = $dotcontent.pull("+structureName:Product$!{queryParams}",0,"modDate desc"))
#if($productList.size() > 0)
	#set($numResults = "$!{productList.size()} product")
	## CHECK TO PLURALIZE 'product'
	#if($productList.size() > 1)
		#set($numResults = "$!{numResults}s")
	#end
#else
	#set($numResults = 'Sorry, no products were found in that category')
#end
Found: $!{numResults}

## SHOW THE LIST OF PRODUCTS
#foreach($con in $productList)
	$!{con.title}
#end

This is a very simple example of an HTML response you could build to have the page return. Realistically, you can include as much or as little information here as you want, it just depends on what you plan to do with the data on the page where it ends up. In this case, assume it’s a basic search filter to show products on a page, allowing the visitor to filter based on the available categories. The result is a basic ordered list of links to the products that matched the search.

Next it’s all about setting up your front end page where visitors will view the content. Create a second page (using a normal template), and we’ll add in a search dropdown box and a little JavaScript to run things.


	Filter by:

So, very simple – search happens, jQuery requests info, response is returned, HTML is inserted into div. It’s simple to do, and works great when you know how the HTML is going to be handled.

The JSONContent Servlet

In 1.9, there is a new servlet tool you can use now that will return content as either JSON or XML data on demand. This is perfect when you don’t necessarily know what the HTML markup is that will be needed. And better, simply calling http://www.yoursite.com/JSONContent will give you the basic instructions to using the servlet. It takes six different parameters:

q: URLEncoded lucene query (required, try the $UtilMethods.encodeURL($query) viewtool)
type: json or xml (default: xml)
limit: number of results (default: 10, max of 1000)
offset: start at specific result number (default: 0)
orderBy: field to order by (default: modDate)
debug: true/false; if set, will return JSON as text/plain (defaults: false)

By making an AJAX request to this servlet we can basically do the same job as above. For instance, instead of hitting the product-response.dot page in the JavaScript, we could do http://demo.dotcms.org/JSONContent/?type=xml&q=%2BstructureName:product. This returns all the info on the contentlets in JSON format (remember, you could change the type parameter if you want to stick with XML) that we could then parse into the page. By working this way, we can drop the need for the proxy page, and we only need our main page to send this query. For the same kind of page, the changes would look something like:


    Filter by:

This effectively produces the exact same results as above. The only change we made to the form itself was the dropdown values now use the category’s Velocity variable name (in the previous example, we used the category key). Otherwise we get a JSON data response back from the /JSONContent servlet, and use the jQuery to loop the results into the page.

Conclusions

Overall, either way works just as well as another, and it is up to you which works best for your style or application. Additionally, you could write your own custom tools to output XML or JSON from dotCMS for other applications. The first method works well when you know the context you’ll use the response in and when you want to limit the amount of JavaScript you’re using. The second way is good when you may not know how the response is used or if you need to manipulate the base data before displaying it.

Photo Credit: Some rights reserved by ptufts

Building a Velocity Portlet Plugin for IRC

Michael Fienen — Sat, 08 Jan 2011 23:52:55 +0000

This post will be dual purpose: first, to announce the release of the dotCMS IRC Client plugin, and second to provide a tutorial explaining how to launch a Velocity portlet plugin. Velocity portlets are a relatively simple way of building tools that can be built into the backend of dotCMS and be used as tabs that users can access. In this case, this plugin builds a portlet that includes the Freenode web based IRC client and an extra collaboration tool. We will deconstruct the plugin piece by piece so that you can see the components needed for such a tool.

To start off, you’ll want to set up the files and folders that you’ll need for the plugin. A basic portlet only requires a handful of files. The files listed in italics are required for any plugin – the rest are specific to this one:

com.learndotcms.plugins.ircsupport
- /conf
  - Language-ext.properties
  - plugin.properties
  - portal-ext.xml
- /static_velocity
  - /portlet
    - irc.vm
- build.xml
- MANIFEST.MF

The two files in the root of your plugin are required, and extremely straightforward. The build.xml file is just to name the plugin internally, and the MANIFEST.MF file carries the specific details of the plugin. We don’t need to define a deploy class in the manifest file for this plugin, because our portlet stands on its own and doesn’t need to do anything when it’s installed. Otherwise, you can use the Deploy-Class field to list a Java class provided in the plugin that should be ran when the plugin is deployed. This can be done to do things like build a structure, add content, or do anything else that requires API interaction necessary for the plugin.

build.xml

MANIFEST.MF

Manifest-Version: 1.0
Deploy-Class:
Plugin-Name: dotCMS IRC Channel Client
Plugin-Version: 1.110106
Author: Michael Fienen (http://learndotcms.com)

From there, you’ll set up the two folders: /conf for the configuration elements, and /static_velocity/portlet which will store the code for our portlet. There’s very little configuration needed, and if you use the Hello World plugin as an example, it’s easy to modify. The language extension file is used to define the name of the portlet that will be visible in the back end:

Language-ext.properties

javax.portlet.title.EXT_IRC_SUPPORT=dotCMS IRC Client

In our portal extension file, mostly we just set the portlet name and the path to our Velocity file that will be used for the portlet. Take note that the portlet-name node (line 3) corresponds to the portlet title value from Language-ext.properties file. You’ll also set the view-template value on line 8 to correspond to your path inside the /static_velocity folder of your plugin.

portal-ext.xml



    EXT_IRC_SUPPORT
    dotCMS IRC Client
    com.liferay.portlet.VelocityPortlet
    
        view-template
        /static/plugins/com.learndotcms.plugins.ircsupport/portlet/irc.vm
    
    0
    
        text/html
    
    com.liferay.portlet.StrutsResourceBundle
    
        CMS User

Finally, the plugin.properties file is required, and can be left simply as:

plugin.properties

## The default for the reload.force is true.  If it is set to false the properties will only load once from
## the file. After that they will be stored and maintained in the database.  If true every time the server
## restart the properties will be cleared and reloaded.
reload.force=true

Now, the fun starts. The heavy lifting for this plugin happens almost entirely in the irc.vm file. As a Velocity portlet, dotCMS effectively takes the file you define above in the portal extension file and wraps it in the back end tab structure, making it look nice, and allowing you to use code you are familiar with. We’ll start the file with some simple Velocity code that takes care of checking some cookie values and setting up option defaults:

irc.vm (part 1/3)

## SEE IF A DEFAULT IRC NICKNAME HAS BEEN SET
#set($dotCMSIRCNick = $cookietool.get('dotCMSIRCNick').value)
#if($dotCMSIRCNick)
    ## SET THE STRING USED IN THE iframe SOURCE URI FOR PRESET NICKNAME
    #set($enableNick = "nick=$!{dotCMSIRCNick}&")
#end
## LOOK FOR DEFAULT HEIGHT AND WIDTH FOR THE POPUP CHAT CLIENT
#set($ircPopupW = $cookietool.get('ircPopupW').value)
#set($ircPopupH = $cookietool.get('ircPopupH').value)
## IF NO HEIGHT OR WIDTH DETECTED, USE DEFAULTS
#if(!$ircPopupW || $ircPopupW.length() == 0)
     #set($ircPopupW = 640)
#end
#if(!$ircPopupH || $ircPopupH.length() == 0)
    #set($ircPopupH = 400)
#end
## ACCOUNT FOR THE INNER HEIGHT OF THE POPUP CHAT CLIENT
#set($ircPopupIframe = $math.sub($ircPopupH,22))

Next, we hit some basic CSS for the layout, and a whole lotta JavaScript. The JavaScript handles the popups (for chat and the Collabedit windows), and setting values from the option popup.

irc.vm (part 2/3)

Finally, we just need to lay out the HTML for the visible part of the portlet. In this case, we use an iframe embed for the Freenode web IRC client (based on qwebirc). Below that, a few buttons that allow the user to open a popup with the chat client in it (created using the openIRCPopup() function above on line 76), open a popup with a Collabedit panel in it (useful for brainstorming or trying to get help from folks in the IRC channel), and finally the options popup. Be sure to note in the HTML the use of Dojo properties on the buttons and dialog to make the look and feel of everything blend in with the rest of the backend.

irc.vm (part 3/3)


    
        Home
        dotCMS IRC Chat
    
    
  



    

    
        
            Brought to you by LearndotCMS.com
        
  

        
        
        
    
  
  


    Default Nickname: 
    Popup Size: px by px
    
        
        
    
    
        Clear your cookies to reset IRC settings to their defaults.

Now, save all this stuff out, and dump your folder into the /plugins directory in your dotCMS install. From here on out, it’s all simply configuration. Start but shutting down your server, open a command prompt, navigate to the dotCMS directory and run the command:

ant clean-plugins deploy-plugins

Set up a new portlet on a tab

Then, start dotCMS back up, log in to the back end, and under the CMS Admin tab open up Roles, Tabs, & Tools. How you deploy this particular portlet is up to you. For instance, you could create a new tab and dedicate it to the chat client, or make it a child of an existing tab, such as the Home tab. In the screenshot to the left we have opened up the Home tab and selected the new portlet from the Tools dropdown list. Click the Add button, and you can drag and drop the portlets in the order you want them to appear in the menu (if you create a dedicated tab, you can just put one portlet on it and there won’t be a menu, clicking the tab will just go straight to it.). Refresh the page, and you’re golden. You can repeat this process for whichever roles you want to have access to the client.

The IRC Portlet plugin

Wherever you tell dotCMS to load the portlet, clicking on it will open a page that will read in the source VM file from your plugin. In our case, it shows our embedded chat client, and extra buttons. By researching the setup of other portlet pages in the backend, applying the appropriate markup to the buttons results in a very familiar feel, allowing you to build something that isn’t just crowbarred into the backend (though, nothing’s stopping you from doing it ugly, it’s just really easy to get that extra polish).

Options popup

We also added a Dijit powered dialog box to control the portlet options. All it is needs is a hidden div with some markup, and Dojo handles the rest (lines 24-34 in irc.vm part 3). In some cases, you can hardcode plugin options into the plugin.properties file. That’s fine. In this case, I wanted the options to be specific per user, without going through the effort of tying into the user settings. The answer was simply adding in a little JavaScript to set up cookies that will last for a year on the machine. When the page loads, we read in those cookie values and use them to customize the chat client and its popup.

Overall, this is about as simple a process as you could ask for. Being Velocity powered, you can access anything you would normally be able to get into on web pages. That might be usage of viewtools, pulling content, or utilizing macros. Better yet, you don’t need to learn any complex Struts mapping or Java code to try it out.

[ Download the IRC Plugin (v1.110106) ]

Image Gallery

Enter Nutch, Stage Left

Michael Fienen — Wed, 29 Dec 2010 15:00:09 +0000

Spindle sucked. Say it with me. Spindle sucked. As far as search goes, sure, it was better than nothing. The problem was that the Spindle backbone wasn’t very robust as far as search algorithms go, there was no UI for it, and the kind of results you could get were pretty limited. Not to mention development on the Spindle project seems to have ceased. Now, you could have always tied into Google Custom Search with the $googleminiapi viewtool, which was perfectly fine, but that then requires you to be set up in Google, and it takes some control out of your hands.

Nutch was introduced as the solution. Nutch is one of many Apache projects implemented within dotCMS. What makes Nutch powerful is that it is built on top of Lucene and Solr, it includes a crawler engine, and is capable of crawling web pages and documents alike. On top of all that, dotCMS also implemented a portlet to run it from (Technically, Spindle had one, but you had to manually call its URI, and all it did was instantiate it). In summation, you end up with a much nicer tool with a lot more flexibility if you need to add search to your site.

The Site Search Portlet

The Site Search portlet is available under the CMS Admin tab. You can enable or disable it per host if you choose, set up the crawl schedule (using a cron expression), and control exclusions. It’s powerful enough to be useful, but simple enough to not be intimidating. Some people experienced in search might find it a bit limiting, but that’s when you can switch to using Google or an appliance. This is a nice balance to being a tool more powerful than the default search in something like WordPress, and not being something that takes hours to figure out.

You interact with Nutch via the $sitesearch viewtool, which just has a single method to worry about: $sitesearch.search($query, $sortBy, $startNum, $numRows, $request). This will return a DotSearchResults object that has a number of fields serialized in that you can call (assuming we’ve set the viewtool results to a Velocity variable called $results):

$results.responseType
$results.query
$results.lang
$results.reverse
$results.start
$results.rows
$results.end
$results.totalHits
$results.hits
$results.details
$results.summaries
$results.withSummary
$results.misspellings

Most of these are specifically details related to the search itself, such as the total hits it found, and alternative spelling suggestions. When you go to display the results, you’ll be working specifically with the .details and .summaries fields. For example:

#* PERFORM THE SEARCH FOR THE QUERY, STARTING
AT THE BEGINNING, GETTING 10 RESULTS *#
#set($results = $sitesearch.search($request.getParameter('query'), null, 0, 10, $request))
## PULL OUT THE DETAIL SETS AND RESULT SUMMARIES
#set($details = $results.details)
#set($summaries = $results.summaries)

#foreach ($i in [0..$math.sub($results.end,1)])
    
        $!{details.get($i).getValue('title')}

        $!{summaries.get($i).toHtml(true)}

        $!{details.get($i).getValue('url')}
    
#end

Overall, implementing Nutch isn’t particularly any more difficult or easy than it was to use Spindle, but level of control and improved results are what make the difference. This also shows off a very nice foundation that we can hope is used to develop an even more robust featureset down the road. Below, you can catch Dean’s walkthrough of the tool as well, where he shows how you enable and setup Nutch.

* NOTE: Windows users will need to install CYGWIN in order to use Nutch on Windows based machines and servers, due to the linux tools Nutch uses natively.

Photo Credit: Some rights reserved by morgan frederick.

User Role Based Custom Content

Michael Fienen — Tue, 28 Dec 2010 20:40:20 +0000

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

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

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:

## DEFAULT DISPLAY SETTINGS
#set($showAds = true)
#set($showNumAds = 2)
## CHECK FOR CHANGES TO DISPLAY DEFAULTS
#if($user)
    #if($cmsuser.isUserRole($user, "Level 2 Ads"))
        ## DISABLE ADS
        #set($showAds = false)
    #elseif($cmsuser.isUserRole($user, "Level 1 Ads"))
        ## REDUCE NUMBER OF ADS SHOWN
        #set($showNumAds = 1)
    #end
#end

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:

#if($showAds)

    #foreach($ad in $dotcontent.pull('+structureName:Advertising +Advertising.adGroup:1',$showNumAds,'random'))
    
        
            
        
    
  
    #end
  
#end

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: Some rights reserved by kelvin255

Apache and dotCMS: Happily Ever After

Xander Steinmann — Thu, 21 Oct 2010 12:55:55 +0000

dotCMS has many ways to handle multiple hosts, permission hosts and force https. But sometimes you just need more… For instance, you want a host to only be visible from certain IP’s or you want to password protect a site before it goes live. All things that could be handled by permissions or plugins if you wanted to, but Apache is there to easily solve these issues for you and give you extra functionality. This post will show you some examples. To start I will show you how you can easily set-up Apache on your server.

Hooking up Apache with dotCMS

Apache will allow you to run multiple web containers on your server. This means that you can have multiple dotCMS instances on your server or, for instance, you can have JBoss running next to dotCMS. And you can have this running within an hour! The only things you need to is download Apache plus mod_jk, configure Apache and set up an AJP13 connector in the dotCMS server.xml file. An example:

workers.properties (Apache)

# Define workers
worker.list=dotcms

#Set properties for worker 'dotcms'
worker.dotcms.type=ajp13
worker.dotcms.host=localhost
worker.dotcms.port=28009

worker.dotcms.cachesize=10
worker.dotcms.cache_timeout=600
worker.dotcms.socket_keepalive=1
worker.dotcms.recycle_timeout=300

The port 28009 in this case is the port of the AJP13 connector that you need to set in the server.xml of dotCMS. Note that since Apache will handle all the incoming HTTP calls, it should run on port 80 and DotCMS shouldn’t. On which port dotCMS runs is up to you (you can set it in the server.xml), as long as you match the AJP13 ports in the Apache workers.properties and the dotCMS server.xml and the port isn’t used already.

server.xml

Apache config

In Apache you need to configure your sites. You can add the following code in httpd.conf, or when you have many sites you can add it in seperate configuration files using the include command: Include conf/vhosts/*.conf


    ServerName myhost.com
    ServerAlias www.myhost2.com
    ErrorLog "logs/myhost-error.log"
    CustomLog "logs/myhost-access.log" common
	JkMount /* dotcms

The virtualhost mentioned above listens om port 80 for all IP addresses, and matches myhost.com and www.myhost2.com. For those hosts it has its own Apache logs and all the URLs that match /* are sent to the dotcms worker. I have built sites where all traffic is sent to dotCMS except the /service directory, which was sent to a local JBoss. All that is possible. When you have multiple hosts they should all listen on *.80 but have a different ServerName. Note that for SSL you need to set-up another virtualhost with port 443.

mod_jk

Apache needs mod_jk for the connecting. It’s not more than downloading a module and adding it in the httpd.conf. You can find mod_jk and a quick way to install it here.

Example: Password protect a folder/site

In Apache you can put a password on a (part of) a website. This is easily configurable and also easy to remove (no actual restart is needed!). This allows you to give a client access to a website without the entire world seeing it. You only need to add a few lines to your virtualhost in Apache, for instance using ‘location’ (more info, see here):


  AuthType Basic
  AuthName "Please Log In"
  AuthUserFile /password
  require valid-user

The above code adds a password to /* (everything), and the password file is located in /password. To create a password file, see here.

Example: IP filter

An IP filter can give certain IP’s access to certain sites. This is very useful when you’re working on a test server or when a site isn’t live yet but your client wants to see it. It can also be set-up with ‘location’:


  Order deny,allow
  Deny  from all
  Allow from 1.2.3.4           #our IP
  Allow from 5.6.7.8           #client IP

Example: Rewrite rules and https

You can use the very powerful rewrite rules of Apache as virtual links, you can force HTTPS on certain files/folders/sites and you can also force HTTP. Furthermore, you only need to set-up SSL in Apache and not in dotCMS which allows you to easily use multiple SSL certificates for multiple sites. You’ll need to download the mod_rewrite module of Apache to make this work.

The following example may be a bit tough, but if you try this out a bit you’ll see it’s quite easy to use. For more info see here.


  ServerName www.myhost.com
  ServerAlias myhost.com

  # Force all url's into non-SSL, except the ones that must be SSL
  RewriteEngine on
  RewriteCond %{HTTPS} =on
  RewriteCond %{REQUEST_URI} !^/protected
  RewriteRule ^(.*)$ http://%{HTTP_HOST}$1 [R,L]

  # Force the use of the www. subdomain
  RewriteCond %{HTTP_HOST} ^myhost\.com
  RewriteRule ^(.*)https://www.myhost.com$1 [R]

  SSLEngine on
  SSLCertificateFile "conf\ssl\mycertificate.crt"
  SSLCertificateKeyFile "conf\ssl\mycertificate.key"
  SSLOptions +StdEnvVars +ExportCertData
  SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL

Example: Useful redirects

When you migrate a website to dotCMS you lose some of the Google indexing since the names of the pages change (probably). In Apache you can define redirects so users get redirected (301) from .html, .jsp or .php to .dot. When you do that correctly Google moves the indexing data to the new URL, so your SEO doesn’t have to start from scratch.

RewriteRule ^/home.aspx$        /home/index.dot [R=301]

Conclusion

There is a downside in using Apache, even though it is not that big of a deal. You need to configure all the hosts of dotCMS in Apache as well (if you want to differentiate between hosts). But if you want to manage many hosts on one server, Apache is THE tool for you. And I always think that since dotCMS is a content management system, it should only worry about the content. Let other programs do what they’re good at. And the good part is that Apache has many other useful functions that you can use once you have it installed. It brings a lot of extra power and flexibility to using dotCMS.

(This isn’t all, by far. Don’t hesitate to post any other useful Apache functions that you use with dotCMS or comments about my examples)

Photo Credit: Some rights reserved by igb

oEmbed and JSON Plugins Available

Michael Fienen — Tue, 14 Sep 2010 19:03:40 +0000

Today, I am announcing the release of two new plugins for dotCMS, available now. The reason I am announcing them together is because the macro relies on the viewtool, but the viewtool has applications beyond the macro, so I didn’t feel that it was right to make it one big plugin. Also, the viewtool is only necessary in dotCMS 1.9 or lower. It is built in to dotCMS 1.9.1.

The viewtool is a fairly simple, straightforward implementation of the JSON Java class. Like the XML viewtool, it allows you to request JSON data via a URI, bring it into Velocity, and use it to manipulate information on a page. In the case of these plugins, the oEmbed macro uses it to request the JSON representation of an oEmbed object, and fetch out the values needed to display the content. As noted, this viewtool has been included in the trunk code for the upcoming 1.9.1 dotCMS update, so this plugin is only necessary if you are on 1.7 or the base 1.9 install. The viewtool plugin is mapped to the same key, so if you install it on a 1.7/9 system and then upgrade to 1.9.1, just remove the plugin and nothing should break. Beyond that, you can use it to process any other JSON data sources that you need.

[ Download JSONTool Viewtool Plugin (v1.100914) ]

#set($jsonData = $json.fetch('http://oohembed.com/oohembed/?url=http%3A//www.amazon.com/Myths-Innovation-Scott-Berkun/dp/0596527055/'))
$!{jsonData.get('title')}

#set($mymap = $contents.getEmptyMap())
#set($dummy = $mymap.put('one','value 1'))
#set($dummy = $mymap.put('two','value 2'))
#set($dummy = $mymap.put('three','value 3'))
#set($myjson = $json.generate($mymap))
$!{myjson}
The value of key 'one' is $!{myjson.get('one')}
-----------------------------------
AND THIS IS THE EXPECTED OUTPUT
The Myths of Innovation

{"two":"value 2","one":"value 1","three":"value 3"}
The value of key 'one' is value 1

The second plugin is a macro that allows you to add oEmbed sources of data to your site, and it requires the JSONTool viewtool, either as a plugin or in 1.9.1, because it uses the oohEmbed API to set up the embed code which responds with JSON data. Using an oEmbed compatible URI, the #oembed() macro will fetch the applicable code and allow you to embed it on your page. This is great for a simple way of embedding YouTube or Vimeo videos, or images from Flickr, as well as many other services. The oohEmbed website lists all of the sites they currently support.

[ Download oEmbed Macro Plugin (v1.100914) ] (requires the JSON viewtool!)

Macro Syntax:

#oembed('sourceURI')

Arguments

sourceURI:
This is the only require parameter and should represent a well-formed oEmbed compatible URI (see the respective web site for proper URI formatting).
oembedH:
Define the height of the oEmbed object (optional, velocity variable). Default: JSON oEmbed height value
oembedW:
Define the width of the oEmbed object (optional, velocity variable). Default: JSON oEmbed width value
oembedClass:
Provide a specific class name for the embed div wrapper (optional, velocity variable). Default: ‘oembedMedia’
useThumbnail:
Boolean value, allows you to display the thumbnail with a link to the resource url. Only works with ‘photo’ type oEmbed data (optional, velocity variable). Default: false

Example:

#oembed('http://www.youtube.com/watch?v=dQw4w9WgXcQ')

Advanced Example:

#set($oembedH     = 267)
#set($oembedW     = 400)
#set($oembedClass = 'oembedFlickrPhoto')
#oembed('http://www.flickr.com/photos/fienen/4965817454')

Email from Velocity

Chris Falzone — Wed, 01 Sep 2010 20:15:58 +0000

The more applications I build in dotCMS, the more I find myself trying to accomplish them with just Velocity coding. This saves me from having to create a plugin and make sure it is maintained through my systems. However, lately I have needed to write a lot of Form Handling with dotCMS. Not your basic, send an form to an email kind of thing either. The stuff I have had to work on is more on piping the form entry through some logic and then starting some kind of workflow. I have been fairly successful writing these forms up and handling them using the #getSQLResults macro. The one piece that I have not been able to do with just velocity is send a notification or confirmation email.

The scenario is that we have a form, this form needs to be processed in some manner and then inserted/updated into a database table, and then an email needs sent to a specific person that there is a new or updated entry. This is a very common scenario. Currently to do this in dotCMS without Java Coding of some sort would be a challenge, if not impossible. DotCMS does have some of it’s own form handlers, but I find that in many cases I need to perform some logic with the data before passing it on. The new Form Handler in dotCMS 1.9 has a lot of promise, but unless you plan on paying for an Enterprise License, I am going to consider that option out. That leaves me with building my own custom form handler.

Staying with the idea that I want a purely Velocity Form Handler; I can perform my logic, and use the SQL macro to insert or update my database (Note: you cannot insert or update to the dotCMS tables, you will need to have your own tables or an external database). The only thing I cannot do currently is send an email. Unfortunately the answer is that I have to bring this functionality to Velocity in the form a ViewTool. It’s going to take some Java, but my hope is that for anyone else looking to do similar things will be able to deploy my simple plugin and get moving.

The code for sending an email with Java can be found easily enough from Google. It is a fairly simple matter to take this code and turn it into a usable viewtool. Here is the plugin in all it’s glory:

[ Download the zip here ]

To use this plugin simply download the zip file and extract it to your plugins directory. You will need to edit the conf\plugin.properties file and change your mail stmp server setting. Stop your dotCMS instance. Then in a command prompt, in the base directory for your dotCMS install execute the following command:

ant clean-plugins build-plugins deploy-plugins

Once that is done, you can restart your dotCMS instance and you are ready to send emails from velocity. Here is a quick code example to show you how.

#set($to   = "cfalzone@edinboro.edu")
#set($from = "test@edinboro.edu")
#set($subj = "Testing Mailer")
#set($body = "This is a test")
#set($html = "This is a Test")

#set($err = $mailer.sendEmail($to, $from, "$subj (TEXT)", $body, false))
#if($UtilMethods.isSet($err))
   TEXT Error:  $err 
#else
   TEXT sent ok 
#end

#set($err = $mailer.sendEmail($to, $from, "$subj (HTML)", $html, true))
#if($UtilMethods.isSet($err))
   HTML Error:  $err 
#else
   HTML sent ok 
#end

As you can see the simpleMailer plugin will allow you to send either Plain Text or simple HTML messages. I have not implemented file attachments. One thing to note is, due to the way dotCMS works, when you hit a page in the editor, it loads it once for Edit Mode, once for Preview Mode, and once for Live Mode. This means if you put this code in a page you will get the emails 3 times each.

I hope it helps someone out there trying to do the same thing as I am. I think this is pretty essential tooling for dotCMS, so hopefully I can convince the folks at dotCMS to include this viewtool with the standard set in the future. There are of course many improvements you could make to this. You could add the ability to add attachments. You could add the ability to use a dotCMS page or template as a wrapper for your email.

Photo Credit: Some rights reserved by soapbeard

Guide to Images

Michael Fienen — Thu, 22 Jul 2010 21:24:21 +0000

Images are highly important to web content. There are numerous ways in which one can incorporate them into a page to enhance what is there. In dotCMS, you are presented with several ways in which you can implement and manipulate image files in your system. Today, we’ll be reviewing several of them.

First off, one of the most common ways that you will work with images is right in a structure. Structures support image specific upload fields that you can then access from the content map on a page or in a widget to display them. However, many newcomers quickly learn that it’s not as simple as just echoing out $content.image onto a page, since that only returns an identifier for the image. When an image is uploaded via a field in a structure, a number of fields are actually created and added to the contentlet, all of which you can access and use. Those fields are:

ImageExtension
ImageFriendlyName
ImageIdentifier
ImageInode
ImageName
ImagePath
ImageTitle
ImageURI
ImageHeight
ImageWidth

So in a page, assuming you have a structure with an image upload field simply named “image” an example of some of these fields in use would look like:

## MAKE SURE AN IMAGE IS ACTUALLY SET
#if($UtilMethods.isSet($content.image) && $content.image != '0')

#end

Alternatively, it’s possible to use dotCMS’s /dotAsset servlet functionality to get the same result using other fields:

## MAKE SURE AN IMAGE IS ACTUALLY SET
#if($UtilMethods.isSet($content.image) && $content.image != '0')

#end

Either example returns the same end result in the browser, all that changes is the path to the image. That’s all there is to basic image embedding. But, we’re not nearly done. Let’s say you have users who sometimes upload pictures that are way too big for a space, so you need to scale them down. That is where the /resize_image servlet comes in handy, which can create scaled versions of images on the fly for you.

Example of conditional /resize_image

#if($UtilMethods.isSet($content.image) && $content.image != '0')
    ## SEE IF THE IMAGE IS OVER 250 PIXELS WIDE
    #if($content.imageImageWidth > 250)

    #else

    #end
#end

Using that example, we can restrict our code to a specific width, and if it’s over it, force it down to the maximum allowable size. But wait, there’s more! You can play values against each other:

#if($UtilMethods.isSet($content.image) && $content.image != '0')
    ## SEE IF THE IMAGE IS OVER 250 PIXELS WIDE
    #if($content.imageImageWidth > 250)
        ## CHECK IF IT IS PORTRAIT OR LANDSCAPE
        #if($content.imageImageHeight > $content.imageImageWidth)

        #else

        #end
    #else

    #end
#end

Depending on landscape or portrait, this image's size will change

Note that this time I see if the height is more than the width, if it is, I use the maxw and maxh values (If you use one of the max parameters, you must use them both, unlike h and w, which can be used individually). This kind of code can help prevent image blowouts if you are unable to predict whether a portrait or landscape image is going to be used, so that after scaling one side down, the other side can be kept within additional length constraints.

Now that you can use images from structures and do some manipulation with them, let’s look at a few other image tools in dotCMS. There are a couple servlets and macros that are designed to give you a means of putting images on pages and doing things with them. /resize_image you are already familiar with from the previous example. Another servlet is the /thumbnail servlet, which is very similar to /resize_image and is used as an exactly the same, except that it also is capable of producing a background fill around images by including the parameters r, g, and b to represent the RGB values you want to use for the border (each one from 0 to 255). Some macros to take note of are: photoCarrousel(), titleImage(), slideshow(), photoGallery(), and randomImage(). Usage of the macros is more extensively covered in the dotCMS documentation, which will give you more information on customization variables.

A 250x250 thumbnail with a blue RGB value

The /thumbnail servlet has a fairly simple purpose: It scales an image down to fit inside the parameters you give it, and fills any remaining space around the image with the background color you set. For example, if you have an image that is 640×480, you can set the height and width 320×320. The resulting image will scale the longest side down to 320 (in this case the width), and the resulting space above and below the image would be filled in 40px above and below it (320 = (480/2) + (40*2)). The difference here between /thumbnail and /resize_image is that if you told /resize_image to have a height and width of 320, the image would get stretched and pulled out of proportion while /thumbnail will always scale the longest side to fit inside the proportions and fill the leftover.

Thumbnail Example:

...or...

Let’s try a somewhat more advanced example of image manipulation. Let’s say that you have a structure for products that includes a header image field. What you would like to do is put a widget on the page to display the product; it should show the specific header if one has been provided, and if one hasn’t, then show one at random from a group of generic banners you have already designed.

Set up a header image based on conditionally supplied image with fallback:


#if($UtilMethods.isSet($content.headerImage) && $content.headerImage != '0')
    ## SEE IF THE HEADER WIDTH IS WHAT IT SHOULD BE, RESIZE IF NOT
    #if($content.headerImageImageWidth != 640)
    
    #else
    
    #end
## IF AN IMAGE ISN'T SET, USE A MACRO TO GET ONE AT RANDOM FROM A FOLDER
#else
    ## GETS A RANDOM IMAGE AND RETURNS IT AS $image
    #randomImage('/global/images/generic-product-headers')
    
#end

Example of an image resized down and then cropped with a div

I have one last trick that I want to share that’s part Velocity and part CSS. One thing that the /resize_image servlet can’t do is crop images, which is pretty handy when you need to fill a space that is a set size, and you can’t predict the height and width of an image. For instance, making a rectangular image fit a square, or vice versa, without it looking squished or stretched. There are some jQuery tools for this, but they have to use the original file, which if it is very large, can be inconvenient for download speeds. This method shrinks the image to the shortest side, and centers it using a

as a container.

Scale and crop image using Velocity and CSS:

## MAKE SURE AN IMAGE IS THERE
#if($UtilMethods.isSet($content.imageImageURI))
    ## SEE IF IT'S TALLER OR WIDER AND SET THE APPROPRIATE SIDE MAX LENGTH
    #if($content.imageImageHeight > $content.imageImageWidth)
        #set($imageSize = "w=250")
    #else
        #set($imageSize = "h=250")
    #end


#end

So that’s that, a look at getting images out of content and folders and into pages and widgets. Feel free to share any other tricks you’ve learned in the comments.

Comparing /resize_image in 1.7 vs. 1.9

Both images resized from the same 606kB, 1024x768 pixel original file

There have been some questions recently regarding the quality of of images produced by the /resize_image servlet in 1.7, and if it has been improved in 1.9. There have indeed been changes in 1.9. However, my understanding is that while the logic wrapping the servlet has been modified, the core library codec (sun.awt.image.codec.JPEGImageEncoderImpl) has not. So, what does this mean? Well, if you look at the comparison to the right, very little. Actually, it would seem the image quality has actually gone DOWN in 1.9, with more JPG artifacts being introduced than previously. However, this is offset by the fact that the image size has been substantially reduced. So it’s half of one, six of a dozen of another. There is now a config property in the 1.9 dotmarketing-config.properties file that sets DEFAULT_KEY_ANTIALIASING=java.awt.RenderingHints.VALUE_ANTIALIAS_ON, but looking at the final results, it doesn’t seem to be having an effect on smoothing the lines out or preventing hard, pixelated edges for the most part (though to be fair, the darkest, top part of the stem of the central flower does look slightly better in 1.9, that’s still offset by the fact that the highlights are clearly jaggy).