Saturday, November 22, 2008

Vertically formatted CHECKBOXLIST - struts 2

This is one tricky point encountered by myself when creating
checkboxlist with struts 2. The default 'xhtml' them will always rendered
horizontally formatted list into the page. To have vertically formatted checkboxlist, we have to overwrite the default FreeMarker template for checkboxlist component.
If you check carefully, you can find the set of templates files
written in FreeMarker for each theme of struts 2 from struts-core.jar file inside the template folder. Here, I am going to overwrite the template file for checkboxlist component to have vertically formated checkboxlist.
Consider fallowing HTML mark up rendered into the view page from
checkboxlist component. It tries to list the users of the system preceding with a checkbox. User id has been set as the value of each checkbox.

<input type="checkbox" id="users-1" value="1000" name="users"/>
<label class="checkboxLabel" for="users-1">administrator</label>
<input type="checkbox" id="users-2" value="1001" name="users"/>
<label class="checkboxLabel" for="users-2">siriwardana</label>

You will get the fallowing out put.

This is a mark up of horizontally formated checkboxlist. If we can add additional '<br>' tag after each of this <label> tag, we are done !. We can have a vertically formatted checkboxlist. We have to overwrite checkboxlist.ftl file located at template/xhtml in struts-core.jar file. I do not suggest you to change this file. Instead, we will create a new theme. To create a new our own theme, create a folder called 'template' under /WEB-INF/classes. Then create a folder with new theme name. In my case, I created a folder called 'pda' and copied all the template files from default xhtml folder to pda folder. Now, I am going to change the checkboxlist.ftl file located at pda folder.

We will look at the contents of this file for a moment.

<#include "/${parameters.templateDir}/${parameters.theme}/controlheader.ftl" />
<#include "/${parameters.templateDir}/simple/checkboxlist.ftl" />
<#include "/${parameters.templateDir}/xhtml/controlfooter.ftl" /><#nt/>

This is written in FreeMarker. I guess, now you know what we have to do is. You can see, this has included checkboxlist.ftl file from default simple theme. We have to edit that file. Again, I am going to overwrite the default simple theme comes with struts 2 for my new theme. I am creating a folder called "pda_simple" under the /WEB-INF/classes/template and copy the checkboxlist.ftl file from default simple theme folder to pda_simple folder. Before edit this checkboxlist.ftl file, we have to change the file path of checkboxlist.ftl file located at pda folder as fallows.

<#include "/${parameters.templateDir}/${parameters.theme}/controlheader.ftl" />
<#include "/${parameters.templateDir}/pda_simple/checkboxlist.ftl" />
<#include "/${parameters.templateDir}/xhtml/controlfooter.ftl" /><#nt/>

Now this refers checkboxlist.ftl file from our new simple theme which is pda_simple. To control the alignment of our checkboxlist component, I am going to use the cssStyle attribute of the checkboxlist component. Here is the my view code.

<s:form action="deleteUser" method="POST" theme="pda">
<s:checkboxlist list="users" name="users" listKey="userId"
listValue="userName" cssStyle="vertical">
<s:submit value="update"></s:submit>

From above code, I want your attention on theme attribute of form component and the cssStyle attribute of checkboxlist component. I have specified our new theme for current form and cssStyle is set to vertical to have a vertically formatted checkboxlist.
Now, we have to edit checkboxlist.ftl file located at /WEB-INF/classes/template/pda_simple as fallows.

<#assign itemCount = 0/>
<#if parameters.list?exists>
<@s.iterator value="parameters.list">
<#assign itemCount = itemCount + 1/>
<#if parameters.listKey?exists>
<#assign itemKey = stack.findValue(parameters.listKey)/>
<#assign itemKey = stack.findValue('top')/>
<#if parameters.listValue?exists>
<#assign itemValue = stack.findString(parameters.listValue)/>
<#assign itemValue = stack.findString('top')/>
<#assign itemKeyStr=itemKey.toString() />
<input type="checkbox" name="${}" value="${itemKeyStr?html}" id="${}-${itemCount}"<#rt/>
<#if tag.contains(parameters.nameValue, itemKey)>
<#if parameters.disabled?default(false)>
<#if parameters.title?exists>
<#include "/${parameters.templateDir}/simple/scripting-events.ftl" />
<#include "/${parameters.templateDir}/simple/common-attributes.ftl" />
<label for="${}-${itemCount}" class="checkboxLabel">${itemValue?html}</label>
<#if parameters.cssStyle?exists>
<#if "${parameters.cssStyle?html}" == "vertical">

Actually you don't need to worry about the whole code above, but what I have highlighted. At the very beginning, I mentioned my target is adding additional <br> tag at the end of each <label> tag. I have done. There may be better ways of achieving this. This is how, I got through this. Finally, I got the expected output as fallows.


  1. This helped us a lot. Thank you.

  2. Thanks, this helped me a lot.

  3. mona bijjakda ooi meh?.. gonpart post karanna epa

  4. That was great, thanks a lot.

  5. Nice, very helpful. The only thing that I did differently is to make it use tr/td for each checkbox, instead of a bread

    XHTML uses tables anyway, so you can just piggyback off of that.

  6. Hi Dude,

    Thanks for the valuable article. Today i learned the new thing of how to create our own themes.

    Thanks buddy!

  7. Thanks, it is very self explanatory.


  8. nice

    -Prakash Mani

  9. Friend can you help me getting checkbox using colspan and left align.

  10. So helpful information, thank you very much!!!

  11. Excellent and very easy to follow. thanks a lot

  12. Its awesome .thank you very much :)

  13. Thanks man, this was really helpful and finally i got what i want and in a good logical way, esp applying cssStyle='vertical'