Getting Started With Development

Contents

Introduction

Elgg is a social networking framework: in other words, it provides the basic functionality to run a social network. However, since it is a framework you may need to do a bit of development in order to get your social network working the way you want it to. The good news is that Elgg is very extensible so it should be easy to add the functionality you want through plugins.

This page provides an overview of the information you will need to begin Elgg development. The engine reference and API reference are available if you want to skip this overview and dive into the documentation of the core functionality of Elgg.


Data Model

Most dynamic web applications use a database for the back-end. Elgg supports recent versions of MySQL. Elgg is designed in such a way that a plugin author should not need to create his or her own database tables to support custom functionality. This is because Elgg is underpinned by a flexible, generic data model. This means that should new database functionality be introduced, or if a new data back-end is inserted to support multiple servers or other infrastructure requirements, you won't need to update your plugins and custom code.

Elgg Entities

Elgg is built on atomic data units called entities. A user is an entity. A blog post is an entity. A group is an entity and so on. There is a base class in the Elgg framework called ElggEntity. All other entity classes extend that class. As an example, the ElggUser class extends the ElggEntity class to provide user functionality.

Besides the different entity classes in Elgg, there are three helper classes that makes it easy to add new functionality. The ElggRelationship class allows you to quickly establish connections between entities. A user can "friend" another user. A user can join a group. A photo can be tagged to indicate a user is in that photo. All of this and more can be done with the ElggRelationship class.

The two other helper classes (ElggMetadata and ElggAnnotation) enable developers to attach information to an entity. When a blog post is tagged, the tag can be stored as an instance of ElggMetadata. When a user leaves a comment on a photo album, that is stored as an ElggAnnotation.

In Elgg's file structure, the PHP classes described above can be found in the directory /engine/lib.

See also:


Actions

An action in Elgg is the code that runs when a user does something. When a user logs in, the login action is called. When a user submits a comment, the add comment action is called. Generally, actions are called when a user submits a form. The action processes the form, makes the appropriate modifications to the database based on the input, and then forwards the user to a new page while supplying feedback through a system message.

Actions are called through a central action handler. Actions are registered with the framework during the framework boot process. The central handler performs some security checks and then calls the registered action file.


See the action reference for details on how to register and construct an action. To look at the core actions, check out the directory /actions.

Elgg's Event System

Elgg has an event system with two types of events that you can register handlers for.

Elgg Events

Elgg events are triggered when something is created, updated or deleted or when the Elgg framework is loading. Arbitrary events can also be triggered by any plugin. Each event is determined by an event name and an object type (system, user, object, relationship name, annotation, group).

There are four special events: boot, system, which is inaccessible to plugins and is triggered when the system is loading its libraries; init, system, which is intended to allow plugins to initialise themselves before any action is called or anything is drawn to the screen; pagesetup, system, which is generally called just before the HTML content starts to be created; and shutdown, system, which is called after the rendered page has been sent to the user.

To register for an event, you define a function that takes the event, object type and the object being acted on (if any) as parameters and returns either true or false. A false result will halt the event and prevent any further event handlers from being called. It may also stop code in the core from running; for example it may prevent an entity from being deleted.


See the event reference for details on how to construct your event handler functions and register for a particular event.

Plugin hooks

Plugin hooks are similar to events. You can register handlers to be run when something happens with plugin hooks just like you can with events. They are different from events in some subtle ways which are covered in the documentation on plugin hooks.

Just as system events are provided in the Elgg framework, there are many core plugin hooks. An example is cron, which allows you to run custom functionality in the background on a regular basis (assuming the site administrator has set up a crontab on their server).

It is a good idea to trigger a plugin hook at various points in your plugin. For example a good place is in your actions since another plugin author might wish to expand your functionality. This allows other plugins to add functionality without modifying your code.

Output

You should now have a basic understanding of Elgg's data model and some of the controller logic (like events and actions). What hasn't been mentioned is actually creating HTML code to send back to the browser. Elgg attempts to separate logic from presentation code using its own templating system. In the Elgg vocabulary, these templates are called views. You will find the default core views under the /views directory.

Views

Each view is responsible for creating a section of presentation code from input data. For example, the default object/blog view takes in as input an ElggObject entity of subtype blog and creates the HTML to display the blog title, blog text, tags, and comments. Each component of a page is created by a view: the toolbar, header, two-column layout, sidebar, footer, and so on are all separate views. Any view can call other views. As an example, the object/blog view calls the output/tags view to display the tags that have been attached to the blog.

View name

A view name is determined by its path. For example, the HTML for the toolbar at the top of an Elgg page is created by the view page_elements/elgg_topbar and this code is located at /views/default/page_elements/elgg_topbar.php. When elgg_view('page_elements/elgg_topbar') is called, the Elgg framework includes the PHP file mentioned above. Input to the view is passed to the view code through the array $vars[].

View type

Besides views, there are viewtypes. The viewtype determines the type of display. The default viewtype generates HTML formatted for a desktop or laptop web browser. The rss viewtype creates RSS feeds. A developer could define a mobile viewtype to create HTML formatted for mobile devices. The same controller code is run to collect the data for the user but it is rendered different based on the viewtype. As you look through the /views directory, you will see subdirectories like default, json, and rss. These are the viewtypes supported natively by the framework. When the rss viewtype is selected and the object/blog view is called for, the framework includes the file rss/object/blog.php. The type directory is always in the directory path before the view name: views/{viewtype}/{viewname}.php.

Overriding views

Plugins will be discussed next, but it is important to mention that they can override any view. A plugin has its own views directory. If it has a view with the same type and name as a core view, the Elgg framework will automatically call the plugin's view rather than the core's view. You could replace the entire templating system this way if you wanted to.

Extending views

There will be many instances when you do not want to replace a view, but add content to it. Perhaps you want to add some sort of widget to the sidebar. This can be done by extending a view by calling extend_view(). Now your presentation code will be included after the primary view code.


For more information on views in Elgg, see the views documentation.

Javascript

Elgg uses the jQuery toolkit to support rich client interfaces. By default, Elgg includes on every page the core jQuery library, the jQuery UI library, and the jQuery Form plugin. Some pages also include the jQuery Easing plugin. The customized jQuery UI library includes its UI core, 3 interactions (draggable, droppable, sortable), and one widget (accordion). You can include your own javascript through the HTML header by extending the metatags view (though Elgg really should add a javascript header view that can be overridden or extended).

Internationalisation

The Elgg framework provides a translation mechanism for supporting multiple languages. Translation files are created for each language and the framework will pull in the correct output text based on the language selected.


For more information on internationalisation, see the internationalisation reference.

Plugins

The Elgg framework is very extensible. You can write a plugin to extend or replace just about any portion of the core Elgg functionality. Plugins interact with the system through the mechanisms previously described: events, actions, and views plus more that are mentioned in the engine reference like notifications. A plugin can be used to create a new theme by overriding the css view and/or changing other views. A plugin can add significant functionality to what is provided out-of-the-box by Elgg (an event calendar system for example). A plugin can change a piece of Elgg functionality like replacing the default registration method with LDAP. The possibilities really are endless.

Plugin directory structure

It is recommended that each plugin mimic the directory setup of the Elgg framework. Under the base directory of your plugin, you should have an actions directory, a languages directory for internationalisation, a graphics directory for any images used by the plugin, a views directory, and maybe a lib directory if the plugin depends on external libraries. By following this setup, Elgg will take of automatically loading parts of your plugin without you needing to do a thing. This will be discussed further in the plugin documentation.


For more information on building plugins, see the Plugin development reference.

Caching

Besides an experimental interface to Memcache, Elgg provides some built-in caching to speed page generation. Currently there are two caches: a view path cache and something called SimpleCache for caching static content. The view path cache enables the Elgg framework to skip the expensive step of scanning all of the views directories. The SimpleCache allows developers to cache pages that rarely or never change (like css or javascript) rather than dynamically generating them on each page load.

When doing plugin development, it is important to turn off caching. The easiest way to do this right now is to use this plugin.

Conclusion

This was just a quick overview of the Elgg framework. There are plenty of topics not mentioned here like notifying users, importing and exporting data, and exposing functionality to external programs. Before beginning development, be sure to read through the Engine overview and try out a tutorial or two.

Also, if you want to check out the latest Elgg code base from the Subversion repository, read this. If you find a bug or want to submit an enhancement back to the core, read this and this.

As you run into questions, it is a good idea to check the Development FAQ to see if they are already answered.

Search docs