This article needs updating. For more information, see Wiki - Need Updating.

Introduction #

This article describes the API that is available to JavaScript code inside any portlet run within Liferay. The API is divided in two parts:

• jQuery API and included jQuery Plugins
• Liferay's own API (which is built on top of the above)

As of Liferay 6, Liferay is built on Alloy UI, which uses YUI instead of JQuery. For more information, see Alloy UI.

jQuery Plugins #

By default, we include numerous plugins for users as a convenience. Here they are:

• jQuery Cookie Plugin [http://www.stilbuero.de/2006/09/17/cookie-plugin-for-jquery/|(allows easy setting and getting of cookies)
• Dimensions http://jquery.com/plugins/project/dimensions] (allows easy and accurate getting of an elements dimensions)
• Hover Intent [http://cherne.net/brian/resources/jquery.hoverIntent.html|(allows a user to easily set delays on mousing over and out of an element)
• Interface http://interface.eyecon.ro] (effects library, with such effects as draggables, fades, animation, etc.)
• jQBrowser2 [http://www.alterform.com/resources/jqbrowser-2|(extends jQuery's default browser detection, as well as adds in browser selectors)
• jEditable http://www.appelsiini.net/projects/jeditable] (allows users to set an element to be editable from within the page)
• jQuery JSON Plugin (handles converting javascript objects to a json string and vice versa)
• jQuery Media Plugin [http://malsup.com/jquery/media/|(for converting elements into rich media content)
• jQuery Tabs Plugin http://stilbuero.de/tabs/] (creates configurable tabs that allow you to switch between tabs without a page reload)

Liferay JavaScript Modules #

There are many prebuilt modules and components that Liferay uses. Some are publicly accessible, and some are not. The documentation will describe the publicly accessible ones, and their usage.

Auto Fields #

Auto Fields is a reusable class that allows the user to add multiple fields to a page via Javascript. The use case it was designed for was that if you have a set of fields (let's say a title and description input, or an upload field), with the click of a button, it will keep adding duplicates of the field(s).

Here is an example of how you would use it:

 Liferay.autoFields({options});

And here are the possible options:

html (String)

HTML to append to the end of the container Usage:

 html: ****

container (String)

The jQuery selector of the item(s) you wish to append the HTML to

 container: '.portlet fieldset:first'

addText (String)

The text you wish to use for the "Add" link

 addText: 'Add another set of options'

removeText (String)

The text you wish to use for the "Remove" link Usage:

 removeText: 'Remove the last set of options'

clearText (String)

The text you wish to use for the "Clear" link (this link clears all of the added forms except the very first one, a sort of reset button) Usage:

 clearText: 'Remove all of my options'

confirmText (String)

The text you wish to use to confirm that the user wishes to clear all of the added buttons (leave empty to not confirm) Usage:

 confirmText: 'Are you sure you wish to remove all of your options?'

rowType (String)

The html tag for the row of fields (eg. fieldset, div or tr) Usage:

 rowType: 'fieldset'

onAdd (function)

A callback that executes after new fields have been added. The callback gets passed the new field that was created as the argument (this is useful if you wish to modify the field after adding it) Usage:

 onAdd: function(newField) {
        alert('This field got added.');
 }

onRemove (function)

A callback that executes after fields have been removed (does not get any parameters) Usage:

 onRemove: function() {
        alert('The last field was removed.');
 }

onClear (function)

A callback that executes after the form fields have been returned (does not get any parameters) Usage:

 onClear: function() {
        alert('All fields have been removed.')
 }

init (function)

A callback that executes after the class has fully initialized (does not get any parameters) Usage:

 init: function() {
        alert('The automagic fields are now ready to use.');
 }

Browser #

Liferay provides a way for users to correctly determine the user's current browser and current version. There are a few methods and variables available for getting the browser version.

Browser Methods:

browser

Usage:

 Liferay.Browser.browser();

The possible returned values are:

• Internet Explorer
• Firefox
• Netscape
• Camino
• Flock
• AOL Explorer
• Konqueror
• iCab
• Opera
• Safari

version

Usage:

 Liferay.Browser.version();

Returns a number, which is the rounded value of the currently running browser.

If you're in Firefox 1.5 or IE 5.5 and you want an exact version number, you can get that by passing in true as the parameter, like so: Liferay.Browser.version(true);

Browser Constants

These constants are boolean values, and determine the current browser. They are named in a self-explanitory fashion:

• Liferay.Browser.is_ie: The browser is Internet Explorer
• Liferay.Browser.is_ie_4: The browser is Internet Explorer 4
• Liferay.Browser.is_ie_5: The browser is Internet Explorer 5
• Liferay.Browser.is_ie_5_5: The browser is Internet Explorer 5.5
• Liferay.Browser.is_ie_5_up: The browser is Internet Explorer 5 and up
• Liferay.Browser.is_ie_6: The browser is Internet Explorer 6
• Liferay.Browser.is_ie_7: The browser is Internet Explorer 7
• Liferay.Browser.is_mozilla: The browser is a Mozilla based browser
• Liferay.Browser.is_mozilla_1_3_up: The browser is a Mozilla based browser and version 1.3 and up
• Liferay.Browser.is_ns_4: The browser is a Netscape browser and version 4
• Liferay.Browser.is_rtf: The browser can run Rich Text Editing controls (IE or Mozilla based browsers)
• Liferay.Browser.is_safari: The browser is Safari (or any WebKit based browser)
• Liferay.Browser.is_opera: The browser is Opera

Language #

Liferay provides a way to get the value of different language keys. This allows you to keep Liferay's internationalization in Javascript. These results are also cached by the user, so multiple requests to the same key will not degrade performance.

Here is an example of how you would use it:

 Liferay.Language.get('hello-world');

This will return you a string in your Javascript that reads: "Hello World"

Some strings require that you pass in parameters. For instance, let's assume that your key is this one: all-email-from-x-is-being-forwarded-to-x

This allows you to pass in what x is.

To use this sort of key with Language, you must pass in the values for x as an array, as the second parameter.

So in this case, you would write:

 Liferay.Language.get('all-email-from-x-is-being-forwarded-to-x', ['Mike', 'Brian']);

Which will read: "All email from Mike is being forwarded to Brian".

Notice #

Liferay has a module called Notice that is instantiable, and allows you to place a notice or warning that sits at the very top of the page, and doesn't intrude upon a users work. If you plan on using this module, please be warned that it is possible that you could either cover up an existing notice/warning message. Use sparingly.

Here is how you would call the method:

 new Liferay.Notice({options});

And the options that are available are:

closeText (String)

the text to use for the "close" button. Set to false to not have a close button

content (String)

the HTML or text to insert into.

toggleText (Object)

the text to use for the "hide" and "show" button. Set to false to not have a hide button

noticeClass (String)

class to add to the notice toolbar.

onClose (fn)

a callback to execute when the toolbar is closed

type (String)

either 'notice' or 'warning', depending on the type of the toolbar. Defaults to notice.