There are a number of built in features in the JS engine. Many of these features are accessible by assigning certain attributes on HTML elements. The following is a list of available features and how to implement them:

UI

Element toggling

Toggles the visibility of an element on the page when an anchor tag is clicked. Set the anchor tag's href to the ID of the element to toggle and add `rel="toggle"`.

Example:

$content = elgg_view('output/url', array(
	'href' => '#toggle-me',
	'rel' => 'toggle',
	'text' => 'Click to toggle'
));
 
$content .= elgg_view_module('info', 'Test toggle', 'Example content', array('id' => 'toggle-me'));
 
echo elgg_view_page('Test', $content);

Popups

Pops up a hidden element on the page on top of other content when an anchor tag is clicked. Set the anchor tag's href to the ID of the element to pop up and add `rel="popup"`.

Note: If you want to pop up images, another page, or external links, use the lightbox instead.

Example:

$content = elgg_view('output/url', array(
	'href' => '#popup',
	'rel' => 'popup',
	'text' => 'Click to pop up'
));
 
$content .= elgg_view_module('popup', 'Test popup', 'Example content', array(
	'id' => 'popup',
	'class' => 'hidden'
));
 
echo elgg_view_page('Test', $content);

Lightbox

Opens a lightbox with when an anchor tag is clicked. Set the lightbox's target to the anchor tag's href and add the class `elgg-lightbox`.

Example:

elgg_load_js('lightbox');
elgg_load_css('lightbox');
 
$content = elgg_view('output/url', array(
	'href' => '/activity',
	'class' => 'elgg-lightbox',
	'text' => 'Activity in a lightbox'
));
 
echo elgg_view_page('Test', $content);

The default lightbox is Fancybox. (This will change in 1.9 because Fancybox is moving to a proprietary license.)

Note: You cannot open external links in a lightbox using this method.

Autofocus

Focuses input on the specified element upon page load. Add the class `.elgg-autofocus` to the element to focus. Note: This is the default behavior for the `output/confirmlink` view.

Example:

$content = elgg_view('input/text', array(
	'name' => 'autofocus_test',
	'class' => 'elgg-autofocus'
));
 
echo elgg_view_page('Test', $content);

Requiring confirmation

Opens a dialogue box asking the user to confirm an action. Add the class `.elgg-requires-confirmation` to the element. Note: This is default behavior for the `output/confirmlink` view. If you require confirmation on anchor tags, use that view instead.

Example:

$content = elgg_view('input/submit', array(
	'value' => 'Requires confirmation',
	'class' => 'elgg-requires-confirmation',
));
 
echo elgg_view_page('Test', $content);

Object methods

The `elgg` JS object has many helpful methods you should be familiar with when writing JS for Elgg. Many of them mimic their similarly named PHP counterparts

Always look in the code for further documentation, features, and examples on how to use these methods.

elgg.normalize_url()

Normalize a URL. See the PHP function elgg_normalize_url().

Example:

// returns http://elgg.org
elgg.normalize_url('elgg.org');

elgg.system_message() and elgg.register_error()

Pop up a system message or an error. See the PHP functions system_message() and register_error().

Example:

elgg.system_message('Success!');
elgg.register_error('Failure.');

elgg.forward()

Forwards to the specified URL. This passes the URL string through elgg.normalize_url().

elgg.parse_url()

Parses a URL into its parts. Similar to PHP's parse_url.

Example:

/* returns an object with the properties
fragment: "fragment"
host: "community.elgg.org"
path: "/path/file.php"
query: "arg=val"
*/
elgg.parse_url('http://community.elgg.org/path/file.php?arg=val#fragment');

elgg.echo()

Echoes a language string. Operates the same as the PHP elgg_echo(). Strings are defined as normal in PHP language files.

Example:

// returns:
// "You have successfully added Brett as a friend."
elgg.echo("friends:add:successful", ['Brett'])

elgg.get_page_owner_guid()

Returns the GUID of the page owner.

elgg.security.refreshToken()

Forces a refresh of all tokens on the page. This requires a valid security token. Note: This is called every 5 minutes by default.

elgg.security.addToken()

Adds a security token to an object (to be used as form data), a URL, or a query string starting with a ?

Example:

/* 
returns an object:
__elgg_token: "1468dc44c5b437f34423e2d55acfdd87"
__elgg_ts: 1328143779
other: "data"
*/
elgg.security.addToken({'other': 'data'});
 
// returns: "action/add?__elgg_ts=1328144079&__elgg_token=55fd9c2d7f5075d11e722358afd5fde2"
elgg.security.addToken("action/add");
 
// returns "?arg=val&__elgg_ts=1328144079&__elgg_token=55fd9c2d7f5075d11e722358afd5fde2"
elgg.security.addToken("?arg=val");

elgg.get_logged_in_user_entity()

Returns the logged in user as an JS ElggUser object.

elgg.get_logged_in_user_guid()

Returns the logged in user's guid.

elgg.is_logged_in() and elgg.is_admin_logged_in()

Returns true if a user is logged in, and if an admin user is logged in respectively.

elgg.provide()

Creates a name-spaced object structure with namespaces separated by dots.

Example:

/*
creates the object structure:
{
    elgg: {
        namespace1: {
            namespace2: {}
        }
    }
}
*/
elgg.provide('elgg.namespace1.namespace2');

Config

There are a number of configuration values set in the elgg object.

elgg.config.wwwroot

The root of the website.

elgg.config.language

The default site language. Use elgg.config.get_language() to get the current language.

elgg.config.viewtype

The current viewtype.

elgg.config.version

The Elgg version (YYYYMMDDXX).

elgg.config.release

The Elgg release (1.8.3).