Search · Index

Solution Grove provides Elgg Customization, Integration, Installation, and Hosting.

Learn More

The main ELGG documentation can be found here http://docs.elgg.org/wiki/Main_Page.  It already explains a lot so this page will just be a quick guide on what's important, the gotchas I encountered and some point comparisons with OpenACS.


INSTALLATION

http://docs.elgg.org/wiki/Installation


DATAMODEL

• All objects are stored in the entities table (OpenACS comparison: acs_objects)
• Object relations are in entity_relationships table (OpenACS comparison: acs_rels)
• Custom fields for custom object types are not created using its own table.  They are stored as metadata using the metadata table and their labels and values are stored in the metastrings table (OpenACS comparison: acs_attributes and acs_attribute_values).  An interesting thing to note here is that a metadata string is stored once only.  So let's say two users input the same URL in their profile, there will be two entries in the metadata table (one for each user) but they will both reference a common entry in the metastrings table.
  

PLUGIN ARCHITECTURE

1. Plugins are located under the mod directory.
2. The common files and directories under a plugin:
• mod/plugin/manifest.xml - manifest file (OpenACS comparison: packages/packagename/packagename.info)
• mod/plugin/languages - for internationalization
• mod/plugin/start.php - the initialization script for the plugin (OpenACS comparison: packages/packagename/tcl/packagename-[init|procs].tcl)
• mod/plugin/actions/ - location of action handlers (OpenACS comparison: think of this as the regular tcl/adp pairs but are tied to an ELGG feature called action handlers.  Binding pages to actions takes care of initializing common variables and libraries so that don't need to do a bunch of php include statements.)
• mod/plugin/views/ - location of views file.
• mod/plugin/pages/ - location of files used inside page handlers.  This is similar to actions directory but mostly used for page handlers rather than action handlers.
3. Plugin ordering is crucial. This means that the views in the last plugin in the plugin order will be used in case there are other views of the same name in other plugins.  More info about this in the customization section.
   

LOOK AND FEEL CUSTOMIZATION

1. The ELGG engine will allow you to customize almost everything by overriding views.  The engine was written in such a way that there should be no need to modify core ELGG files, except for bug fixes in core libraries, to achieve the look you want for an ELGG site.
2. The plugin views directory contains all the different views you want for the site.  The most important subdirectory is "default".  Then you can have some other subdirectories like "rss", "xml", etc.  A view other than the default is called by appending the view variable to the URL (e.g. http//yoursite/somepage?view=print)
3. Views are called using the API elgg_view (OpenACS comparison: this is similar to the include tag and you can also pass in variables)
4. Elgg views are relative.  This means that when you call a view you don't need to include the module name.  This makes overriding possible.  Let's say we call a view using code similar to the following:
   
   echo elgg_view("groups/groupprofile");
   
   This will look for a file named "views/default/groups/groupprofile.php" under all modules and on the default views directory under the root elgg directory.  Remember that I wrote the plugin ordering is crucial.  Using the example, the groups/groupprofile view is a part of the groups module so the full path is "mod/groups/views/default/groups/groupprofile.php".  If you have a plugin named "sgcustom" and it also has a file "mod/sgcustom/views/default/groups/groupprofile.php" and if the sgcustom plugin comes after the groups plugin in ordering, then it will be the one used to display the view.  NOTE: Using elgg_view will not append the views but overwrite.
5. If what you want is to append to a view you use code similar to this:
   
   extend_view("profile/menu/links", "sgcustom/menu");
   
   The particular code above adds to the default view found for profile/menu/links the contents of "mod/sgcustom/views/default/sgcustom/menu.php".  This shows the power of how you can customize the whole ELGG experience without needing to modify core code.
6. Official documentation: http://docs.elgg.org/wiki/Views
   

PLUGIN HOOKS

I've written how easy it is to extend views.  But what about if I want to override some default API behavior.  This is where plugin hooks come in.  Let's say you want to customize the group profile fields.  There's a plugin hook for "profile:fields" for groups and to add in our custom code to it, we do the following code:

register_plugin_hook("profile:fields","group","sg_group_fields");

where sg_group_fields is a procedure that does what we want.

Official documentation: http://docs.elgg.org/wiki/PluginHooks


ELGG EVENTS

These are standard events in ELGG that the engine calls during different phases of site and page initialization and display.  You can register a handler for this so that a custom procedure can be called whenever one of the events are triggered.  (OpenACS comparison: callback procedures)

Official documentation: http://docs.elgg.org/wiki/Elgg_Events


GOTCHAS

• On CSS, be careful when overriding styles.  As an example, you don't normally have a file named "mod/myplugin/views/default/groups/css.php" if you just want to add some custom styles to the groups display as that will ignore the original file and use the one in your plugin instead.  What you usually do is have a file named "mod/myplugin/views/default/myplugin/css.php" and call "elgg_extend('css','myplugin/css.php');" so that they properly cascade.
• As a result of the default caching mechanism, some changes you make like adding new views or a direct change to the site properties in the database (when transfering a db dump to a new location) requires you to "upgrade" to refresh the cache.  You do this by visiting http://yoursite/upgrade.php.  This is necessary since an apache restart will not refresh the in-database cache.
• When you install new plugins they will normally be loaded at the end of the plugin chain.  This could result in some of your customizations to be overriden.  So something doesn't look / behave right and you just recently installed new plugins, take a look at the plugin ordering (Administration -> Tool Administration) when logged in as administrator and see if the newly installed plugin is causing the override.
• Different plugins sometimes clash with each other so check the official plugin page for any mentioned incompatibilities when installing third-party plugins.
  

---

Categories: Documentation (Docwiki Navigation)