Ok, so don't. This doesn't mean you can't gain advantage of Liferay.

Also, what follows is not just a story about Sharepoint. If you have any HTML site of any kind you can gain advantages from using Liferay.

Liferay has this crazy simple mechanism called "widgets". Yup widgets!

The term has been used, we know, but Liferay has seriously had this feature since at least version 5.1.0 (possibly earlier) and yet I NEVER hear anyone talking about, or taking advantage of it.

Sure you can use Liferay as a WSRP provider and/or use other thick integration technologies like Web Services. You could even build Open Social apps on Liferay as full fledged gadget server (and also a client on whatever site you want to ingrate into).

However; "widget" are dead simple! AND they require only an HTML client! Nothing else!

Q: "Where do I sign up???"

It's extrelemly simple. Let's build an example.

Imagine you have a Liferay portal running somewhere (this is of course required).

Now, suppose on that portal you have a portlet on a page, and let's say the page is:

http://host.my.tld/web/site/page

and on this page is portlet named: XYZ

It even happens to be instanceable, so the fully instanced portlet id is: XYZ_INSTANCE_1234

Wait! It also happens to be a plugin, it's not a native Liferay portlet, it's in a war called: XYZ_portlet.war (and so the context is XYZ_portlet), and so the fully full instanced, plugin portletId is: XYZ_portlet_WAR_XYZ_INSTANCE_1234

Ok, so given the page url, and the portletId above, we change the url to:

http://host.my.tld/widget/web/site/page/-/XYZ_portlet_WAR_XYZ_INSTANCE_1234

If everything is working as it should what you should see is a HTML page with ONLY the portlet in question; no headers, no footers (you can even tune the portlet's "look and feel" to show the portlet in borderless mode (Show Portlet Borders: uncheck, Save) so it integrates more smoothly with the host site).

You can even navigate around the portlet, clicking links, performing actions, and again if everything is working as it should, the portlet should remain in widget mode throughout. Even non-native (or plugin) portlets!!!

Now, back to this Sharepoint server you have, or the legacy website you can't, for whatever reason, get out of using. But you want to plug in the shinny new portlet you created (or existing one you want to use 'cause it's already designed and doing what you need/want).

On this host site, all you need is an iframe! That's it! Just an iframe which references the widget url you created earlier.

(In fact, you could probably even get out of using an iframe with some clever js which loads the content of an ajax request to the same url into some HTML container on the page. Adding a url or button event listener to handle the clicks via ajax requests can round out a pretty darn smooth integration.)

Now, you want to have that portlet behave in context of the user logged in from this other site? Sure thing!

Just plug in Liferay to whatever SSO you are using on the host site and BAM! you have integration!

I hope that helps someone out there.

Liferay has been slowly integrating an OSGi framework into it's core; not in the sense that Liferay will nessecarily run "within" an OSGi runtime itself (there are arguments for doing that, and it's possible to a certain extent but the gain just isn't in doing that just yet), more that Liferay will "host" and OSGi runtime within itself that Liferay will utterly control.

Why do this? Well, as I've stated many times before, Liferay is a complex beast with an intricate network of features, so many features in fact that the ocassionaly have such indistinct lines such as finding the where one feature ends and another begins can be difficult.

OSGi will hopefully play a part in 1) providing us with a lot of re-use of features we had ourselves partially implemented but for which there existed a fully specified implementation our in the larger java eco system. The savings those existing features can bring is one of many benefits. 2) A specified lifecycle for "modules" (a.k.a. bundles) also is a huge benefit, one we can simply use. 3) Dependency resolution and management is another piece we had started to implement but it was clear to me that this had already been done much more effectively than Liferay alone could implement, again as part of an OSGi specification.

The number of benefits is almost too great to list. However, one of the greatest advantages can't be discussed enough: Modularity. 

Modularity is something that Liferay is now learning to embrace. Hopefully in the future we'll see many more examples like the one I'm about to illustrate.

One of the things I spend a lot of time doing is running and debugging code. There are a number of challenges to doing this with such a large application as Liferay. It takes time to get up and running, the vast number of features sometimes makes it tricky to isolate just the right service calls in order to test some specific interaction. I'm most often running the portal in debug mode executed from my IDE (Eclipse). A favourite thing to do is, place a break point and then use the context evaluation to invoke some specific code (using the Display view). However, my main purpose for doing this is to be able to fire some operation often unrelated with the actual breakpoint position. Effectively I just want to execute some arbitrary code in the JVM.

What would be ideal is if I had a command line from which I could do the same thing.

Enter Gogo

The OSGi echo system provides that out there somewhere a bunch of smart people have specified some behaviors, how to build properly interacting bits of code, and provided I have the appropriate runtime for those bits, I can interconnect them with my own bits and compose a greater feature.

Gogo is an OSGi (hence java) command shell implemented by the Apache Felix community.

"Apache Felix Gogo is a subproject of Apache Felix implementing the OSGi RFC 147, which describes a standard shell for OSGi-based environments."

Installing this shell with Liferay (due to Liferay's new interated OSGi runtime) is almost too simple.

Step 1)

First we'll download the necessary bundles:

(Note: We could have even avoided this pre-download step, but due to a small logical bug in Liferay's integration, we'll have to download the bundles ahead of time. I'll be fixing this bug in the days to come.)

Step 2)

Enable Liferay's Module Framework

Place the following in your portal-ext.properties (or equivalent props file):

module.framework.enabled=true

Step 3)

Configure some initial bundles to start when the OSGi runtime starts in Liferay (still in  portal-ext.properties):

extra.bundles=file:/downloaded/bundles

Step 4)

Step 5)

Step 6)

You should see something like the following:

We have sheel access!

But what can we do with this?

The first thing I wanted to do was investigate how the shell works and how to customize the configuration.

Passing System Properties to OSGi bundles

One thing I should add is that OSGi bundles often have system properties specific to them, and in order to isolate these from potentially other osgi runtimes in the same JVM, Liferay provided a means of passing these as namespaced portal properties.

An example of this is passing a Gogo specific system property called gosh.home. And so I added that property to my portal-ext.properties (prefixed by module.framework.properties.):

e.g.

module.framework.properties.gosh.home=${module.framework.base.dir}

This places the Gogo shell's home directory within Liferay's osgi directory inside ${liferay.home}.

Gogo is then trained to look inside an /etc directory within it's gosh.home for configuration files.

In this folder I added two files.

gosh_profile (think bash_profile):

https://gist.github.com/rotty3000/4712530#file-gosh_profile

motd (a.k.a. Message of the day):

https://gist.github.com/rotty3000/4712530#file-motd

Now a restart and my shell appears like:

Awesome!

Executing commands

The shell offers many build in commands. Executing help will reveal many of the extra commands namespaced by providers. However these are executable without the namespace (the namespace is used for conflict resolution of two namespaces provide commands of the same name).

 

A few choice commands are:

ss (short bundle status)

diag (diagnose a problem bundle)

 

However, it's possible to add commands dynamically as well as use closures. This is where the real power begins.

You may note that we added a custom set of commands based on the java.lang.System class in the gosh_profile:

addcommand system (loadclass java.lang.System)

What this does is loads the class and assigns the public methods of that class under the system prefix. Executing:

system:getproperties

outputs all the system properties. In a similar fashion any class can be added as a set of shell commands.

Conclusion

Modularity via OSGi allowed me to easily add functionality not previously available in Liferay. I can now build out some commands that will enable me to quickly take actions which previously required me to find round about ways to achieve.

 

Well, that's all for today. It was simple and fun to extend Liferay with shell access, I solved my problem. It also demonstrates the power of OSGi since we didn't have to write a single line of code in order to benefit from it's well defined modularity and lifecycle specifications.

 

I'll talk more about shell commands, closures, and how to add and use custom Liferay commands in more detail in a future blog post. I'll also start using this shell to show how to start building small Liferay extensions using OSGi.

Eventually, more of the Module Framework features (such as the web extender) that Miguel and I have been working on will reach master and we'll start to discuss those as well.

 

 

I had planned to speak at this years North American Symposium about our ongoing work with OSGi. However, sadly due to several different factors that didn't happen.

It's too bad because as it turns out at least two dozen people asked me:

• What happened to the OSGi plans?

• Was it dead?

• When would it come?

• Was there a talk on it disguised as something else?

• some variation thereof

 

Likewise, I was asked:

• What does OSGi and Liferay together even mean?

• What is the relation?

• What is the value?

 

Clearing the air

 

1. The plan

Liferay's OSGi plans are not dead. My current focus, as far as development is concerned, is almost 100% OSGi. A usable form of OSGi integration will arrive in 6.2. There was no talk on OSGi at NAS, so you didn't miss anything.

2. The reasoning (why OSGi?)

Liferay is a large, complex application which implements it's own proprietary plugin mechanisms. While Liferay has managed well enough dealing with those characteristics over it's history, it's reached a point on several fronts where these are becoming a burden which seem to bleed into every aspect of Liferay: development, support, sales, marketting, etc.

(Disclaimer: I'm not part of support, sales or marketting. However, as a senior architect I see how each of those teams deal with the limitations imposed by those previously mentioned characteristics and how they impact the effectiveness of each team, and at times their level of frustration.)

How can OSGi make such a broad impact? you ask.

The impact doesn't actually come from OSGi at all. The impact comes from the outcomes resulting from designing a system using a modular approach.

"Modularity is the degree to which a system's components may be separated and recombined." - Wikipedia

Further to this general definition, you might consider that regardless of which context is used for obtaining a more specific one, it becomes quickly apparent that "modularity" is a benefit rather than impediment.

However, when we do look at a specific definition in the context of software design we see how it clearly applies and might relate to the aspects above:

"In software design, modularity refers to a logical partitioning of the "software design" that allows complex software to be manageable for the purpose of implementation and maintenance. The logic of partitioning may be based on related functions, implementation considerations, data links, or other criteria.” - Wikipedia

Plainly, a modular system allows that the interal details each module be altered without affecting other modules in the system. Imagine if this were true for Liferay on a wider scale.

• simpler delivery of hot fixes for bugs and/or security vulnerabilities

• more frequent delivery of improved or new features

• less bugs in critical modules due to higher degree of focus

• potentially smaller deployment footprint due to ability to limit functionality to desired modules

• greater robustness and resilience due to higher degree of care required in designing for consumption and re-use

 

OSGi is simply the best existing implementation of a Java modularity framework. So many of the less obvious concerns which become inherent needs in modular systems are already implemented in OSGi. There exists a number of very good implementations. They are widely adopted. They are heavily supported. The number of supported libraries grows daily, while even unsupported libraries are easily fixed.

 

In short, the benefits far outweigh the costs. There will surely be difficulties along the way, the largest being the fact that learning to implement in a modular way is often counter to how many of us have worked for so long.

 

I'd be very interested in any feedback that people have about this topic, so please let yourselves be heard.

At this year's Liferay North American Symposium I did a talk on Big Data.

The goal of the talk was to illustrate some cases where Liferay and the broad notion of "Big Data" intersect.

Most importantly I showed an example which stored Documents & Media portlet files in Hadoop's extremely scallable and fault tolerant Dynamic File System (a.k.a. HDFS).

The same example code also demonstrates how you might tee off the indexed result of these documents to store a copy in a separate location in HDFS so that it might be consumed as input for some MapReduce calculation in order to extract insight from it.

It demonstrates how to use the MapReduce API from a java client all the way from creating the job and sending it to submitting it for processing and then (basically) monitoring it's progress. The actual logic applied in the example is trivial, however the most important part is actually showing how you could use the APIs in making Liferay and Hadoop talk.

The code is on github as a standalone Liferay SDK (based on trunk but easily adaptable to earlier versions):

https://github.com/rotty3000/liferay-plugins-sdk-hadoop

Please feel free to fork it or use it as an example.

[update] I should also add a few links to resources I used in setting up hadoop in hybrid mode (single cluster node with access from a remote client, where my Liferay code is assumed to be a remote client):

• http://www.michael-noll.com/tutorials/running-hadoop-on-ubuntu-linux-single-node-cluster/
• http://hadoop.apache.org/docs/r1.0.3/mapred_tutorial.html
• http://hadoop.apache.org/docs/r1.0.3/single_node_setup.html
• http://blog.rajeevsharma.in/2009/06/using-hdfs-in-java-0200.html
• http://www.cs.brandeis.edu//~cs147a/lab/hadoop-troubleshooting/

I'm almost back home from San Francisco after yesterday's completion of Liferay's 2012 North American Symposium. I'm quite exhausted but what a great event to be a part of. For this small town Canadian boy, travelling to historic big cities to meet with old friends I rarely get to see face to face is an experience I will never take for granted. Every turn through the crowd there seemed to result in either heartfelt handshake and a great "Nice to see you again!" with a community member or client I'd met once or twice or even, dare I say, in a big hug from someone I've been working with for years but have really only met in person a dozen times, perhaps less. And the pride that comes from seeing what people have done and dream to do with the humble project I began participating in and was later allowed to earn a living from those many years ago is sometimes... overwhelming. But you can't help but stay grounded when you see the deep intensity and passion people bring. You want to make sure that doesn't get lost, and between the two there seems to be little room for pretentiousness. I'm honoured to be given the opportunity to do the work I do and I hope to keep doing it for a long time. Once again it was great to see you all. To those I already knew, I wish you continued good health and happiness. To those I met for the first time, I wish you luck in your endeavors and hope to see you again at other Liferay events or even elsewhere and happy. Thanks for having me.

In order to maintain its extensive deployment matrix, Liferay up to 6.1 has been locked to Java 5 APIs.

However, Java 5 started its EOL cycle on April 8th, 2007 and completely it on October 8th of 2009.

Furthermore the last app server that still required Java 5 has finally been EOL'd itself at the end of 2011.

This means that Liferay 6.2 is now free to adopt Java 6.

It's true that Java 6 itself is almost EOL (extended through Feburary 2013), but due to the transition period lasting an estimated 2 years for clients with support contracts, it means that many enterprise applications will remain Java 6 dependent untill the very end of the transition period which also demands that Liferay remain complient if it wants to retain those applications as part of the extensive deployment matrix it currently enjoys.

This of course in no way prevents 3rd parties from developing plugins/extensions against Java 7 or later as long as they accept the limitation this will have on deployment.

It was also suggested that the community should be informed (as the documents have not yet been updated) that building Liferay 6.2+ requires Ant 1.8 or greater. This is a minor point but can cause frustration if one is not aware.

Liferay has long had the ability to embed portlets in themes. This is convenient for implementors to get highly functional design into the look and feel of a site. In my years at Liferay I've seen and heard many different attempts at doing this with various levels of success. There are a number of things to consider when embedding portlets in the theme and the same method does not apply in all cases.

The original motive behind embedded portlets was for integrating WCM content or simple functional features such as Search or Language selection. As such the complexity of these portlets was understood to be low and without significant performance costs either due to not having any direct service calls (search & language selection portlets don't have any initial service calls), or having service calls which were highly cached (such as is the case with web content).

There is more than one technique for embedding portlets into the theme, and several different issues to consider when choosing any of those.

Method One: Using $theme.runtime()

This is by far the most common method. There are of course a few gotchas with this method.

1) it renders the portlet synchronously in the theme regardless of the ajaxable settings on the portlet ( via liferay-portlet.xml).

This means if the portlet is expensive to render because it a) has lots of data to process on render, b) uses synchronous web service calls, or c) calculates the fibonacci sequence up to a million, DON'T EMBED IT IN THE THEME! You're just killing the performance of your portal whenever that theme is on any page.

Rule of Themes #1: This is a good rule of thumb to follow regardless of embedded portlets or not: "Themes should be SUPER FAST! They should be the fastest component of your portal view at any given time."

If you don't follow this rule how will you expect the experience to be once you start actually putting more things on the page? It's a different topic entirely, but you should generally performance test your theme with no portlets on the page. Once you know it's blazing fast then proceed to test your portlets' performace.

But I digress! Back to portlets embedded in the theme.

2) portlets rendered in the theme don't have their js/css resources loaded at the top of the page with all the rest of the portlets. Liferay doesn't yet implement "streaming portlet" mode (this is optional in the spec, this doesn't mean Liferay is not fast, it's just a name they chose for the feature of calling the portlet's header altering methods separately from the rendering methods). So the issue with this is that if you embed a portlet that uses something like JSF dynamic javascript features and there happens to be more than one of this type of portlet on the page, the ordering of these dynamic resources may get fouled up and cause general mayhem to their behavior.

On the other hand, I would argue that such portlets are already, by their very nature, TOO complex and expensive to be embedded in the theme. They are quickly diverging from the rule above that the theme should be SUPER FAST!

Rule of Themes #2: "Only use $theme.runtime() to embed portlets that are extremely fast. If they make expensive service calls, MAKE SURE those are not calls that happen all the time, and MAKE SURE they use great caching."

 

Method Two: Ajax / Iframe!

This is a "currently" seldom used method, but one that I would HIGHLY recommend using! Why?

1) It's Asynchronous with the rendering of the theme. This is HUGE! It means that regardless how slow your portlet(s) is(are), the general experience of the portal will remain fast!

2) It means that you can still put that fairly complex portlet into the theme without killing the overall performace.

3) It doesn't suffer from the limitation of the resource loading that the $theme.runtime() method suffers from.

So how do I do it?

Ok, so generally what you do to embed a portlet via ajax or iframe is to create a portlet url (either server side or client side) and then request for it, placing it somewhere in the page. With an iframe you can of course interact with the portlet in place. If you use an ajax call and embed the output of the portlet directly it will of course cause page refresh.

Here is the code for doing it with the iframe:

 

One thing you'll note with this code is that it's making the assumption that the portlet is at the current page! But it's not on the current page yet!

There are a couple of ways of handling this.

1) The portlet is specifically designed to be in the theme and should be visible to anyone seeing the page.

In this case I recommend setting these attributes in your liferay-portlet.xml file:

These will allow your portlet to safely added to any page in the portal automatically (otherwise you may get permission issues because the user viewing the portlet may not have permission and all that jazz.)

2) You can't do as above because you still want to control permissions of the portlet using roles.

In this case, you'll have to add the portlet to something like a hidden page, from which you can manage it's permissions. When creating the url in the code above, you'll then use the page "plid" of that target page instead of the current one.

 

Well, I hope that helps!

I hope that I hear far less talk about $theme.runtime()issues and Liferay performance problems that end up being directly related to expensive operations embedded in the theme.

 

And please heed these words:

"Embed portlets with impunity! Just make sure to do it carefully!"

 

<bean class="com.liferay.arkadiko.BridgeBeanPostProcessor">
    <property name="framework">
        <!-- some factory to get an instance of org.osgi.framework.launch.Framework -->
    </property>
</bean>

 

I've taken to using github.com's gist service quite alot recently and so I wanted to just spread the word that there are some handy nuggets appearing there.

Here's the url https://gist.github.com/rotty3000.

Examples:

• list open and accessible sites (that a user could join, or may already be part of)
• a simple localization hook
• embed navigation tag directly without portlet
• get all RatingsEntry by user and asset type
• embed a portlet via js
• simple sample client for fileupload to dl, requires commons-httpclient and it's dependencies
• to add localizations in a theme, add this compile section your your build.xml and the languages in the usual location
• simple dialog (inline popup) with encoded (safe) content from a bean
• setting look and feel settings on a non-instancable portlet embedded in the theme (velocity and freemarker)
• portlet urls from PHP portlet

From others:

• How to Mavenize Liferay Plugins Ant build.xml (Kamesh Sampath)

 

I hope those prove useful. I'll continue putting things there as I come across them.

Also, there is an RSS feed of those if you want as well . (won't include ones I add by others)

Over the past several months I've been working on integrating an OSGi framework into Liferay Portal. The reasons for doing so are varied but include solutions to app server/servlet container dependency, library version conflicts, runtime module lifecycle, advanced extensibility, and so on.

If you are not familliar with OSGi, I recommend visiting the OSGi web site, and in particular reading the Benefits of Using OSGi.

The first publicly available code of this integration is available as an OSGi branch on my fork of the liferay-portal project on github.

The url of the branch is: https://github.com/rotty3000/liferay-portal/tree/OSGi

I'd like to encourage anyone having an interest in this work to clone the branch and send me feature improvements, bug fixes, etc, via git pull request, or even to just send me comments here.

 

Things I've done to date:

• I'm using Eclipse Equinox 3.7 (but it works with any 4.1 or greater implementation of OSGi with no code changes, I tested Knopflerfish 3.2.0 and it worked very well, I'm sure Felix would work equally well).
• Published all the services and beans of the portal's spring context as services in the framework so they can be used by bundles.
• Developed a management portlet available in the control panel where the portal administor can add/remove/start/stop/update bundles, see all the bundle headers, all the service registrations and all service references of any bundle. (I'd like to eventually add bundle dependency graphing as well).
• Make sure logging works (this can be tricky in OSGi due to libraries not due to OSGi).
• Setup an auto deploy listener that will inspect any jar/war file dropped into the portal deploy folder that are OSGi bundles and automatically install them into the framework (and try to start them).
• Setup a bridge Servlet which is wired into the OSGi HttpService to provide HttpServlet request dispatching for any servlets or jsps registered in the framework. (This feature depends on a bundle I created which I'm going to release in the comming days, in an OSGi branch of my fork of the liferay-plugins repository. The bundle depends on the eclipse equinox http servlet package which is available in the Equinox 3.7 zip.)
• I've successfully tested various code modification scenarios such as replacing a service implementation and replacing a Util implementation, with all the virtues of OSGi bundle lifecycle goodness.
• I've successfully deployed and used the recently released Gemini Blueprint implementation of the OSGi Blueprint specification (which you might call Spring for OSGi). It's a simple matter of deploying the 3 main bundles.
• I've added BND lib to the portal so that it can be used for various OSGi packaging tasks.

Things I'd like to do next:

• Make some changes to the Plugins SDK so that plugins can (optionally) be generated as OSGi bundles.
• Support deploying the various bundle-ized plugins into the framework.
• Support all the spring wiring of ServiceBuilder services found in plugins correctly.
• Setup a portal packaging system so that we can bundle as set of bundles/plugins so there is no need to assemble and install them manually.
• Modify the Liferay repository mechanism so that it supports bundles and implements either auto update or auto detectiong of possible updates for bundles in the repository (and also resolves/downloads dependencies).

 

Here are a couple of images of the OSGi Admin portlet.

List of bundles:

View of a Bundle:

 

I'll be presenting this work in a workshop at the upcoming West Coast Symposium in Anaheim on 21-22 of September.

I hope to hear your thoughs on this and maybe to discuss it with you at WCS.

To continue a recent string of theme related posts, I'm going to add another on the recently added feature allowing addition of advanced input controls and behaviors to theme settings.

Themes are the whip cream that bring flavour and sweetness to our portal fruit salads. Without beautiful and clever theme designs our fruit salad may taste healthy but can be bland and leave us wanting other treats.

To make sure this doesn't happen, Liferay tries its hardest, each generation, to bring new and/or improved features and richness to the theme APIs in order to empower designers to create master pieces.

One of the tools in the deisgners chest which was added in 6.0 and which added pretty significant flexibility to theme developers was the Settings API.

As the name implies, the Settings API is a mechanism that allows a designer to add configuration settings to their theme creations. These settings can then be used within the theme logic to do things like toggle features on or off, provide lists of options for display behaviors, provide boiler plate content fragments, etc. Using this API the designer can, with a single theme, attempt to provide a mixture of options that can potentially meet many more requirements and appeal to more users.

Using the Settings API

In order to use the settings API the designer must include a liferay-look-and-feel.xml file in their theme. The path should be:

<theme>/docroot/WEB-INF/liferay-look-and-feel.xml

As you might have guessed this is an xml file and a boiler plate file for 6.1 could be as trim as the following:

<?xml version="1.0"?>
 <!DOCTYPE
    look-and-feel PUBLIC
    "-//Liferay//DTD Look and Feel 6.1.0//EN"
    "http://www.liferay.com/dtd/liferay-look-and-feel_6_1_0.dtd">

<look-and-feel>
    <compatibility>
        <version>6.1.0+</version>
    </compatibility>
    <theme id="hotel" name="Hotel Theme" />
</look-and-feel>

Plainly enough this file defines the compatibility the theme has with different portal versions (in this case, since we're using features from 6.1 DTD, we're limiting our compatibility to 6.1+). It defines the theme element which contains the id of the theme as well as the name that will appear in the UI during theme selection/configuration.

In order to add settings we're going to add an element as a child of the <theme> element:

<?xml version="1.0"?>
 <!DOCTYPE
    look-and-feel PUBLIC
    "-//Liferay//DTD Look and Feel 6.1.0//EN"
    "http://www.liferay.com/dtd/liferay-look-and-feel_6_1_0.dtd">

<look-and-feel>
    <compatibility>
        <version>6.1.0+</version>
    </compatibility>
    <theme id="hotel" name="Hotel Theme" >
        <settings>
        </settings>
    </theme>
</look-and-feel>

Each setting is defined using a single <setting> elements with two main attributes, key (the name by which the setting is handled) and value (in the case of configurable setting, this will be the default value).

e.g.

...
<settings>
   <setting key="show-breadcrumb" value="true" />
</settings>
...

There are three optional attributes (added in 6.1):

• configurable (whether or not the setting is static or editable from the UI)
• type (the data type for the field: checkbox, select, text, or textarea, default is text if not provided)
• options (in the case of type="select", options should contain a comma delimited list of values available to the selection)

Therefore a slightly more advanced setting might be:

...
<settings>
    <setting configurable="true" key="show-breadcrumb" type="checkbox" value="true" />
 </settings> 
...

So, how would this be used from the theme?

The usage is pretty simple and is handled by a single method on the ThemeDisplay object; getThemeSetting(String key). The ThemeDisplay object you say? Do not fear, this object is already in the context of both Velocity and Freemarker. In Velocity it is available as both $themeDisplay, as well as $theme_display. In Freemaker it's available as themeDisplay as well as theme_display.

Using the setting we created above, in your theme's portal_normal.vm (in a Velocity theme) you might do the following:

#set ($show_breadcrumb = $theme_display.getThemeSetting('show-breadcrumb'))
 
#if ($show_breadcrumb == 'true')
    <nav class="site-breadcrumbs" id="breadcrumbs">
        <h1>
            <span>#language("breadcrumbs")</span>
        </h1>
        #breadcrumbs()
    </nav>
#end

Checkbox type fields have string values of either "true" or "false".

Advanced controls

So far I have not talked about the Advanced Controls I referred to in the title of the post.

So you have controls, fine! Checkboxs, text fields, textareas, and selects are great but we can't exactly call this a great collection of "rich" controls. These are the lowest common controls that you'd probably expect. We're talking about theme developement here, so we want some POP and PIZZAZ (yes PIZZAZ!!!).

To solve this limitation without trying to provide for every scenario imaginable we added the ability for a setting definition to contain a block of javascript code which would be inlined immediately with the input field. This javascript would allow the designer to take the basic field types and turn them into a more advanced control.

For the following example I'm going to bind a color picker tool to a regular text field.

First the base xml for the definition:

...
<setting 
    configurable="true"
    key="portal-main-color"
    type="text"
    value="#EEF0F2">
<![CDATA[
]]>
</setting>
...

Now, I'm going to use the Alloy UI color-picker component and some other simple code for making the field read-only so users can't input faulty data:

...
<setting 
    configurable="true"
    key="portal-main-color"
    type="text"
    value="#EEF0F2">
<![CDATA[ 

</setting> ... 

If you read through the javascript you will see that we get an element using the A.one() alloy call. This is akin to document.getElementById() but it works by using css selectors. In this case we're getting the setting field by using the key of the field prefixed by the # symbol, which in CSS means that it's the ID of an element. The key is also prefixed by the token [@NAMESPACE@]. This token is used to avoid namespace collisions with other applications that may be floating around the page and is replaced at runtime with the actual namespace of the theme configuration app (in a portal we always need to be conscious that we may be co-existing with other apps). Use the token whenever creating public variables or dom objects.

Once we have the field, we can manipulate it however we like.

The Advanced Control Result

We've added the control, so what does it look like?

Here is the settings panel with the new field and the control:

With the control active:

Moving the cursor around the color-picker while left button pressing on the mouse will move the color-picker cursor and update the value in the setting text field until you release the button.

The Possibilities

Given the multitude of advanced controls we can create using javascript and the simple usage of the Settings API, the possibilities are quite limitless.

I hope that this takes your theme development to a whole new level of creativity and richness.

I'll be at WCS doing a couple of talks and a workshop which I'll be talking about shortly. So if you have questions regarding any of the things I've writen about recently, or about any other topic actually, and you're attending WCS, please bring those along with you.

See you at WCS!

Update: I wanted to add that the Theme Settings feature was originally implemented and donated to Liferay as part of a community contribution by José Ignacio Huertas (LPS-12468). I'd like to thank José for his contribution. This is a very good example of how a small contribution by the community can become a very cool feature. I would like to encourage others to participate by donating their feature implementations, suggestions, bug reports, documentation skills, or translation skills. This is the key way that Liferay has become the rich platform that it is.

Ok, so in the last post I talked about JSP Include Buffer.

That post talked about how you'd override JSPs from Liferay's core in a maintainable way. Now I'd like to introduce you to a Liferay Theme feature, new in 6.1, that will grant you much more power when it comes to manipulating portal views from your theme using that plus this additional feature.

From your theme you can now include templates (following the same path maning as they are found in the core) in your themes which override those of the core, provided they have a template extension matching that of your themes. They will override the default view of the portatl but only where and when your theme is applied.

Now think about this! When you apply a theme onto any page of your portal, you can alter the view of any portlet on just those pages!

Let me illustrate with an example. I'll use the exact same example that was intriduced in the previous post just so it easier to follow along.

Assuming for the moment that our theme is a Freemarker theme, we add the following template to our theme:

<SDK_ROOT>/themes/my-theme/docroot/_diffs/templates/html/taglib/ui/page_iterator/start.ftl


In this template we place the following code (using the buffer pattern):

<#assign liferay_util = PortalJspTagLibs["/WEB-INF/tld/liferay-util.tld"] />

<@liferay_util["buffer"] var="html">
    <@liferay_util["include"] 
        page="/html/taglib/ui/page_iterator/start.jsp" 
        strict=true 
        useCustomPage=false 
    /> 
</@> 
 
<div style="border: 4px solid red; padding: 4px;">
    ${html}
</div>

So, you should note two things.

First, unlike in the previous post I don't have to use the .portal encoded name for the jsp because it's still where it started, the portal didn't relocate it since my override is in the theme (it only does that when using hook plugins).

Second, the attribute strict=true. As I mentioned before, but will again, this is to prevent the portal from doing a lookup for overrides when making the call to the underlying JSP (this is to avoid infinite recursion since we're in an override right now).

Ok, I can noew enhance or alter this view no problem without having to reproduce the whole of the original logic and I'm doing it from my theme no less!

What more could you ask for?

Well it turns out there IS more that could be asked and since it was asked for, we made it reality (that's what we do at Liferay, we make wishes come true).

The question was "Could you override a JSP, but only for a particular portlet?"

Since overriding a blog JSP only in blogs doesn't really make sense, nor does overriding a blog JSP only for message boards, the main case here is with taglib JSPs. Liferay has a vast number of tags and their view logic are largely implemented with JSPs.

So, the answer to that is, "Yes, now you can override a JSP in your theme for only specific portlets!"

How do you do it?

Simple! All you need to do is add the portlet Id of the target portlet, between the file name of the original JSP and the extension of the template like so:

<SDK_ROOT>/themes/my-theme/docroot/_diffs/templates/html/taglib/ui/page_iterator/start.19.ftl

Using a similar template containing (note the green border instead):

<#assign liferay_util = PortalJspTagLibs["/WEB-INF/tld/liferay-util.tld"] />

<@liferay_util["buffer"] var="html">
    <@liferay_util["include"]
        page="/html/taglib/ui/page_iterator/start.jsp"
        strict=true 
        useCustomPage=false 
    />
</@>

<div style="border: 4px solid green; padding: 4px;"> 
    ${html} 
</div>  

Now, you'll note that we have two new tempalate files in our theme:

_diffs/templates/html/taglib/ui/page_iterator/start.ftl
_diffs/templates/html/taglib/ui/page_iterator/start.19.ftl  

These two files do not conflict, and the precendence will be:

1. portlet specific template
2. non portlet specific template
3. (no file) default

If your template is trying to override the JSP for a portlet that is in a plugin, make sure to use the fully qualified portletId (which is encoded using the pattern portletid_WAR_plugincontextname).

Now if you place two portlets on the page while this theme is in effect on it, and each of those portlets use the liferay-util:page-iterator tag, and one of those portlets is the Message Boards Portlet (19) then you should see both red and green boxes around those parts of the page.

 

Oh, and remember that you CAN do the same from a Velocity theme:

_diffs/templates/html/taglib/ui/page_iterator/start.vm
_diffs/templates/html/taglib/ui/page_iterator/start.19.vm

The template (using the buffer pattern) would look more like this:

#set ($bufferTagClass = $portal.class.forName("com.liferay.taglib.util.BufferTag"))
#set ($includeTagClass = $portal.class.forName("com.liferay.taglib.util.IncludeTag"))
 
#set ($bufferTag = $bufferTagClass.newInstance())
#set ($V = $bufferTag.setPageContext($pageContext))
#set ($V = $bufferTag.setParent(null))
#set ($V = $bufferTag.setVar('html'))
 
#if ($bufferTag.doStartTag() == 2)
    #set ($V = $bufferTag.setBodyContent($pageContext.pushBody()))
    #set ($V = $bufferTag.doInitBody())
    #set ($includeTag = $includeTagClass.newInstance())
    #set ($V = $includeTag.setPageContext($pageContext))

    #set ($V = $includeTag.setPage('/html/taglib/ui/page_iterator/start.jsp'))

    #set ($V = $includeTag.setStrict(true))
    #set ($V = $includeTag.setUseCustomPage(false))
    #set ($V = $includeTag.runTag())
    #set ($V = $bufferTag.doAfterBody())
    #set ($V = $pageContext.popBody())
    #set ($V = $bufferTag.doEndTag())
#end
 
<div style="border: 4px solid red; padding: 4px;">
    ${pageContext.findAttribute('html')}
</div>

Now, I hope you find more uses for these features that colourful boxes. Good luck!

There are plenty of times when you might want to alter the default views of the portal. I'm not going to go into the why since that is hugely subjective. What I do want to show is the how you can do this in the most maintainable way possible.

The largest concern with core JSP modification in projects is of course maintainability. JSPs have no "extensability" feature of their own and so when taking modified core JSPs into your project you run the risk of causing yourself a tone of heartache during future upgrades.

JSPs don't have any contract that allows for cleanly identifying when something has changed or gone wrong between versions. At least with pure source code you can take a leap and just try compiling against the latest version and although you likely run into many errors, they are quite literally spelled out for you. With JSPs you don't have this luxery and it's quite possible to go weeks or months with JSPs that seem to work after an upgrade but that suddenly start to exhibit bad behavior as your system starts to hit those edge cases or outright fail for the same reason. This is typically because of some unforseen change in the core logic.

Developers often try to mitigate this by doing things like using some complex or just "obvious" comments explaining changed code, hoping they are still around to review the changes on future upgrades...

What's likely to happen is that there ends up being so many JSPs changed and/or that the same developer is not around for the next upgrade, a complete and thorough review of those changes simply doesn't get done, risks are run and the ensuing issues become costly.

So goes the story of "JSP Hell"!

Meanwhile JSPs are still the best performing RAD view techology in java, so they are still used quite heavily.

What to do?

Liferay has long experienced this scenario and though we knew that changing from JSP was either unlikely or unreasonable considering the alternatives, we still had to come up with a good solution to the problem.

The solution is quite simple, the JSP Include Buffer.

The basic principle is to simply buffer, then extend the result that is output from the original JSP. Thus we can change only the parts we care about, and latter if there is a change in the original, it will either cause our extension to fail, or it will be seamlessly integrated, exactly the way a source code change would (even though it won't be a build time error, it will still be far more evident than the previous alternative).

There is one limitation, the JSP that you want to perform this operation on must NOT be a jsp fragment (a fragement is a JSP that you include using the low level <%@ include file="****.jsp" %> directive.

Rather it should be one using an include tag, such as <jsp:include /> or in the case of Liferay <liferay-util:include />, i.e. one that is invoked through a request dispatcher.

The examples I'm going to show will be using the <liferay-uitl:include /> tag.

From a JSP Hook

Liferay offers a plugin type called a "Hook" that allows you to define JSPs that should override (not overwrite) JSPs in the core, and on deploy these jsps replace those in the core. BUT the core JSPs are not lost (remember override not overwrite). The core JSPs are simply re-located, thus they are still accessible.

The core JSPs are relocated to a new name which injects the keyword .portal between the file name and extension. Thus a core JSP having the name start.jsp after being "Hooked" would be located under the name start.portal.jsp (at the exact same path).

How does this help us with the above problem?

Simply it means that we have the original to work with and so we don't need to completely re-implement or reproduce the complete code in our "extended" implementation. We can still call the original, buffer it's output and then manipulate the result to our needs.

Here is a very simple example or wrapping the output of the original with a simple black box (you could do this via CSS but what's the fun in that, and this example could serve many more uses that simple css styling can ever achieve).

<%@ taglib uri="http://liferay.com/tld/util" prefix="liferay-util" %>

<liferay-util:buffer var="html">
    <liferay-util:include
        page="/html/taglib/ui/page_iterator/start.portal.jsp"
        useCustomPage="<%= false %>"
    />
</liferay-util:buffer>

<div style="border: 4px solid red; padding: 4px;">
    <%= html %>
</div>

From a FreeMarker Template

Can the same be achieved from Freemarker you ask? Certainly! And here is the same example as above.

 <#assign liferay_util = PortalJspTagLibs["/WEB-INF/tld/liferay-util.tld"] />

<@liferay_util["buffer"] var="html">
    <@liferay_util["include"]
        page="/html/taglib/ui/page_iterator/start.jsp"
        strict=true
        useCustomPage=false
    />
</@>

<div style="border: 4px solid red; padding: 4px;">
    ${html}
</div>

From a Velocity Template

Hold up! You're kidding right? Velocity can't do jsp tags...

Well it can! It's just not pretty. Why would you do this from a Velocity anyway? Well, you never know what people want to do in their themes and the next blog post I write about how to override JSPs from theme templates will make this here feature all the more interesting for theme developers, AND by supporting Velocity, won't force all those developers to convert their existing themes to Freemarker just so they can override the odd JSP.

So, here goes (remember I don't promise that this is beautiful, only that it works and works well).

#set ($bufferTagClass = $portal.class.forName("com.liferay.taglib.util.BufferTag"))
#set ($includeTagClass = $portal.class.forName("com.liferay.taglib.util.IncludeTag"))

#set ($bufferTag = $bufferTagClass.newInstance())
#set ($V = $bufferTag.setPageContext($pageContext))
#set ($V = $bufferTag.setParent(null))
#set ($V = $bufferTag.setVar('html'))

#if ($bufferTag.doStartTag() == 2)
    #set ($V = $bufferTag.setBodyContent($pageContext.pushBody()))
    #set ($V = $bufferTag.doInitBody())

    #set ($includeTag = $includeTagClass.newInstance())
    #set ($V = $includeTag.setPageContext($pageContext))

    #set ($V = $includeTag.setPage('/html/taglib/ui/page_iterator/start.jsp'))

    #set ($V = $includeTag.setStrict(true))
    #set ($V = $includeTag.setUseCustomPage(false))
    #set ($V = $includeTag.runTag())
    #set ($V = $bufferTag.doAfterBody())
    #set ($V = $pageContext.popBody())
    #set ($V = $bufferTag.doEndTag())
#end

<div style="border: 4px solid red; padding: 4px;">
    ${pageContext.findAttribute('html')}
</div>

And there you have it!

Now you'll notice that I bolded a coupled of lines above in the template examples. These lines, which set the field strict on the include tag to true, are VERY important. They tell the underlying tag NOT check if there are overrides for the specified JSP include (otherwise you may end up with infinite recursion and likely stack overflow errors ;) ).

 

I hope this can help some of you to biuld more maintainable solutions on Liferay with less fear of the upgrade process.

Recently I was asked how to do this! Well, it's rather simple (providing you understand the limitations of accessing portlets without permission, and portlets that are not allowed to be loaded dynamically; a.k.a. add-default-resource, and so on).

Here goes!

First I created a simple web content structure/type with the following definition:

<root>
    <dynamic-element name='portlet-id' type='text' index-type='' repeatable='false'></dynamic-element>  
    <dynamic-element name='parameters' type='text' index-type='' repeatable='true'>         
        <dynamic-element name='value' type='text' index-type='' repeatable='false'></dynamic-element>
    </dynamic-element>
</root>

Then I created the following web content template:

 

<script type="text/javascript" charset="utf-8">
    AUI().ready('aui-dialog','aui-dialog-iframe','liferay-portlet-url', function(A) {
        var url = Liferay.PortletURL.createRenderURL();
        url.setPortletId("${portlet-id.data}");
        url.setWindowState('pop_up'); 

        #foreach ($parameter IN $parameters.getSiblings())
            url.setParameter("${parameter.data}", "${parameter.value.data}");
        #end  

        window.myDialog = new A.Dialog(
            {
                title: 'My Dialog',
                width: 640,
                centered: true
            }
        ).plug(
            A.Plugin.DialogIframe,
            {
                uri: url.toString(),
                iframeCssClass: 'dialog-iframe'
            }
        ).render();
    });
 </script>

 

As you can see there is a place for setting the portletId to craete an URL for, as well as a repeated section for assigning parameters to the url.

Creating an article with the Portlet Id value of 3 results in a dialog opening with the search portlet.

 

You can expand this simple example into whatever you like. The Alloy Dialog plugin is very rich and the Liferay.PortletURL library provides a complete API for creating all of the PortletURL types defined by the portlet spec.

 

Enjoy!

All secure RSS feeds now transparently support BASIC  Authentication.

The behavior is such that when you're logged in, the feeds will simply work as expected if you open them directly in the browser. If you log out, you'll suddenly be promted for BASIC  Authentication. If you use the url with an external RSS client and that client supports BASIC Authentication then simply give your credentials and you should be good to go.

Pleae note that BASIC Authentication transfers your passwords over the internet/network in plain text, so make sure that you have SSL enabled if you care about such things.

An alternative is also to enabled DIGEST Authentication (just add an init parameter for "digest_auth" in the filter declaration and restart).

Note of you're using an SSO of some kind, and the client making the request speaks in your SSO's toung, then of course you don't have to worry about any of this.

 

Enjoy!

(Update: The issue was resolved as of LPS-12308 r73243.)

Last week I wrote about a hook we wrote for Expandos using MongoDB.

I just wanted to let you know that it just finished review and is ready for consumption.

It's been renamed to mongodb-hook in case we ever want to persist more services to it.

Have a look and enjoy!

The JCP Election is just around the corner and Liferay is on the ballot for the first time ever. Being that it is the first time, you may want to know what motivates Liferay's desire for a seat on the JCP?

Frankly it's not a political one. It's purely pragmatic! Liferay would like to see things get done, to see the JCP process in the most effective state it can be. Liferay is not new to the java world and Liferay knows open source. It knows it well as a provider as well as a consumer being itself one of the largest consumers of open source java projects in the industry. On the other hand Liferay is aware of the need to drive revenue whether as an individual or as an enterprise. So, we like to not waste time and get things done. There is no political engine at work. There is only reality which demands that solutions arrive in a timely fashion; and yet Liferay is keenly aware that standardization is nessecary and can take time. Adressing the needs of a wide audience can be difficult and filled with roadblocks beyond just the technical ones. To that end Liferay wants to bring it's pragmatic know how to bare and drive innovation at it's heart. There is no better venue than the JCP.

So then, the key techincal concerns for Liferay are primarly to preserve an open, unfragmented, ubiquitous Java platform, to see improved development agility, to strive for increased modularity and to reach those goals sooner than later. The future looks bright if the JCP's focus can stay on track and Liferay would like to help make that happen.