Elgg 1.9 Documentation¶

How much does Elgg cost?¶

Elgg is free to download, install, and use. If you’d like to donate, we do appreciate our financial supporters!

Can I remove the Elgg branding/links?¶

Yes.

Can I modify the source code?¶

Yes, but in general we recommend you make your modifications as plugins so that when a new version of Elgg is released, the upgrade process is as painless as possible.

Can I charge my users membership fees?¶

Yes.

If I modify Elgg, do I have to make the changes available?¶

No, if you are using Elgg to provide a service, you do not have to make the source available. If you distribute a modified version of Elgg, than you must include the source code for the changes.

If I use Elgg to host a network, does The Elgg Foundation have any rights over my network?¶

No.

What’s the difference between the MIT and GPL versions?¶

Plugins are not included with the MIT version.

You can distribute a commercial product based on Elgg using the MIT version without making your modifications available.

With the GPL licensed version, you have to include make your modifications of the framework public if you redistribute the framework.

Why are plugins missing from the MIT version?¶

The plugins were developed under the GPL license, so they cannot be released under an MIT license. Also, some plugins include external dependencies that are not compatible with the MIT license.

May I distribute a plugin for Elgg under a commercial license?¶

We believe you can, since plugins typically depend only the core framework and the framework is available under the MIT license. That said, we really recommend you consult with a lawyer on this particular issue to be absolutely sure.

Note that plugins released via the community site repository must be licensed under a GPLv2-compatible license.

Can we build our own tool that uses Elgg and sell that tool to our clients?¶

Yes, but then your clients will be free to redistribute that tool under the terms of the GPLv2.

Upload Elgg¶

• Download the latest version of Elgg
• Upload the ZIP file with an FTP client to your server
• Unzip the files in your domain’s document root (/home/username/www).

Create a data folder¶

Elgg needs a special folder to store uploaded files including profile icons and photos. You will need to create this directory.

Once this folder has been created, you’ll need to make sure the web server Elgg is running on has permission to write to and create directories in it. This shouldn’t be a problem on Windows-based servers, but if your server runs Linux, Mac OS X or a UNIX variant, you’ll need to set the permissions on the directory.

TODO: What is the recommended setting? 755? 644?

If you are using a graphical FTP client to upload files, you can usually set permissions by right clicking on the folder and selecting ‘properties’ or ‘Get Info’.

Create a MySQL database¶

Using your database administration tool of choice (if you’re unsure about this, ask your system administrator), create a new MySQL database for Elgg. You can create a MySQL database with any of the following tools:

Make sure you add a user to the database with all privileges and record the database name, username and password. You will need this information when installing Elgg.

Visit your Elgg site¶

Once you’ve performed these steps, visit your Elgg site in your web browser. Elgg will take you through the rest of the installation process from there. The first account that you create at the end of the installation process will be an administrator account.

A note on settings.php and .htaccess¶

The Elgg installer will try and create two files for you:

• engine/settings.php, which contains the database settings for your installation
• .htaccess, which allows Elgg to generate dynamic URLs

If these files can’t be automatically generated, for example because the web server doesn’t have write permissions in the directories, Elgg will tell you how to create them. You could also temporarily change the permissions on the root directory and the engine directory. Set the permissions on those two directories so that the web server can write those two files, complete the install process, and them change the permissions back to their original settings. If, for some reason, this won’t work, you will need to:

• Copy engine/settings.example.php to engine/settings.php, open it up in a text editor and fill in your database details
• Copy /htaccess_dist to /.htaccess

Lighttpd¶

Have you installed Elgg on a server running lighttpd? We are looking for someone to share any configuration and installation steps involved in setting this up.

Nginx¶

To run Elgg on Nginx, you will need to:

• configure Nginx to talk to a PHP process in either CGI or FPM mode
• Port the rewrite rules

TODO: Add the rewrite rules from the community site.

IIS¶

When installing on IIS, the problem is that the Apache mod_rewrite rules will not be recognized, and this breaks the application. You need to convert the mod_rewrite rules to the IIS URL Rewrite module format.

You can do this using the IIS 7+ management console, and the “Import Rules” feature that will do the conversion, as describe in the tutorial “importing Apache mod_rewrite rules”.

MariaDB¶

This DBMS should be a drop-in replacement for MySQL, if you prefer it.

http://community.elgg.org/discussion/view/1455994/alternative-dbmss

Virtual host (e.g. Rackspace, Amazon EC2)¶

For installation to proceed successfully, modify the .htaccess file in the root, and uncomment:

#RewriteBase /

To be:

RewriteBase /

MAMP¶

On certain versions of MAMP, Elgg will either fail to install or have intermittent problems while running.

This is a known issue with MAMP and is related to the Zend Optimizer. Until Zend/MAMP have resolved this issue it is recommended that you turn off the Zend Optimizer in your PHP settings.

XAMPP¶

These intructions are provided in case you want to test your Elgg installation on your local computer running Windows.

• Download and install XAMPP to your computer from http://www.apachefriends.org/en/xampp.html

• Once the installation is completed, it will prompt you to start the XAMPP controller panel. Leave it for now.

• Open C:\xampp\apache\conf\httpd.conf file with notepad and uncomment these lines:

  #LoadModule rewrite_module modules/mod_rewrite.so
  #LoadModule filter_module modules/mod_filter.so
  

• Edit the php.ini file and change arg_separator.output = & to arg_separator.output = &

• Go to C:\xampp and double click on the xampp_start application

• Go to http://localhost/

• Change your server’s password in the security option

• Go to http://localhost/phpmyadmin and login with the username and the password of your server

• Create a database called “elgg” in your phpmyadmin panel

• Now download Elgg. Unzip it and extract to C:\xampp\htdocs\sites\elgg

• Create the Elgg data folder as C:\xampp\htdocs\sites\data

• Go to http://localhost/sites/elgg

• You will be taken to the Elgg installation steps. Install it and enjoy.

A note on XAMPP 1.7.4 and eAccelerator

Elgg is compatible with opcode caches and it is highly recommended that you enable a PHP opcode caching tool for a faster experience. XAMPP comes with support for eAccelerator out of the box, but unfortunately, the 1.7.4 build of XAMPP leaves out the DLL that’s required. To get eAccelerator working, follow these steps:

• Download the DLL from http://eac.qme.nl/eAccelerator_v1_0_svn427_for_v5_3_5-VC6.zip

• Copy eAccelerator_ts.dll to C:\xampp\php\ext\php_eaccelerator.dll

• Uncomment this line in C:\xampp\php\php.ini:

  ;zend_extension = "C:\xampp\php\ext\php_eaccelerator.dll"

• Restart apache

To verify that it is on:

• Go to localhost/xampp
• Click on phpinfo() from the left sidebar
• Ctrl+F for eaccelerator. If you get no results, eAccelerator is not active

EasyPHP¶

• Assuming no MySQL, PHP or Apache installations exist already.
• Best run as a development/test server

1. Stop IIS running if installed

2. Download and install the latest Easy PHP from http://www.easyphp.org (16MB download)

3. Set up the database and point the web server to your Elgg folder (all done from the EasyPHP tray icon) - Right click EasyPHP tray icon, select “Administration” - A new tab is created in your browser for managing Easy PHP - Add your Elgg folder to Apache in “Alias” section - Click “Manage MySQL with PhpMyAdmin”, create a database and account for Elgg

4. (Ignore this step for v5.3 or later) From the tray icon go Configuration/Apache and uncomment this line:

   #LoadModule rewrite_module modules/mod_rewrite.so
   

5. (Ignore this step for v5.3 or later) Change AllowOverride None to AllowOverride All in the relevant directory entry in Configuration/Apache

6. (Ignore this step for v5.3 or later) From the tray icon fo Configuration/PHP and uncomment this line:

   ;extension=php_curl.dll

7. A reboot is best Elgg should run via http://127.0.0.1

Ubuntu Linux¶

• Install the dependencies:

  sudo apt-get install apache2
  sudo apt-get install mysql-server
  sudo apt-get install php5 libapache2-mod-php5 php5-mysql
  sudo apt-get install phpmyadmin
  sudo a2enmod rewrite

• Edit /etc/apache2/sites_available/default to enable .htaccess processing (set AllowOverride to All)

• Restart Apache: sudo /etc/init.d/apache2 restart

• Follow the standard installation instructions above

Cloud9IDE¶

1. Create a c9 workspace

• Go to http://c9.io
• Login with GitHub
• On the Dashboard, click “Create new workspace” => “Create a new workspace”
• Choose a project name (e.g. “elgg”)
• Choose “PHP” for project type
• Click “Create”
• Wait... (~1 min for c9 workspace to be ready)
• Click “Start editing” for the workspace

2. Set up the workspace for Elgg

Run the following in cloud9’s terminal:

rm -rf * # Clear out the c9 hello-world stuff
git clone https://github.com/Elgg/Elgg . # the hotness
cp htaccess_dist .htaccess
cp engine/settings.example.php engine/settings.php
mysql-ctl start # start c9's local mysql server
mkdir ../elgg-data # setup data dir for Elgg

Configure engine/settings.php to be like so:

// Must set timezone explicitly!
date_default_timezone_set('America/Los_Angeles');
$CONFIG->dbuser = 'your_username'; // Your c9 username
$CONFIG->dbpass = '';
$CONFIG->dbname = 'c9';
$CONFIG->dbhost = $_SERVER['SERVER_ADDR'];
$CONFIG->dbprefix = 'elgg_';

3. Complete the install process from Elgg’s UI

• Hit “Run” at the top of the page to start Apache.
• Go to http://your-workspace.your-username.c9.io/install.php?step=database
• Change Site URL to http://your-workspace.your-username.c9.io/
• Put in the data directory path. Should be something like /var/..../app-root/data/elgg-data/.
• Click “Next”
• Create the admin account
• Click “Go to site”
• You may have to manually visit http://your-workspace.your-username.c9.io/ and login with the admin credentials you just configured.

Help! I’m having trouble installing Elgg¶

First:

• Recheck that your server meets the technical requirements for Elgg.
• Follow the environment-specific instructions if need be
• Have you verified that mod_rewrite is being loaded?
• Is the mysql apache being loaded?

Keep notes on steps that you take to fix the install. Sometimes changing some setting or file to try to fix a problem may cause some other problem later on. If you need to start over, just delete all the files, drop your database, and begin again.

I can’t save my settings on installation (I get a 404 error when saving settings)¶

Elgg relies on the mod_rewrite Apache extension in order to simulate certain URLs. For example, whenever you perform an action in Elgg, or when you visit a user’s profile, the URL is translated by the server into something Elgg understands internally. This is done using rules defined in an .htaccess file, which is Apache’s standard way of defining extra configuration for a site.

This error suggests that the mod_rewrite rules aren’t being picked up correctly. This may be for several reasons. If you’re not comfortable implementing the solutions provided below, we strongly recommend that you contact your system administrator or technical support and forward this page to them.

The .htaccess, if not generated automatically (that happens when you have problem with mod_rewrite), you can create it by renaming htaccess_dist file you find with elgg package to .htaccess. Also if you find a .htaccess file inside the installation path, but you are still getting 404 error, make sure the contents of .htaccess are same as that of htaccess_dist.

Instructions for testing mod_rewrite

``mod_rewrite`` isn’t installed.

Check your httpd.conf to make sure that this module is being loaded by Apache. You may have to restart Apache to get it to pick up any changes in configuration. You can also use PHP info to check to see if the module is being loaded.

The rules in ``.htaccess`` aren’t being obeyed.

In your virtual host configuration settings (which may be contained within httpd.conf), change the AllowOverride setting so that it reads:

AllowOverride all

This will tell Apache to pick up the mod_rewrite rules from .htaccess.

Elgg is not installed in the root of your web directory (ex: http://example.org/elgg/ instead of http://example.org/)

The install script redirects me to “action” when it should be “actions”¶

This is a problem with your mod_rewrite setup. DO NOT, REPEAT, DO NOT change any directory names!

I installed in a subdirectory and my install action isn’t working!¶

If you installed Elgg so that it is reached with an address like http://example.org/mysite/ rather than http://example.org/, there is a small chance that the rewrite rules in .htaccess will not be processed correctly. This is usually due to using an alias with Apache. You may need to give mod_rewrite a pointer to where your Elgg installation is.

• Open up .htaccess in a text editor
• Where prompted, add a line like RewriteBase /path/to/your/elgg/installation/ (Don’t forget the trailing slash)
• Save the file and refresh your browser.

Please note that the path you are using is the web path, minus the host.

For example, if you reach your elgg install at http://example.org/elgg/, you would set the base like this:

RewriteBase /elgg/

Please note that installing in a subdirectory does not require using RewriteBase. There are only some rare circumstances when it is needed due to the set up of the server.

I did everything! mod_rewrite is working fine, but still the 404 error¶

Maybe there is a problem with the file .htaccess. Sometimes the elgg install routine is unable to create one and unable to tell you that. If you are on this point and tried everything that is written above:

• check if it is really the elgg-created .htaccess (not only a dummy provided from the server provider)
• if it is not the elgg provided htaccess file, use the htaccess_dist (rename it to .htaccess)

I get an error message that the rewrite test failed after the requirements check page¶

I get the following messages after the requirements check step (step 2) of the install:

We think your server is running the Apache web server.

The rewrite test failed and the most likely cause is that AllowOverride is not set to All for Elgg’s directory. This prevents Apache from processing the .htaccess file which contains the rewrite rules.

A less likely cause is Apache is configured with an alias for your Elgg directory and you need to set the RewriteBase in your .htaccess. There are further instructions in the .htaccess file in your Elgg directory.

After this error, everinteraction with the web interface results in a error 500 (Internal Server Error)

This is likely caused by not loading the “filter module by un-commenting the

#LoadModule filter_module modules/mod_filter.so

line in the “httpd.conf” file.

the Apache “error.log” file will contain an entry similar to:

... .htaccess: Invalid command ‘AddOutputFilterByType’, perhaps misspelled or defined by a module not included in the server configuration

There is a white page after I submit my database settings¶

Check that the Apache mysql module is installed and is being loaded.

I’m getting a 404 error with a really long url¶

If you see a 404 error during the install or on the creation of the first user with a url like: http://example.com/homepages/26/d147515119/htdocs/elgg/action/register that means your site url is incorrect in your sites_entity table in your database. This was set by you on the second page of the install. Elgg tries to guess the correct value but has difficulty with shared hosting sites. Use phpMyAdmin to edit this value to the correct base url.

I am having trouble setting my data path¶

This is highly server specific so it is difficult to give specific advice. If you have created a directory for uploading data, make sure your http server can access it. The easiest (but least secure) way to do this is give it permissions 777. It is better to give the web server ownership of the directory and limit the permissions.

The top cause of this issue is PHP configured to prevent access to most directories using open_basedir. You may want to check with your hosting provider on this.

Make sure the path is correct and ends with a /. You can check the path in your database in the datalists table.

If you only have ftp access to your server and created a directory but do not know the path of it, you might be able to figure it out from the www file path set in your datalists database table. Asking for help from your hosting help team is recommended at this stage.

I can’t validate my admin account because I don’t have an email server!¶

While it’s true that normal accounts (aside from those created from the admin panel) require their email address to be authenticated before they can log in, the admin account does not.

Once you have registered your first account you will be able to log in using the credentials you have provided!

I have tried all of these suggestions and I still cannot install Elgg¶

It is possible that during the process of debugging your install you have broken something else. Try doing a clean install:

• drop your elgg database
• delete your data directory
• delete the Elgg source files
• start over

If that fails, seek the help of the Elgg community. Be sure to mention what version of Elgg you are installing, details of your server platform, and any error messages that you may have received including ones in the error log of your server.

Updating core¶

Delete the following core directories (same level as _graphics and engine):

• _css
• account
• admin
• dashboard
• entities
• friends
• search
• settings
• simplecache
• views

Themes¶

Themes are just plugins that modify the look-and-feel of your site, so you’ll typically find them wherever Elgg plugins are available.

Language Packs¶

Language packs are just plugins that provide support for another language. There are language packs for the core and they are usually installed in the languages directory off the elgg root directory. Other language packs are provided for various plugins. Generally, the authors make it easy to copy those files into the languages directory of each plugin under the mod directory.

Updating core¶

Delete the following core directories (same level as _graphics and engine):

• _css
• account
• admin
• dashboard
• entities
• friends
• search
• settings
• simplecache
• views

Updating plugins¶

Permissions¶

By default, actions are only available to logged in users. To make them available to logged out users, pass “public” as the third parameter:

elgg_register_action(“example”, $filepath, “public”);

To restrict an action to only administrators, pass ”admin” for the last parameter:

elgg_register_action(“example”, $filepath, “admin”);

Implementing actions¶

Use the get_input function to get access to request parameters:

$field = get_input('input_field_name', 'default_value');

You can then use the Database api to load entities and perform actions on them accordingly.

To redirect the page once you’ve completed your actions, use the forward function:

forward('url/to/forward/to');

For example, to forward to the user’s profile:

$user = elgg_get_logged_in_user_entity();
forward($user->getURL());

URLs can also be relative to the Elgg root:

$user = elgg_get_logged_in_user_entity();
forward(“/example/$user->username”);

You can also redirect to the referring page by using the REFERRER constant:

forward(REFERRER);
forward(REFERER); // equivalent

To give feedback to the user about the status of the action, use system_message for positive feedback or register_error for warnings and errors:

if ($success) {
  system_message(elgg_echo(‘actions:example:success’));
} else {
  register_error(elgg_echo(‘actions:example:error’));
}

Customizing actions¶

Before executing any action, Elgg triggers a hook:

$result = elgg_trigger_plugin_hook('action', $action, null, true);

Where $action is the action being called. If the hook returns false then the action will not be executed.

elgg_register_plugin_hook_handler("action", "register", "captcha_verify_action_hook");
elgg_register_plugin_hook_handler("action", "user/requestnewpassword", "captcha_verify_action_hook");

...

function captcha_verify_action_hook($hook, $entity_type, $returnvalue, $params) {
  $token = get_input('captcha_token');
  $input = get_input('captcha_input');

  if (($token) && (captcha_verify_captcha($input, $token))) {
    return true;
  }

  register_error(elgg_echo('captcha:captchafail'));

  return false;
}

echo elgg_view_form('example');

<form action="http://localhost/elgg/action/example">
  <fieldset>
    <input type="hidden" name="__elgg_ts" value="1234567890" />
    <input type="hidden" name="__elgg_token" value="3874acfc283d90e34" />
  </fieldset>
</form>

// /mod/example/views/default/forms/example.php
echo elgg_view('input/text', array('name' => 'example'));
echo elgg_view('input/submit');

<form action="http://localhost/elgg/action/example">
  <fieldset>
    <input type="hidden" name="__elgg_ts" value="...">
    <input type="hidden" name="__elgg_token" value="...">

    <input type="text" class="elgg-input-text" name="example">
    <input type="submit" class="elgg-button elgg-button-submit" value="Submit">
  </fieldset>
</form>

Helper functions¶

Sticky forms are implemented in Elgg 1.8 by the following functions:

elgg_make_sticky_form($name) Tells the engine to make all input on a form sticky.

elgg_clear_sticky_form($name) Tells the engine to discard all sticky input on a form.

elgg_is_sticky_form($name) Checks if $name is a valid sticky form.

elgg_get_sticky_values($name) Returns all sticky values saved for $name by elgg_make_sticky_form().

Overview¶

The basic flow of using sticky forms is: Call elgg_make_sticky_form($name) at the top of actions for forms you want to be sticky. Use elgg_is_sticky_form($name) and elgg_get_sticky_values($name) to get sticky values when rendering a form view. Call elgg_clear_sticky_form($name) after the action has completed successfully or after data has been loaded by elgg_get_sticky_values($name).

Example: User registration¶

Simple sticky forms require little logic to determine the input values for the form. This logic is placed at the top of the form body view itself.

The registration form view first sets default values for inputs, then checks if there are sticky values. If so, it loads the sticky values before clearing the sticky form:

// views/default/forms/register.php
$password = $password2 = '';
$username = get_input('u');
$email = get_input('e');
$name = get_input('n');

if (elgg_is_sticky_form('register')) {
     extract(elgg_get_sticky_values('register'));
     elgg_clear_sticky_form('register');
}

The registration action sets creates the sticky form and clears it once the action is completed:

// actions/register.php
elgg_make_sticky_form('register');

...

$guid = register_user($username, $password, $name, $email, false, $friend_guid, $invitecode);

if ($guid) {
     elgg_clear_sticky_form('register');
     ....
}

Example: Bookmarks¶

The bundled plugin Bookmarks’ save form and action is an example of a complex sticky form.

The form view for the save bookmark action uses elgg_extract() to pull values from the $vars array:

// mod/bookmarks/views/default/forms/bookmarks/save.php
$title = elgg_extract('title', $vars, '');
$desc = elgg_extract('description', $vars, '');
$address = elgg_extract('address', $vars, '');
$tags = elgg_extract('tags', $vars, '');
$access_id = elgg_extract('access_id', $vars, ACCESS_DEFAULT);
$container_guid = elgg_extract('container_guid', $vars);
$guid = elgg_extract('guid', $vars, null);
$shares = elgg_extract('shares', $vars, array());

The page handler scripts prepares the form variables and calls elgg_view_form() passing the correct values:

// mod/bookmarks/pages/add.php
$vars = bookmarks_prepare_form_vars();
$content = elgg_view_form('bookmarks/save', array(), $vars);

Similarly, mod/bookmarks/pages/edit.php uses the same function, but passes the entity that is being edited as an argument:

$bookmark_guid = get_input('guid');
$bookmark = get_entity($bookmark_guid);

...

$vars = bookmarks_prepare_form_vars($bookmark);
$content = elgg_view_form('bookmarks/save', array(), $vars);

The library file defines bookmarks_prepare_form_vars(). This function accepts an ElggEntity as an argument and does 3 things:

1. Defines the input names and default values for form inputs.
2. Extracts the values from a bookmark object if it’s passed.
3. Extracts the values from a sticky form if it exists.

TODO: Include directly from lib/bookmarks.php

// mod/bookmarks/lib/bookmarks.php
function bookmarks_prepare_form_vars($bookmark = null) {
     // input names => defaults
  $values = array(
    'title' => get_input('title', ''), // bookmarklet support
    'address' => get_input('address', ''),
    'description' => '',
    'access_id' => ACCESS_DEFAULT,
    'tags' => '',
    'shares' => array(),
    'container_guid' => elgg_get_page_owner_guid(),
    'guid' => null,
    'entity' => $bookmark,
  );

  if ($bookmark) {
       foreach (array_keys($values) as $field) {
       if (isset($bookmark->$field)) {
         $values[$field] = $bookmark->$field;
       }
    }
  }

  if (elgg_is_sticky_form('bookmarks')) {
       $sticky_values = elgg_get_sticky_values('bookmarks');
       foreach ($sticky_values as $key => $value) {
      $values[$key] = $value;
    }
  }

  elgg_clear_sticky_form('bookmarks');

  return $values;
}

The save action checks the input, then clears the sticky form upon success:

// mod/bookmarks/actions/bookmarks/save.php
elgg_make_sticky_form('bookmarks');
...

if ($bookmark->save()) {
     elgg_clear_sticky_form('bookmarks');
}

Creating an object¶

To create an object in your code, you need to instantiate an ElggObject. Setting data is simply a matter of adding instance variables or properties. The built-in properties are:

• ``guid`` The entity’s GUID; set automatically
• ``owner_guid`` The owning user’s GUID
• ``site_guid`` The owning site’s GUID. This is set automatically when an instance of ElggObject gets created)
• ``subtype`` A single-word arbitrary string that defines what kind of object it is, for example blog
• ``access_id`` An integer representing the access level of the object
• ``title`` The title of the object
• ``description`` The description of the object

The object subtype is a special property. This is an arbitrary string that describes what the object is. For example, if you were writing a blog plugin, your subtype string might be blog. It’s a good idea to make this unique, so that other plugins don’t accidentally try and use the same subtype. For the purposes of this document, let’s assume we’re building a simple forum. Therefore, the subtype will be forum:

$object = new ElggObject();
$object->subtype = "forum";
$object->access_id = 2;
$object->save();

access_id is another important property. If you don’t set this, your object will be private, and only the creator user will be able to see it. Elgg defines constants for the special values of access_id:

• ACCESS_PRIVATE Only the owner can see it
• ACCESS_FRIENDS Only the owner and his/her friends can see it
• ACCESS_LOGGED_IN Any logged in user can see it
• ACCESS_PUBLIC Even visitors not logged in can see it

Saving the object will automatically populate the $object->guid property if successful. If you change any more base properties, you can call $object->save() again, and it will update the database for you.

You can set metadata on an object just like a standard property. Let’s say we want to set the SKU of a product:

$object->SKU = 62784;

If you assign an array, all the values will be set for that metadata. This is how, for example, you set tags.

Metadata cannot be persisted to the database until the entity has been saved, but for convenience, ElggEntity can cache it internally and save it when saving the entity.

Loading an object¶

$entity = get_entity($guid);
if (!$entity) {
    // The entity does not exist or you're not allowed to access it.
}

$entities = elgg_get_entities(array(
    'type' => $entity_type,
    'subtype' => $subtype,
    'owner_guid' => $owner_guid,
));

$objects = $user->getObjects($subtype, $limit, $offset)

Displaying entities¶

In order for entities to be displayed in listing functions you need to provide a view for the entity in the views system.

To display an entity, create a view EntityType/subtype where EntityType is one of the following:

object: for entities derived from ElggObject user: for entities derived from ElggUser site: for entities derived from ElggSite group: for entities derived from ElggGroup

A default view for all entities has already been created, this is called EntityType/default.

Adding, reading and deleting annotations¶

Annotations could be used, for example, to track ratings. To annotate an entity you can use the object’s annotate() method. For example, to give a blog post a rating of 5, you could use:

$blog_post->annotate('rating', 5);

To retrieve the ratings on the blog post, use $blogpost->getAnnotations('rating') and if you want to delete an annotation, you can operate on the ElggAnnotation class, eg $annotation->delete().

Retrieving a single annotation can be done with get_annotation() if you have the annotation’s ID. If you delete an ElggEntity of any kind, all its metadata, annotations, and relationships will be automatically deleted as well.

Extending ElggEntity¶

If you derive from one of the Elgg core classes, you’ll need to tell Elgg how to properly instantiate the new type of object so that get_entity() et al. will return the appropriate PHP class. For example, if I customize ElggGroup in a class called “Committee”, I need to make Elgg aware of the new mapping. Following is an example class extension:

// Class source
class Committee extends ElggGroup {

    protected function initializeAttributes() {
        parent::initializeAttributes();
        $this->attributes['subtype'] = 'committee';
    }

    // more customizations here
}

function committee_init() {

    register_entity_type('group', 'committee');

    // Tell Elgg that group subtype "committee" should be loaded using the Committee class
    // If you ever change the name of the class, use update_subtype() to change it
    add_subtype('group', 'committee', 'Committee');
}

register_elgg_event_handler('init', 'system', 'committee_init');

Now if you invoke get_entity() with the GUID of a committee object, you’ll get back an object of type Committee.

This template was extracted from the definition of ElggFile.

Advanced features¶

Pre-1.8 Notes¶

update_subtype(): This function is new in 1.8. In prior versions, you would need to edit the database by hand if you updated the class name associated with a given subtype.

elgg_register_entity_url_handler(): This function is new in 1.8. It deprecates register_entity_url_handler(), which you should use if developing for a pre-1.8 version of Elgg.

elgg_get_entities_from_metadata(): This function is new in 1.8. It deprecates get_entities_from_metadata(), which you should use if developing for a pre-1.8 version of Elgg.

File¶

simple_type, file

In file_get_simple_type(), filters the return value

Embed¶

embed_get_items, <active_section>

embed_get_sections, all

embed_get_upload_sections, all

HTMLawed¶

allowed_styles, htmlawed

config, htmlawed

Members¶

members:list, <page_segment>

To handle the page /members/$page_segment, handle this hook and return the HTML of the list.

members:config, tabs

This hook is used to assemble an array of tabs to be passed to the navigation/tabs view for the members pages.

Twitter API¶

login, twitter_api

new_twitter_user, twitter_service

first_login, twitter_api

authorize, twitter_api

plugin_list, twitter_service

Reported Content¶

reportedcontent:add, system

reportedcontent:archive, system

reportedcontent:delete, system

reportedcontent:add, <entity_type>

reportedcontent:archive, <entity_type>

reportedcontent:delete, <entity_type>

Search¶

search, <type>:<subtype>

search, tags

search, <type>

search_types, get_types

search_types, get_queries

Before a search this filters the types queried. This can be used to reorder the display of search results.

Initialise the widget¶

Once you have created your edit and view pages, you need to initialize the plugin widget. This is done within the plugins init() function.

// Add generic new file widget
add_widget_type('filerepo', elgg_echo("file:widget"), elgg_echo("file:widget:description"));

Note: it is possible to add multiple widgets for a plugin. You just initialize as many widget directories as you need.

// Add generic new file widget
add_widget_type('filerepo', elgg_echo("file:widget"), elgg_echo("file:widget:description"));

// Add a second file widget
add_widget_type('filerepo2', elgg_echo("file:widget2"), elgg_echo("file:widget:description2"));

// Add a third file widget
add_widget_type('filerepo3', elgg_echo("file:widget3"), elgg_echo("file:widget:description3"));

Multiple widgets¶

Make sure you have the corrosponding directories within your plugin views structure:

‘Plugin’

• /views
  • /default
    • /widgets
      • /filerepo
        • /edit.php
        • /view.php
      • /filerepo2
        • /edit.php
        • /view.php
      • /filerepo3
        • /edit.php
        • /view.php

elgg_register_plugin_hook_handler('get_list', 'default_widgets', 'my_plugin_default_widgets');

function my_plugin_default_widgets_hook($hook, $type, $return, $params) {
    $return[] = array(
        'name' => elgg_echo('my_plugin'),
        'widget_context' => 'my_plugin',
        'widget_columns' => 3,

        'event' => 'create',
        'entity_type' => 'user',
        'entity_subtype' => ELGG_ENTITIES_ANY_VALUE,
    );

    return $return;
}

<p>
<?php echo elgg_echo("flickr:id"); ?>
    <input type="text" name="params[title]" value="<?php echo htmlentities($vars['entity']->title); ?>" />
</p>

<p><?php echo elgg_echo("flickr:whatisid"); ?></p>

<?php

    //some required params
    $flickr_id = $vars['entity']->title;

    // if the flickr id is empty, then do not show any photos
    if($flickr_id){

?>
<!-- this script uses the jquery cycle plugin -->
<script type="text/javascript" src="<?php echo $vars['url']; ?>mod/flickr/views/default/flickr/js/cycle.js"></script>

<!-- the Flickr JSON script -->
<script>
    $.getJSON("http://api.flickr.com/services/feeds/photos_public.gne?id=
<?php echo $flickr_id;?>&lang=en-us&format=json&jsoncallback=?", function(data){
        $.each(data.items, function(i,item){
            $("<img/>").attr("src", item.media.m).appendTo("#images")
            .wrap("<a href='" + item.link + "'></a>");
    });

    $('#images').cycle({
        fx:     'fade',
        speed:    'slow',
        timeout:  0,
        next:   '#next',
        prev:   '#prev'
    });

});

</script>

<!-- some css for display -->
<style type="text/css">
    #images {
        height: 180px;
        width: 100%;
        padding:0;
        margin:0 0 10px 0;
        overflow: hidden;
     }
      #images img {
          border:none;
      }
</style>

<!-- div where the images will display -->
<div id="title"></div>
<div id="images" align="center"></div>

<!-- next and prev nav -->
<div class="flickrNav" align="center">
    <a id="prev" href="#">&laquo; Prev</a> <a id="next" href="#">Next &raquo;</a>
</div>

<?php

    }else{

        //this should go through elgg_echo() - it was taken out for this demo
        echo "You have not yet entered your Flickr ID which is required to display your photos.";

    }
?>

Create your plugin¶

Step one is to create your plugin as described in the developer guide.

• Create a new directory under mod/
• Create a new start.php
• Create a manifest file describing your theme.

Customize the CSS¶

As of Elgg 1.8, the css is split into several files based on what aspects of the site you’re theming. This allows you to tackle them one at a time, giving you a chance to make real progress without getting overwhelmed.

Here is a list of the existing CSS views:

• css/elements/buttons: Provides a way to style all the different kinds of buttons your site will use. There are 5 kinds of buttons that plugins will expect to be available: action, cancel, delete, submit, and special.
• css/elements/chrome: This file has some miscellaneous look-and-feel classes.
• css/elements/components: This file contains many “css objects” that are used all over the site: media block, list, gallery, table, owner block, system messages, river, tags, photo, and comments.
• css/elements/forms: This file determines what your forms and input elements will look like.
• css/elements/icons: Contains styles for the sprite icons and avatars used on your site.
• css/elements/layout: Determines what your page layout will look like: sidebars, page wrapper, main body, header, footer, etc.
• css/elements/modules: Lots of content in Elgg is displayed in boxes with a title and a content body. We called these modules. There are a few kinds: info, aside, featured, dropdown, popup, widget. Widget styles are included in this file too, since they are a subset of modules.
• css/elements/navigation: This file determines what all your menus will look like.
• css/elements/typography: This file determines what the content and headings of your site will look like.
• css/ie6: Custom rules for ie6 and below.
• css/ie7: Custom rules for ie7 and below.
• css/rtl: Custom rules for users viewing your site in a right-to-left language.
• css/admin: A completely separate theme for the admin area (usually not overridden).
• css/elgg: Compiles all the core css/elements/* files into one file (DO NOT OVERRIDE).
• css/elements/core: Contains base styles for the more complicated “css objects”. If you find yourself wanting to override this, you probably need to report a bug to Elgg core instead (DO NOT OVERRIDE).
• css/elements/reset: Contains a reset stylesheet that forces elements to have the same default

<?php

    function mytheme_init() {
        elgg_extend_view('css/elgg', 'mytheme/css');
    }

    elgg_register_event_handler('init', 'system', 'mytheme_init');
?>

Users, Objects, Groups, Sites¶

ElggEntity has four main specializations, which provide extra properties and methods to more easily handle different kinds of data.

ElggObject: content like blog posts, uploaded files and bookmarks ElggUser: a system user ElggSite: each Elgg site within an Elgg installation ElggGroup: multi-user collaborative systems (called “Communities” in prior versions of Elgg)

The benefit of such an approach is that, apart from modelling data with greater ease, a common set of functions is available to handle objects, regardless of their (sub)type.

Each of these have their own properties that they bring to the table: ElggObjects have a title and description, ElggUsers have a username and password, and so on. However, because they all inherit ElggEntity, they each have a number of core properties and behaviours in common.

• A numeric Globally Unique IDentifier (See GUIDs).
• Access permissions. (When a plugin requests data, it never gets to touch data that the current user doesn’t have permission to see.)
• An arbitrary subtype. For example, a blog post is an ElggObject with a subtype of “blog”. Subtypes aren’t predefined; they can be any unique way to describe a particular kind of entity. “blog”, “forum”, “foo”, “bar”, “loafofbread” and “pyjamas” are all valid subtypes.
• An owner.
• The site that the entity belongs to.
• A container, usually used to associate a group’s content with the group.

GUIDs¶

A GUID is an integer that uniquely identifies every entity in an Elgg installation (a Globally Unique IDentifier). It’s assigned automatically when the entity is first saved and can never be changed.

Some Elgg API functions work with GUIDs instead of ElggEntity objects.

The Groups plugin¶

Not to be confused with the entity type ElggGroup, Elgg comes with a plugin called “Groups” that provides a default UI/UX for site users to interact with groups. Each group is given a discussion forum and a profile page linking users to content within the group.

You can alter the user experience via the traditional means of extending plugins or completely replace the Groups plugin with your own.

Because ElggGroup can be subtyped like all other ElggEntities, you can have multiple types of groups running on the same site.

Writing a group-aware plugin¶

Plugin owners need not worry too much about writing group-aware functionality, but there are a few key points:

$user = elgg_get_logged_in_user_entity();
$container_guid = (int)get_input('container_guid');
if ($container_guid) {
    if (!can_write_to_container($user->guid, $container_guid)) {
        // register error and forward
    }
} else {
    $container_guid = elgg_get_logged_in_user_guid();
}

$object = new ElggObject;
$object->container_guid = $container_guid;

...

$container = get_entity($container_guid);
forward($container->getURL());

<p>
  <a href="<?php echo $vars['url']; ?>pg/file/<?php echo page_owner_entity()->username; ?>">
    <?php echo elgg_echo("file"); ?>
  </a>
</p>

extend_view('groups/menu/links', 'file/menu');

Adding an annotation¶

The easiest way to annotate is to use the annotate method on an entity, which is defined as:

public function annotate(
    $name,           // The name of the annotation type (eg 'comment')
    $value,          // The value of the annotation
    $access_id = 0,  // The access level of the annotation
    $owner_id = 0,   // The annotation owner, defaults to current user
    $vartype = ""    // 'text' or 'integer'
)

For example, to leave a rating on an entity, you might call:

$entity->annotate('rating', $rating_value, $entity->access_id);

Reading annotations¶

To retrieve annotations on an object, you can call the following method:

$annotations = $entity->getAnnotations(
    $name,    // The type of annotation
    $limit,   // The number to return
    $offset,  // Any indexing offset
    $order,   // 'asc' or 'desc' (default 'asc')
);

If your annotation type largely deals with integer values, a couple of useful mathematical functions are provided:

$averagevalue = $entity->getAnnotationsAvg($name);  // Get the average value
$total = $entity->getAnnotationsSum($name);         // Get the total value
$minvalue = $entity->getAnnotationsMin($name);      // Get the minimum value
$maxvalue = $entity->getAnnotationsMax($name);      // Get the maximum value

Useful helper functions¶

function elgg_view_comments(ElggEntity $entity)

The simple case¶

$entity->metadata_name = $metadata_value;

$user->dob = $dob_timestamp;

$object->tags = array('tag one', 'tag two', 'tag three');

$tags_value = $object->tags;

$object->tags = array('tag');
$tags = $object->tags;
// $tags will be the string "tag", NOT array('tag')

$tags = (array)$object->tags;

Finer control¶

function create_metadata(
    $entity_guid,           // The GUID of the parent entity
    $name,                  // The name of the metadata (eg 'tags')
    $value,                 // The metadata value
    $value_type,            // Currently either 'string' or 'integer'
    $owner_guid,            // The owner of the metadata
    $access_id = 0,         // The access restriction
    $allow_multiple = false // Do we have more than one value?
    )

create_metadata($user_guid, 'dob', $dob_timestamp, 'integer', $_SESSION['guid'], $access_id);

$i = 0;
foreach ($value as $interval) {
    $i++;
    $multiple = ($i != 1);
    create_metadata($user->guid, $shortname, $interval, 'text', $user->guid, $access_id, $multiple);
}

elgg_get_metadata(array(
    'metadata_name' => 'dob',
    'metadata_owner_guid' => $user_guid,
));

elgg_get_metadata(array(
    'metadata_owner_guid' => $user_guid,
    'limit' => 0,
));

Common mistakes¶

$object->tags[] = "tag four";

// Won't work!! Only the array values are stored
$object->tags = array('one' => 'a', 'two' => 'b', 'three' => 'c');

$object->one = 'a';
$object->two = 'b';
$object->three = 'c';

Working with relationships¶

// option 1
$success = add_entity_relationship($user->guid, 'fan', $artist->guid);

// option 2
$success = $user->addRelationship($artist->guid, 'fan');

if (check_entity_relationship($user->guid, 'fan', $artist->guid)) {
    // relationship exists
}

$relationship = check_entity_relationship($user->guid, 'fan', $artist->guid);
if ($relationship) {
    // use $relationship->id or $relationship->time_created
}

$was_removed = remove_entity_relationship($user->guid, 'fan', $artist->guid);

Access controls in the data model¶

In order to achieve this, every entity, annotation and piece of metadata contains an access_id property, which in turn corresponds to one of the pre-defined access controls or an entry in the access_collections database table.

How access affects data retrieval¶

All data retrieval functions above the database layer - for example get_entities and its cousins - will only return items that the current user has access to see. It is not possible to retrieve items that the current user does not have access to. This makes it very hard to create a security hole for retrieval.

Write access¶

The following rules govern write access:

• The owner of an entity can always edit it
• The owner of a container can edit anything therein (note that this does not mean that the owner of a group can edit anything therein)
• Admins can edit anything

You can override this behaviour using a plugin hook called permissions_check, which passes the entity in question to any function that has announced it wants to be referenced. Returning true will allow write access; returning false will deny it. See the plugin hook reference for permissions_check for more details.

Also see¶

• Engine reference
• Access library reference

Main tables¶

This is a description of the main tables. Keep in mind that in a given Elgg installation, the tables will have a prefix (typically “elgg_”).

Elgg Events vs. Plugin Hooks¶

There are a few big differences between Elgg Events and Plugin Hooks:

1. Most Elgg events can be cancelled; unless the event is an “after” event, a handler that returns false can cancel the event, and no more handlers are called.
2. Plugin hooks cannot be cancelled; all handlers are always called.
3. Plugin hooks pass an arbitrary value through the handlers, giving each a chance to alter along the way.

Note: Plugin hooks also allow passing a parameters array to the handlers, though this will eventually come to Elgg events as well.

Before and After Events¶

Some events are split into “before” and “after”. This avoids confusion around the state of the system while in flux. E.g. Should the user be logged in during the [login, user] event?

Before Events have names ending in ”:before” and are triggered before something happens. Like traditional events, handlers can cancel the event by returning false.

After Events, with names ending in ”:after”, are triggered after something happens. Unlike traditional events, handlers cannot cancel these events; all handlers will always be called.

Where before and after events are available, developers are encouraged to transition to them, though older events will be supported for backwards compatibility.

Elgg Event Handlers¶

Elgg event handlers should have the following prototype:

/**
 * @param string $event       The name of the event
 * @param string $object_type The type of $object (e.g. "user", "group")
 * @param mixed  $object      The object of the event
 *
 * @return bool if false, the handler is requesting to cancel the event
 */
function event_handler($event, $object_type, $object) {
    ...
}

If the handler returns false, the event is cancelled, preventing execution of the other handlers. All other return values are ignored.

Register to handle an Elgg Event¶

Register your handler to an event using elgg_register_event_handler:

elgg_register_event_handler($event, $object_type, $handler, $priority);

Parameters:

• $event The event name.
• $object_type The object type (e.g. “user” or “object”) or ‘all’ for all types on which the event is fired.
• $handler The callback of the handler function.
• $priority The priority - 0 is first and the default is 500.

Object here does not refer to an ElggObject but rather any object in the framework: system, user, object, relationship, annotation, group.

Example:

// Register the function myPlugin_handle_login() to handle the
// user login event with priority 400.
elgg_register_event_handler('login', 'user', 'myPlugin_handle_login', 400);

Trigger an Elgg Event¶

You can trigger a custom Elgg event using elgg_trigger_event:

if (elgg_trigger_event($event, $object_type, $object)) {
    // Proceed with doing something.
} else {
    // Event was cancelled. Roll back any progress made before the event.
}

Parameters:

• $event The event name.
• $object_type The object type (e.g. “user” or “object”).
• $object The object (e.g. an instance of ElggUser or ElggGroup)

The function will return false if any of the selected handlers returned false, otherwise it will return true.

Plugin Hook Handlers¶

Plugin hook handlers should have the following prototype:

/**
 * @param string $hook    The name of the plugin hook
 * @param string $type    The type of the plugin hook
 * @param mixed  $value   The current value of the plugin hook
 * @param mixed  $params  Data passed from the trigger
 *
 * @return mixed if not null, this will be the new value of the plugin hook
 */
function plugin_hook_handler($hook, $type, $value, $params) {
    ...
}

If the handler returns no value (or null explicitly), the plugin hook value is not altered. Otherwise the return value becomes the new value of the plugin hook. It will then be passed to the next handler as $value.

Register to handle a Plugin Hook¶

Register your handler to a plugin hook using elgg_register_plugin_hook_handler:

elgg_register_plugin_hook_handler($hook, $type, $handler, $priority);

Parameters:

• $hook The name of the plugin hook.
• $type The type of the hook or ‘all’ for all types.
• $handler The callback of the handler function.
• $priority The priority - 0 is first and the default is 500.

Type can vary in meaning. It may mean an Elgg entity type or something specific to the plugin hook name.

Example:

// Register the function myPlugin_hourly_job() to be called with priority 400.
elgg_register_plugin_hook_handler('cron', 'hourly', 'myPlugin_hourly_job', 400);

Trigger a Plugin Hook¶

You can trigger a custom plugin hook using elgg_trigger_plugin_hook:

// filter $value through the handlers
$value = elgg_trigger_plugin_hook($hook, $type, $params, $value);

Parameters:

• $hook The name of the plugin hook.
• $type The type of the hook or ‘all’ for all types.
• $params Arbitrary data passed from the trigger to the handlers.
• $value The initial value of the plugin hook.

Caveat! The $params and $value arguments are reversed between the plugin hook handlers and trigger functions!

1. Define your module as asynchronous JavaScript¶

You can define a module via a view or an URL.

define(function(require) {
  var elgg = require("elgg");
  var $ = require("jquery");

  return function() {
    // Some logic in here
  };
});

<?php
// AMD module
elgg_register_js('backbone', '/vendors/backbone/backbone.js', 'async');

<?php
// AMD shimed module
elgg_register_js('jquery.form', array(
    'src' => '/vendors/jquery/jquery.form.js',
    'deps' => array('jquery'),
    'exports' => 'jQuery.fn.ajaxForm',
));

2. Use require or elgg_load_js to load the module on the current page¶

Once an AMD module is defined, you can use require("my/module") from JavaScript to get access to its “exported” value.

Also, calling elgg_load_js("my/module") from PHP tells Elgg to execute the module code on the current page.

1. Simplified dependency management¶

No more “priority” or “location” arguments for your scripts. You don’t even need to call elgg_register_js() for new AMD modules. They load asynchronously and execute as soon as their dependencies are available. Also, you don’t need to worry about explicitly loading your module’s dependencies using elgg_load_js(). The AMD loader (RequireJS in this case) takes care of all that hassle for you. It’s also possible have text dependencies with the RequireJS text plugin, so client-side templating should be a breeze.

2. AMD works in all browsers. Today.¶

Elgg developers are already writing lots of Javascript. We know you want to write more. We cannot accept waiting 5-10 years for a native JS modules solution to be available in all browsers before we can organize our javascript in a maintainable way.

3. You do not need a build step to develop in AMD.¶

We like the edit-refresh cycle of web development. We wanted to make sure everyone developing on Elgg could continue experiencing that joy. Synchronous module formats like Closure or CommonJS just weren’t an option for us. But even though AMD doesn’t require a build step, it is still very build-friendly. Because of the define() wrapper, It’s possible to concatenate multiple modules into a single file and ship them all at once in a production environment. [*]

AMD is a battle-tested and well thought out module loading system for the web today. We’re very thankful for the work that has gone into it, and are excited to offer it as the standard solution for Javascript development in Elgg starting with Elgg 1.9.

Password validation¶

The only restriction that Elgg places on a password is that it must be at least 6 characters long by default, though this may be changed in /engine/settings.php. Additional criteria can be added by a plugin by registering for the registeruser:validate:password plugin hook.

Password salting¶

Elgg salts passwords with a unique 8 character random string. The salt is generated each time the password is set. The main security advantages of the salting are:

• preventing anyone with access to the database from conducting a precomputed dictionary attack
• preventing a site administration from noting users with the same password.

Password hashing¶

The hashed password is computed using md5 from the user’s password text and the salt.

Password storage¶

The hashed password and the salt are stored in the users table. Neither are stored in any cookies on a user’s computer.

Password throttling¶

Elgg has a password throttling mechanism to make dictionary attacks from the outside very difficult. A user is only allowed 5 login attempts over a 5 minute period.

Password resetting¶

If a user forgets his password, a new random password can be requested. After the request, an email is sent with a unique URL. When the user visits that URL, a new random password is sent to the user through email.

Session fixation¶

Elgg protects against session fixation by regenerating the session id when a user logs in.

Session hijacking¶

Besides protecting against session fixation attacks, Elgg also has a further check to try to defeat session hijacking if the session identifier is compromised. Elgg stores a hash of the browser’s user agent and a site secret as a session fingerprint. The use of the site secret is rather superfluous but checking the user agent might prevent some session hijacking attempts.

“Remember me” cookie¶

To allow users to stay logged in for a longer period of time regardless of whether the browser has been closed, Elgg uses a cookie (called elggperm) that contains what could be considered a super session identifier. This identifier is stored in a cookies table. When a session is being initiated, Elgg checks for the presence of the elggperm cookie. If it exists and the session code in the cookie matches the code in the cookies table, the corresponding user is automatically logged in.

Accessibility¶

Elgg-based sites should be usable by anyone anywhere. That means we’ll always strive to make Elgg:

• Device-agnostic – mobile, tablet, desktop, etc. friendly
• Language-agnostic – i18n, RTL, etc.
• Capability-agnostic – touch, keyboard, screen-reader friendly

Testability¶

We want to make manual testing unnecessary for core developers, plugin authors, and site administrators by promoting and enabling fast, automated testing at every level of the Elgg stack.

We think APIs are broken if they require plugin authors to write untestable code. We know there are a lot of violations of this principle in core currently and are working to fix it.

We look forward to a world where the core developers do not need to do any manual testing to verify the correctness of code contributed to Elgg. Similarly, we envision a world where site administrators can upgrade and install new plugins with confidence that everything works well together.

TODO: other goals/values?

When will feature X be implemented?¶

We cannot promise when features will get implemented because new features are checked into Elgg only when someone is motivated enough to implement the feature and submit a pull request. The best we can do is tell you to look out for what features existing developers have expressed interest in working on.

The best way to ensure a feature gets implemented is to discuss it with the core team and implement it yourself. See our Contributing guide if you’re interested. We love new contributors!

Do not rely on future enhancements if you’re on the fence as to whether to use Elgg. Evaluate it given the current feature set. Upcoming features will almost certainly not materialize within your timeline.

When is version X.Y.Z going to be released?¶

The next version will be released when the core team feels it’s ready and has time to cut the release.

Follow the existing document organization¶

It’s not necessarily the One True Way to organize the docs, but consistency is better than randomness.

Use “Elgg” in a grammatically correct way¶

Elgg is not an acronym, so writing it in all caps (ELGG or E-LGG) is incorrect. Please don’t do this.

In English, Elgg does not take an article when used as a noun. Here are some examples to emulate:

• “I’m using Elgg to run my website”
• “Install Elgg to get your community online”

When used as an adjective, the article applies to the main noun, so you should use one. For example:

• “Go to the Elgg community website to get help.”
• “I built an Elgg-based network yesterday”

This advice may not apply in languages other than English.

Avoid first person pronouns¶

Refer to the reader as “you.” Do not include yourself in the normal narrative.

Before:

When we’re done installing Elgg, we’ll look for some plugins!

After:

When you’re done installing Elgg, look for some plugins!

To refer to yourself (avoid this if possible), use your name and write in the third person. This clarifies to future readers/editors whose opinions are being expressed.

Before:

I think the best way to do X is to use Y.

After:

Evan thinks the best way to do X is to use Y.

Eliminate fluff¶

Before:

If you want to use a third-party javascript library within the Elgg framework, you should take care to call the elgg_register_js function to register it.

After:

To use a third-party javascript library, call elgg_register_js to register it.

Do not remind the reader to contribute¶

Focus on addressing the topic at hand. Do not solicit bug fixes. If they want to contribute to the project, they will come to this section to learn how. Our users don’t want to be constantly reminded how needy we feel.

Prefer absolute dates over relative ones¶

It is not easy to tell when a particular sentence or paragraph was written, so relative dates quickly become meaningless. Absolute dates also give the reader a good indication of whether a project has been abandoned, or whether some advice might be out of date.

Before:

Recently the foo was barred. Soon, the baz will be barred too.

After:

Recently (as of September 2013), the foo was barred. The baz is expected to be barred by October 2013.

Benefits¶

For only $50 per year for individuals or $150 per year for organizations, you can get listed as a supporter on our supporters page. Elgg supporters are listed there unless they request not to be.

All funds raised via the Elgg supporters network go directly into core Elgg development and infrastructure provision (elgg.org, github, etc.). It is a great way to help with Elgg development!

Supporters are able to put this official logo on their site if they wish:

Disclaimer¶

We operate a no refund policy on supporter subscriptions. If you would like to withdraw your support, go to PayPal and cancel your subscription. You will not be billed the following year.

Being an Elgg Supporter does not give an individual or organization the right to impersonate, trade as or imply they are connected to the Elgg project. They can, however, mention that they support the Elgg project.

If you have any questions about this disclaimer, email info@elgg.org.

We reserve the right to remove or refuse a listing without any prior warning at our complete discretion. There is no refund policy.

If there is no obvious use of Elgg, your site will be linked to with “nofollow” set.

Sign up¶

If you would like to become an Elgg supporter:

• read the disclaimer above
• on the supporters page, subscribe via PayPal
• send an email to info@elgg.org with:
  • the date you subscribed
  • your name (and organization name, if applicable)
  • your website
  • your Elgg community profile

Once all the details have been received, we will add you to the appropriate list. Thanks for your support!