Understanding Elgg's view system

Last updated by ihayredinov Comments (1)

GENERAL CUSTOMIZATION PRINCIPLES:

1. Elgg plugins undergo constant updates and bugfixes. It is very common that publishers release new versions of their plugins on regular basis.
It is therefore not a reasonable approach to edit the plugin files directly. With every new release, you would need to compare each file and replicate the changes you have made previously.

2. BEST PRACTICE
The correct approach to customizing Elgg plugins is by following the view system logic:

 

a. OVERLOADING
Overloading is a term used to describe the process of overwriting a certain code without modifying it.

If you look through the directory tree of all plugins, you will notice that most of them are similar. You will have such folders as:
ACTIONS – that’s where plugins store various actions. Each action is registered in start.php with register_action function.
GRAPHICS – this is where plugins store various images used in the design
LANGUAGES – this folder contains language files that are used by plugins for rendering various language versions
Using en.php file for example you can rename your Blogs into Recipes or similar in English. By creating other language files, you can control how the translations are shown on your site.
Most plugins use elgg_echo function to print text, so in stead of printing ‘My plugin is the best’, you would use a language string, e.g. ‘myplugin:thebest’. You would then assign this language string a translation in a corresponding language, e.g. ‘myplugin:thebest’ => ‘My plugin is the best’. See en.php for examples.
VIEWS – this is the most important folder that we will be working with mostly.
Elgg view system allows you to overwrite files within the VIEWS folder.
To overwrite a certain view, you need to place a file with the same name in a folder under the same tree structure, for example:
if you would like to overwrite a file mod/hypeStyler/views/default/hypeStyler/index.php,
you need to place your index.php into mod/hypeMySite/views/default/hypeStyler/index.php
After you have done that, you need to run an upgrade.php script. Type in my-site-name.com/upgrade.php. This will clear the cache and reload the tree structure. Depending on the order of plugins in your Tools Administration, the index.php file that is lower will be picked up. So, you need to place hypeMySite below hypeStyler for your index.php to be used instead of hypeStyler’s.

Similar is true with regards to the VIEWS folder that you will find in your site’s root directory. Plugins that overload views take precedence over the Elgg’s core view files.

b. EXTENDING
Extending is a term used to describe the process of extending a certain code with another code without modifying the original code.

If you would like to add something to a file that resides within the Views folder, you use a function elgg_extend_view.

Locate the file you would like to extend, and write down its path relative to views/default folder, e.g. if you wish to extend a file mod/hypeStyler/views/default/hypeStyler/indexarticle.php, your path is ‘hypeStyler/indexarticle’ (without .php).

Place a file that will be extending the above view in any folder within mod/hypeMySite/views/default (optimally, create a folder with a unique name, so that other plugins do no accidentally overload it).
Let’s say your file resides in mod/hypeMySite/views/default/hypeMySite/overloading_indexarticle.php.

Now, to overload the view, we need to add the funciton to the initialization function of hypeMySite plugin.
Go to mod/hypeMySite/start.php. Locate function hypeMySite_init() {}.
Add the following code within the {}
elgg_extend_view(‘hypeStyler/indexarticle’, ‘hypeMySite/overloading_indexarticle’);

Run upgrade.php.

The indexarticle file will now be appended with the code from overloading_indexarticle.

3. EVENT HANDLER and PLUGIN HOOKS

Another way to make modifications to existing function without modifying them is by using event handlers and plugin hooks. You can read more about them in Elgg documentation.

STRUCTURE:

<< GRAPHICS >> — place the graphics you would like to use in your site in this folder. These can be picked up via html src at mod/hypeMySite/graphics/…jpg
<< ACTIONS >> — place your custom actions here. Register them in start.php. After registering, you can call the actions at action/nameofyouraction
<< VIEWS >> — place all views you would like to overload or to be used for extention here
<< LANGUAGES >> — place your languages and translations in this folder
MANIFEST.XML — this file helps Elgg understand that this is a plugin
START.PHP — when Elgg starts running it implements all start.php files within all active plugins. This is a good place to place your elgg_extend_view function, as well as any event handlers and plugin_hooks.

CSS FILES

hypeMySite has a preset css file, which you can edit to achieve the customization results you want.
To change the sites css, add your selectors and properties in
mod/hypeMySite/views/default/hypeMySite/css/mysite.php
For the CSS changes to take place, you need to run upgrade.php.

ihayredinov

My involvement with Elgg has come to an end. Please do not send me support requests.