User administration

The User Administration tool has been designed to offer a very complete set of options while keeping it very usable.

This article describes how the new UI can be used and also how it can be customized to a much higher degree than what it used to be possible.

Using the User Administration #

These are the most significant elements of the user administration UI:

Toolbar for top level navigation #

There is a new toolbar located at the top of the users section just below the title “Users”.

This toolbar provides a quick access to the most used functions when working with users:

  • View users → show a list of all the users
  • Add user → show the add user form
  • Custom attributes → management of custom attributes. Only available to users with the Administrator role.
  • Export users → a very simple export functionality to download a CSV file which contains the userId and email address of all the users. Only available to users with the Administrator role.

Searching for users #

The user adminsitration has a very powerful search system powered by Lucene.

By default, the administrator is shown a simple search box to enter some text. That text will be used to search in all of the user's fields (first name, last name, screenname, etc.) and custom attributes.

There is also an advanced search available that allows entering different texts for each of the main user fields. Once an administrator switches to 'advanced search' the user will remember her choice and show the advanced search until she switches back to the simple search.

Editing the user profile #

The user profile of portal is usually complex, with lots of fields and information. It is a challenge to fit all this information into a usable and fast form. To achieve this Liferay's user administration provides a right menu showing all the sections of the form allowing navigating through them in a super fast way that does not require page reload.

Furthermore the menu shows at all times which sections have been modified and are pending a save. This allows making changes to different sections and save everything at once. The "save" and “cancel” have been placed right below the menu so that they are always in the same place independently of how large the form section is so it's easier for users to find it. Also this placement makes it clear that clicking save will save all the changes to any of the sections of the form.

The sections are divided into three categories: Main user info, Identification and Miscellaneous. The following picture shows the three categories and the elements in each of them:

When some data introduced in the form by the user is wrong, it will be shown to the user with a global message at the top of the form and a specific message besides the wrong field. The user is redirected to the section containing the wrong field and the right menu will show the word “Error” besides the name of the section. None of the fields previously filled is lost. When changing the language of a user the dropdown will always show the available locales in the language of the administrator.

Assignment of roles, organizations and communities #

While editing the user profile it's possible to assign roles, organizations and communities to the user without leaving the form. Any change in the assignment of one of those entities will be saved, along with the rest of the form, when the 'Save' button is clicked.

When an administrator edits the profile of a user (assuming he has permission to 'Update' the profile of that user), he will be able to access the sections of the form that shows the Organizations, Communities and Roles of the user. Also he'll be able to assign any organization, communities and roles for which he has the “Assign Members” permission.

There is an important security aspect that has been considered while implementing this functionality. While an administrator may be able to edit a user (for example because he's an administrator of the organization the user belongs to), he should not be able to remove (or even see) certain roles of the edited user that he has no control of. The same applies to organizations and communities.

For that reason the administrator will only see in the list of roles, organisations and communities those that he's allowed to assign (and remove). All others will be invisible to him.

Customizing the User Administration #

The form used for editing or adding users can be completely customized. This customization ranges from the configuring which sections of the form navigation menu are shown to adding custom ones.

Configuring the sections of the user form #

The form sections can be configured through properties at the portal-ext.properties file. The following 3 properties determine which sections are available when creating a new user account:

users.form.add.main=details
users.form.add.identification=
users.form.add.miscellaneous=

Note that those categories that have no sections configured (in the example above that's the case for identification and miscellaneous) won't appear at all in the menu. Also, note that many of the sections, such as password, user associations, roles etc require the user account to exist, so they cannot be used in the above properties. It is possible though to customize those sections or create custom ones that can be used during creation (see below for an explanation of creating new sections).

After the user account has been created the form is expanded to show several additional sections.

[
users.form.my.account.main=details,password,organizations,communities,roles users.form.my.account.identification=websites,instant-messenger,social-network,open-id users.form.my.account.miscellaneous=announcements,display-settings,comments }}}

In this properties we can add the name of the sections we want to show in each section-group separated by commas. For example, if we don't want to show the “websites” section, we would just remove the word websites from users.profile.update.identification. We can also change sections from one group to another or even create new sections.

Creating new sections #

It is possible to add custom new sections to the user form using the extension environment. The following steps detail how to achieve that

  • 1) Choose a name for the section and add it to the desired section in the properties listed above. The name must follow the following rules:
    • It must be lower case
    • If it has several words they should be separated by a dash.
      • Note that the name should never have spaces or non-ascii characters.
      • For example, note that social-network is ok while social_network or social.network are wrong.
  • 2) Create a JSP file which contains the form section. The file must be located in the extension environment in ext-web/docroot/html/portlet/enterprise_admin/user and the name must be the one chosen in the previous step but with underscores instead of dashes (Tip: this change is required to conform to Liferay's own convention of using underscores in the names of the JSPs).
    • For example, the correct jsp file name for the section social-network is social_network.jsp and must be placed in the extension environment in the folder
  • 3) Add a new entry in Language-ext.properties using the name chosen in step 1 as the key and the desired label as the value. Repeat for any languages that are supported in the portal.

Dynamically hiding or showing sections #

In some advanced cases it may be useful to be able to hide or show certain sections based on custom conditions. One simple way to do this is by using jQuery. For example, let's say we want to hide the section "addresses". The following code will do the job:

	<script type="text/javascript">
		jQuery(
			function() {
				jQuery('#addressesLink').parent().hide();
			}
		);
	</script>

The benefit of using JavaScript to do this is that it allows hiding or showing sections when the user changes the value of a certain field in the browser, with no need to do a page refresh.

But sometimes, the condition to show or hide is known in the server and using JavaScript causes the section to be visible for a small period of time while the browser finishes the page loading and then disappears. To solve this Liferay v5.3 has introduced a second mechanism that allows any section JSP to specify that its associated link in the menu or that of any other section should not be included at all. For example:

<%
if (myCustomCondition) {
	request.setAttribute(WebKeys.FORM_NAVIGATOR_SECTION_SHOW + "addresses", Boolean.FALSE);
}
%>

Customizing the fields of any form section #

Each section of the user form has been implemented as a separate JSP template with no business logic so that it can be safely overridden.

All these files have the same name as the section (using hyphens for underscores) and can be found in the following deployment directory:

	/html/portlet/enterprise_admin/user

To modify any of these files copy it to the equivalent directory in the extension environment:

	ext-web/docroot/html/portlet/enterprise_admin/user 

And perform any changes desired.

Customizing the columns of the list of users #

The list of users can also be customized through the extension environment. To do that copy the file: /html/portlet/enterprise_admin/user/search_columns.jspf into:

	ext-web/docroot/html/portlet/enterprise_admin/user 

And perform any changes desired. That file doesn't contain any business logic. It has a taglib invocation for each of the columns making it very easy to change the order or add additional columns. That file provides examples for how to show values of custom attributes in custom columns.

4 Attachments
73011 Views
Average (1 Vote)
The average rating is 3.0 stars out of 5.
Comments
Threaded Replies Author Date
Hi, this is pretty good. So is here any way how... Milan Jaroš April 24, 2009 3:38 AM
I want to bookmark this article Rafael Cervantes May 16, 2009 8:43 AM
I think the line... Rafael Cervantes May 18, 2009 7:00 AM
Note that while the "My Account" page uses the... Michael Hanisch July 22, 2009 7:08 AM
Made the changes for these lines : ... Paul B. August 18, 2009 8:01 AM
It is pretty good. Thank you, Jorge. Jonas Yuan August 18, 2009 10:26 AM
This is very useful, thanks! However I'm very... Jen Fong May 19, 2010 8:26 PM
its very useful to us Sivachandran Nagendran April 4, 2012 12:35 AM
Hi :-) I customized the user list as described... Stefan Kruppa May 22, 2012 3:11 AM
how about adding new field .. and create new... Arif Rahman October 8, 2012 1:18 AM
Hi Stefan, I am experiencing the same problem.... Alain B February 21, 2013 6:40 PM

Hi,
this is pretty good. So is here any way how to "Configure the sections" for different instances? Thx.
Posted on 4/24/09 3:38 AM.
I want to bookmark this article
Posted on 5/16/09 8:43 AM.
I think the line
users.form.update.main=user-details,password,organizations,communties,roles
s­hould be
users.form.update.main=details,password,organizations,communties,roles
Posted on 5/18/09 7:00 AM.
Note that while the "My Account" page uses the same JSPs as the User administration, the properties for modifying the sections displayed are different (since 5.2.3 - see http://issues.liferay.com/browse/LPS-2470 ).

To modify the sections shown on the "My Account" page, use the following properties:

users.form.my.account.main=${users.form.update.main}
users.form.my.acc­ount.identification=${users.form.update.identification}
users.form.my.account.mis­cellaneous=${users.form.update.miscellaneous}

As you can see it's even possible to reference the config for the user administration pages from the other set of properties!
Posted on 7/22/09 7:08 AM.
Made the changes for these lines :

users.form.my.account.main=details,password,organizations,communities,roles
user­s.form.my.account.identification=websites,instant-messenger,social-network,open-­id
users.form.my.account.miscellaneous=announcements,display-settings,comments
Posted on 8/18/09 8:01 AM in reply to Michael Hanisch.
It is pretty good. Thank you, Jorge.
Posted on 8/18/09 10:26 AM.
This is very useful, thanks!

However I'm very new to liferay and I was wondering if anyone out there could help me as to what classes the jsp files in ext-web/docroot/html/portlet/enterprise_admin/user might have access to, and how to add to those. Could I simply define my own classes under ext-impl and let the jsp access them by importing the classes [i.e., com.ext.mypackage.myclass?]?

Also, I see that this wiki was created quite some time ago, so does this still pertain to liferay 5.2.3?
Posted on 5/19/10 8:26 PM.
its very useful to us
Posted on 4/4/12 12:35 AM.
Hi :-)

I customized the user list as described above by adding a custom field, looking like this:

<liferay-ui:search-container-column-text
href="<%= rowURL %>"
name="my custom field"
orderable="<%= true %>"
value="<%= StringUtil.valueOf(user2.getExpandoBridge().getAttribute(\"myCustomField\")) %>"
/>

The field is being displayed, but sorting by this field doesn't work (i.e. there is a clickable link and a triangle indicating the sort order but when clicking the link the page refreshes with the sort order remaining the same as before).
Is there something I missed?

I use Liferay 6.1 running on Ubuntu 10.10.

Thanks for your help!
Posted on 5/22/12 3:11 AM in reply to Sivachandran Nagendran.
how about adding new field .. and create new form on user jsp section, and new field of database .am i gonna get database field generated by it self ?
Posted on 10/8/12 1:18 AM in reply to Stefan Kruppa.
Hi Stefan,

I am experiencing the same problem. Please let me know if you find a solution.
I will do the same

I use Liferay 6.1 running on Glassfish 3.2 Ubuntu 12.04.

Thanks
Posted on 2/21/13 6:40 PM in reply to Stefan Kruppa.