« Back

User-specific versus shared portlet preferences - part 1

General Blogs May 15, 2014 By Peter Mesotten

This article is the first in a series of 2 posts on how personalization can be achieved in a portal project. Moreover, the concept of sharing personalized settings between users is explained and how this behavior can be changed in Liferay.

See also User-specific versus shared portlet preferences - part 2.


One of the most important features of a portal is personalization, or the ability for users to change the behavior, content or visualization of portlets. In most projects we've done, customers are very skeptical about personalization. For those customers, enabling personalization equals enabling users to mess things up and call for support afterwards. We believe however that personalization, if implemented the right way, creates a dynamic experience that will increase the usage and ultimately extend the lifetime of the portal.

Preferences scopes

The Portlet 2.0 specification (JSR-286) enables personalization through the definition of portlet preferences. According to the spec, preferences are simple key-value pairs that are stored for each portlet and for each user. This means that two users who look at the same portlet will see two different versions of that portlet, according to the preferences they have set on that portlet.

Since Liferay implements JSR-286 you would expect Liferay to store preferences on a per-user basis too. This is however not the case. By default, Liferay stores a portlet's preferences on a per-portlet basis. This means that all users will see the same preferences for a certain portlet instance. Luckily, the scope in which preferences are stored can be changed. For this, we need to update the portlet's liferay-portlet.xml. There are 3 properties that are related to the storage of portlet preferences:

  • preferences-company-wide
  • preferences-unique-per-layout
  • preferences-owned-by-group

The first configuration parameter is the easiest one to understand. If preferences-company-wide is set to true, the preferences for the portlet are stored portal-wide. Every instance of the portlet on every page within every site will have the same preferences. Changing the preferences in one place will change the portlet in all other places. If this parameter is true, the other configuration parameters are ignored.

The other 2 parameters, preferences-unique-per-layout and preferences-owned-by-group, can both be true or false as well. In this case, the combination of these settings will define the scope in which the preferences for a portlet are stored. 

If we do the math, we end up with 5 options for storing portlet preferences. The implications of those options can best be explained by giving an example.

Example: QuickLinks portlet

Consider a custom portlet that can be configured to show one or more links to internal or external pages, resources or applications. The set of links that should be visible is configured using portlet preferences. In this case, the preferences scope configuration will decide which quick links will be visible for which users. 

  • Portal-wide quick links (preferences-company-wide=true)
    In this case, all portal users will see the same set of quick links throughout the portal. So even if there are multiple QuickLinks portlets on different pages, they will all show the same links. Usually, you won't allow every user to update company-wide preferences, because users will start to override each other's preferences. It is more common to assign this task to a global administrator.
  • Site-wide quick links (preferences-company-wide=false, preferences-unique-per-layout=false, preferences-owned-by-group=true)
    This case behaves very much like the previous one. Except for the fact that the links will be the same in portlets on pages within one site. Each site can thus show its own quick links. Again, it is not recommended to let every site member update these site-wide preferences. The ideal person to manage these kinds of preferences is the site administrator.
  • Per-portlet quick links, shared across users (preferences-company-wide=false, preferences-unique-per-layout=true, preferences-owned-by-group=true)
    In this case, every portlet instance has its own preferences. So we can have different QuickLinks portlets in different pages and even in different sites and each of them will show different links. For a given portlet instance however, all users will see the same links. Again it's mostly the site administrator who will manage these links or maybe a small group of users that will manage different parts of a site. Remember that this is the default setting, so it will be used if no configuration is set in liferay-portlet.xml.
  • Per-user, per-portlet quick links (preferences-company-wide=false, preferences-unique-per-layout=true, preferences-owned-by-group=false)
    In this case, every user will be able to store a dedicated portlet configuration for each portlet instance separately. So each user can decide for himself which links are visible in the portlet. If there are multiple QuickLinks portlets, the configured links can be different in each portlet. The user must of course be given the appropriate permissions to allow him to update the preferences (enable the PREFERENCES action on the portlet resource).
  • Per-user quick links, shared across portlets (preferences-company-wide=false, preferences-unique-per-layout=false, preferences-owned-by-group=false)
    In case there are multiple QuickLinks portlet instances on different pages or even different sites, this setting will share a user's preferences between all those instances. So if a user changes the quick links in one portlet, they will be updated in all other QuickLinks portlets as well. Still, the preferences are not shared across different users.


It is clear that Liferay's addition to the Portlet 2.0 specification with regard to portlet preferences enables a great amount of flexibility. Defining the scope in which preferences should be stored is an important decision that needs to be taken during functional analysis, not during development.

One limitation of this is that it seems impossible to store preferences in multiple scopes at the same time. Indeed, the liferay-portlet.xml configuration is applied to all preferences. Sometimes however, it could be useful to store default preferences on a global level (e.g. portal-wide or site-wide), while allowing end-users to override this global configuration with custom preferences. In case of the QuickLinks portlet, an administrator could provide a default set of quick links that are used if a user has not set his own quick links. The next part of this series will explain in detail how this can be achieved in a clean, reusable way.

Threaded Replies Author Date
How did you know that I just needed to... Olaf Kock May 15, 2014 7:20 AM
Very good coverage of portlet preferences. ... Ahmed Hasan May 15, 2014 8:53 AM
Good Post. All the luck :) Akash Jaisawal May 16, 2014 3:53 AM
Very well explained !! Thanks, Venkat Venkat Koppavolu May 25, 2014 10:40 AM
Great explanation. When (or where) do you post... Christophe Cariou July 11, 2014 2:41 AM
Coming soon... :-) Peter Mesotten July 24, 2014 1:14 AM
Part 2 of this series was just posted:... Peter Mesotten August 11, 2014 12:34 AM
Hello Peter, First of all, great post. I... Marko Perić January 21, 2015 12:50 AM

How did you know that I just needed to summarize this?
Less effort for me \o/ - I'll keep this reference in my toolbox.
Posted on 5/15/14 7:20 AM.
Very good coverage of portlet preferences.

Ahamed Hasan
Author, Liferay Cookbook
Posted on 5/15/14 8:53 AM.
Good Post.
All the luck emoticon
Posted on 5/16/14 3:53 AM.
Very well explained !!

Posted on 5/25/14 10:40 AM.
Great explanation. When (or where) do you post the second part ?
Posted on 7/11/14 2:41 AM.
Posted on 7/24/14 1:14 AM in reply to Christophe Cariou.
Part 2 of this series was just posted: https://www.liferay.com/web/pmesotten/blog/-/blogs/user-specific-versus-shared-p­ortlet-preferences-part-2.

This part will explain a way for storing preferences for a Liferay portlet in multiple scopes at the same time.
Posted on 8/11/14 12:34 AM.
Hello Peter,

First of all, great post. I would really appreciate if you could see my problem I posted on forum and I think this blog post could solve my problem.
Link: https://www.liferay.com/community/forums/-/message_boards/message/47911045

I have used 4th option from your list, "per-user, per-portlet" but it didn't help, two users still see the same data.

Please take a look on a link.

Thank you very much.
Posted on 1/21/15 12:50 AM.