Hey All,
At ECS Greg Amerson and I did a workshop to show how, using freemarker & it's JSP Tags support, to overload portal/plugin jsps from your theme.
I can't say it was easy to achieve the understanding to do get everything working, but we finally did and I just wanted to highlight the caveats that caused some pain (and hopefully from here it'll make it easier for everyone else).
So, without further ado, here they are:
*Freemarker doesn't accept '-' (dash) in identifiers* including taglib or tag names (more on this later).
Initializing a taglib for use If the taglib belongs to the portal:
<#assign portlet = [b]PortalJspTagLibs[/b]["/WEB-INF/tld/liferay-portlet.tld"] />
If the taglib belongs to the theme (bundled with the theme plugin)
<#assign taglib = [b]ThemeJspTaglibs[/b]["/WEB-INF/tld/taglib.tld"] />
If the taglib contains a '-' (dash) in it's name, I would suggest a convention like:
<#assign [b]liferay_ui[/b] = PortalJspTagLibs["/WEB-INF/tld/liferay-ui.tld"] />
Using JSP Tags The syntax is strange and foreign but I guess we have to live with it. There are two syntax but in the Liferay tradition I will only show and suggest the one that works for all cases. I repeat the fact that freemarker doesn't work with tags that contain dashes in their name. This means we have to use the "map" syntax to call them. It also means we have to use the "short" closing tag syntax as well (not officially, but I couldn't get it to work consistently using the long form):
<@[b]liferay_ui["message"][/b] key="message" />
And the short closing tag syntax
<@liferay_ui["panel-container"] cssClass="message-boards-panels">
...
[b]<!--@-->[/b]
Handling tag attributes You can only quote string literals
<@liferay_ui["message"] [b]key="message"[/b] />
When assigning objects (and remember there are no primitive types in template languages usually) you don't quote them
<@liferay_ui["message"] [b]key=myKeyVar[/b] />
What about complex assignments then? I suggest another convention, use parentheses around complex/object assignments.
<@liferay_ui["search-container-column-text"]
href=(rowURL)
name="my-column"
value=[b]("something" + 15 + "something else")[/b]
/>
Note that freemarker provides "builtins" for conversions so that for instance you can assign numbers to string attributes:
<@liferay_ui["search-container-column-text"]
href=rowURL
name="posts"
value=(categoryDisplay.getSubcategoriesMessagesCount(curCategory)[b]?string[/b])
/>
Accessing Static classes' methods and/or fields You have to jump through a hoop here and leverage a utility of freemarker to wrap the static class so that it exposes the methods and/or fields
<#assign ParamUtil = [b]staticUtil[/b]["com.liferay.portal.kernel.util.ParamUtil"] />
After that, usage is as simple as:
<#assign portletResource = ParamUtil.getString(request, "portletResource") />
Initializing an instance of a class Here you have to also leverage a freemarker util or wrapper
<#assign rssURLParams = objectUtil("com.liferay.portal.kernel.util.StringBundler") />
Finally, I've attached a sample similar to what I used at ECS-2011 (with a few changes to match above recommendations).
The big points here is that you can achieve per theme UI changes so that you can apply those to only portions of your site(s), doing things like using AUI tags in your themes. You could make the same APP have completely different UIs in different sites without touching the core. You can even have this apply technique to jsps in plugin portlets.
Note: In order to see this in action you first
have to apply it to a page or site, and then
make a Message Board Category of type "Question". Once you navigate into this category you will see the message "this-is-the-overloaded-view" just under the Category name.
Hope it helps!
