FreeMarker pagination macros

I couldn’t find a good set of macros to help navigate through paginated data so I wrote my own. The macro names echo the names of the CakePHP PaginationHelper functions because…well, they’re reasonably sensible.

The macros expect you to add a model attribute called “paginationData” which contains (at least) the following properties:

pageNumber -> The current page number
pageSize -> The number of items in each page
pagesAvailable -> The total number of pages
sortDirection -> The sorting direction (ascending or descending)
sortField -> The field currently sorted by

In my implementation, my paginationData also contains a property called “pageItems” – the actual items in this page.

The macros available to you are:

  • first
    Outputs a link to the first page
  • last
    Outputs a link to the last page
  • next
    Outputs a link to the next page
  • previous
    Outputs a link to the previous page
  • numbers
    Outputs links to other pages. The macro takes a parameter called “maxPages”, which is the maximum number of pages that should be output. There is also a second parameter “separator”, which is the text/html that should be output between each page link.
  • page
    Outputs a link to a particular page. It takes the page number and link text as parameters. If you omit the link text it’ll default to the page number
  • counter
    Outputs the current page number and the total pages e.g. “1 of 20″
  • sort
    Outputs a link to sort by a field. Takes the field to sort by as its first parameter. If field is different to the current sort field, the link will change the sort field but not the sort direction. If the field is the same as the current sort field, the link will change the sort direction. The second parameter is the link text, which defaults to the field name with an upper case first letter. It also takes a parameter called “directions”. This is an an array of two items: the words being used in paginationData.sortDirection to describe the sorting direction of ascending or descending. Default: ["Asc", "Desc"]. So it can compare the current sorting direction and switch to the converse.

Note, ordinarily you’ll probably not need to use the “page” macro.

How to use

In Java, add a model attribute “paginationData” containing the properties I’ve described above. Then, in your view, import the library:

    <#import "pagination.ftl" as pagination />

Call the macros:

    <nav style="float:right;">
        <@pagination.first />
        <@pagination.previous />
        <@pagination.numbers />
        <@pagination.next />
        <@pagination.last />
    </nav>
    <@pagination.counter />

Which’ll give you something like:

For table headings that allow sorting:

    <table>
        <tr>
            <th><@pagination.sort "forename" /></th>
            <th><@pagination.sort "surname" /></th>
            <th><@pagination.sort "email" /></th>
            <th><@pagination.sort "created" "Registration date" /></th>
        </tr>
        ...
    </table>

Download

You can download the pagination macros here.

How to switch to/from HTTPS using Apache as a proxy to Tomcat

I’m writing this down because it too me an age to figure out a way of doing this. I have a website which Tomcat is happily serving. Areas of the site require a secure connection so I’m using Spring security to require particular URLs to be accessed over HTTPS. It means that when I access http://example.org:8080/webapp/login, it’ll bump me to https://example.org:8443/webapp/login. Note: Tomcat is setup with the SSL connector and a self signed .keystore see (http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html).

I have two vhosts setup in Apache, one for the http://example.org and one for https://example.org. They are both using mod_proxy to ProxyPass and ProxyPassReverse requests to the appropriate Tomcat URL’s. The problem comes when switching to HTTPS from HTTP and vice versa. Ideally I wanted some sort of ProxyPassReverse declaration in my config for http://example.org what would change HTTP headers (that Spring sets) for https://example.org:8443/webapp into https://example.org. Except ProxyPassReverse doesn’t work like that.

Now, I realise I could simply not use Spring to manage which parts of the site should be accessed over HTTPS and which should not…and just setup Apache to redirect as appropriate. I don’t want to do that though, because that makes the task of adding these restrictions a deploy time task, rather than a development time task. I don’t want to risk someone forgetting to add new restrictions when deploying the webapp and I’d much rather the developer added these restrictions when they were working on the task and really thinking about where and when they are needed.

So, how do I solve the problem so that the app can manage its secure-ness and I can setup Apache once and forget about it? The answer is to ProxyPassReverse onto a “special” URL, which when accessed will redirect to the HTTPS (or HTTP) site. For example, if the HTTP site needed to redirect to the HTTPS site, I’d add rules like so to perform the redirect:

    # Proxy a request (from the server) to switch to https onto a special URL "/2https/"
    ProxyPassReverse /2https/ https://example.org:8443/webapp/

    # When a client requests a URL prefixed with "/2https" map it onto the secure site
    RewriteRule ^/2https/(.*)$ https://example.org/$1 [R,L]

…and you’d add something similar to the secure site Apache config. As long as I don’t mount any pages at /2http or /2https I should be ok. Note a couple of things:

  • You’ll need “SSLProxyEngine on” and “RewriteEngine on” and obviously the appropriate Apache modules loaded for these commands.
  • Because of the redirect between HTTP <-> HTTPS you won’t be able to POST data between them directly (I’m not sure why you’d NEED to though)
  • Obviously you’ll need to setup Apache with an SSL certificate…but that is a different story

I should say a special thanks to this random site – from whence the idea actually came from. If anyone has any better ideas on how to do it I’d love to hear them. Please comment below.

Simple FreeMarker random number generator

FreeMarker doesn’t have a random number generator function. I needed a really simple solution that would allow me to pick a random image URL to be displayed on the homepage.

<#--
* Generates a "random" integer between min and max (inclusive)
*
* Note the values this function returns are based on the current
* second the function is called and thus are highly deterministic
* and SHOULD NOT be used for anything other than inconsequential
* purposes, such as picking a random image to display.
-->
<#function rand min max>
  <#local now = .now?long?c />
  <#local randomNum = _rand +
    ("0." + now?substring(now?length-1) + now?substring(now?length-2))?number />
  <#if (randomNum > 1)>
    <#assign _rand = randomNum % 1 />
  <#else>
    <#assign _rand = randomNum />
  </#if>
  <#return (min + ((max - min) * _rand))?round />
</#function>
<#assign _rand = 0.36 />

I’ve added this function to the FreeMarker Spring extensions I’ve been building up. You might use it in your code like so:

<img src="<@spring.url "/images/" + springx.rand(1, 10) + ".jpg" />" />

Note that there are obvious issues with this function. Aside from being based heavily on the second the function is called, you’ll notice that the min and max have less probability of being generated as the other values…what? I said it was simple.

Java interface and implementation naming (or “I” or “Impl”)

How do I name my interfaces and the classes that implement my interfaces? Through much research on the internet and my own gut feelings, this is what I reckon:

I never prefix my interfaces with “I”. The value of coding to interfaces is that you can swap out the implementation with minimal hassle. It means that instead of using implementation specific class names in your code, you use interface names instead – right? So, if I’m going to be using interface names everywhere, I don’t want to have to prefix everything with “I”. Coding to interfaces is a best practice, so I don’t need to explicitly state that I am doing it…It should just happen – which makes the “I” prefix redundant.

Furthermore, the “Impl” suffix is also redundant. Yes, indeed, your dilemma isn’t as simple as picking between the two. Firstly, “Impl” doesn’t translate. “Impl” in other languages has no meaning, and yes I’m talking about Polish and Scala. In Polish (according to Google translate), “implementation” is “realizacja” and in Scala, there are no interfaces. The closest thing Scala has to interfaces is traits, which can contain implementation specific code. So really, everything is Scala is an implementation, so why you use “Impl” suffix?

Secondly “Impl” is restrictive. What happens when you want to add another implementation of Foo? You gonna call it “FooImplImpl”? “AnotherFooImpl”? “FooImpl2″? I didn’t think so. Perhaps you were going to just call it “FooImpl” and put it in a different package…

Thirdly “Impl” doesn’t convey any meaning about what the implementation is. You wouldn’t create an “AnimalImpl” would you? You’d create a “Lion” or an “Elephant”. There is almost always something that distinguishes your implementation that you can use in the class name. Even if it is a long name, it doesn’t matter – you’re coding to interfaces (remember?), so you’re rarely going to see that class name.

Lastly, and probably most importantly – you still can’t think of a name? You don’t need an interface. If you really can’t think of a name, your class must be generic enough to not need an interface and you’re probably not going to have any other implementations. Your class methods become the interface contract, and that is that.

LESS CSS clearfix

The fantastic clearfix, as a LESS CSS class:

.clearfix {
    zoom: 1;
    &:before, &:after {
        content: "";
        display: table;
    }
    &:after {
        clear: both;
    }
}

Use in your code like so:

ul#gallery {
    .clearfix;
    li {
        float: left;
    }
}

Easy.

Extensions to Spring’s FreeMarker macro’s (spring.ftl)

Spring’s FreeMarker macro’s are pretty useful, but there are a couple of things I need from the showErrors macro that simply aren’t there:

  1. Show errors without a HTML tag around them – if you don’t specify a classOrStyle, the showErrors macro will wrap your error message in a <b> tag. If you do, it’ll wrap it in a <span> (understandably)
  2. Pick the tag that surrounds each message – As explained in the first point, you can see we only get the choice of <b> or <span>. What if I wanted to use an <li>? …use the separator? – no good, because unless I write an <#if> statement to check the number of error messages before I call showErrors I’ll end up with redundant <ul>/<ol> and <li>’s in my markup if there aren’t any errors:
    e.g. <ul><li><@spring.showErrors “</li><li>”/></li></ul>
    Which leads me nicely onto the next point:
  3. Show errors in an ordered/unordered list, automatically detecting zero messages and not outputting markup if this is the case
  4. Show errors for multiple bind paths – Spring’s showErrors only shows errors for the currently bound field. However I’ve found that I’ve needed to show errors for 2 or more fields together. This is particularly true of a DOB field where the day/month and year are separate <select>’s
  5. Finally, show errors for multiple bind paths, in an unordered/ordered list

You can download my Spring extensions here: springx.ftl. Inevitably I’ll find more bits and pieces to add and will update them accordingly.