It's possible that you might want your Elgg site to have several sets of interface pages. For example:

• Standard HTML
• HTML optimised for accessibility
• Mobile Internet
• iPhone
• Embeddable widget

In Elgg, one set of interface pages is called a view type. Each individual display element - a blog post, a user icon, a title - is called a view.

Elgg has a powerful views system, which ensures that presentation is separate from logic and allows for advanced features like automatic RSS generation, a swift-to-develop mobile interface, and the alternative interfaces suggested above.

Using views

Views have string names - for example, the name for the site CSS view is just 'css'. They can also be broken up into groups, for example 'page_elements/title', 'page_elements/header' and so on.

Each view is stored in a separate file. The directory structure reflects the view type that the view is in. The default view type is called 'default', so the 'page_elements/header' view described above is stored in:

• /views
  • /default
    • /page_elements
      • /header.php

To display this view, you would call:

echo elgg_view('page_elements/header', array('variable1' => $value1, 'variable2' => $value2));

The variables array is how you pass values to the view. These are made available within the view as elements of the $vars array. In the example above, variable1 would be made available within header.php as $vars['variable1'], variable2 would be made available as $vars['variable2'], and so on.

$vars is also prepopulated with a couple of important variables:

• $vars['url'] is always the URL of the current Elgg site
• $vars['user'] is the current user object, if any is logged in
• $vars['config'] is the configuration object (normally stored in the global variable $CONFIG)

Views in plugins

Each plugin may have its own /views directory. This is treated by Elgg to be the same as the root views directory, with the exception that views belonging to a plugin will take precedence over the ones provided by the Elgg core.

Therefore, /mod/myplugin/views/default/page_elements/header.php will completely overwrite the page header, as it's considered to have a view name of page_elements/header and will supercede the version in core.

You can manually do the same thing with the set_view_location function:

set_view_location($view_name, $full_path_to_view_file);

Extending views

A plugin may extend a view by calling the following function:

extend_view('view/to/extend', 'view/to/extend/with');

An optional third parameter sets the priority. The original view is given a priority of 500, so setting the priority to below that means the new view content occurs before the original view; setting a priority over 500 (the default behaviour) causes the content to occur after the original view.

Controlling the viewtype

The default view is called default. However, you can alter Elgg's viewtype simply by setting the $view input variable. For example, to get an RSS version of a page, you might access:

http://your-elgg-site.domain/pg/your/site/page/?view=rss

You could also write a plugin to set this using the set_input() function. For example, your plugin might detect that the page was accessed with an iPhone's browser string, and set the viewtype to iphone by calling:

set_input('view','iphone');

The plugin would presumably also supply a set of iPhone views.

Displaying entities

If you don't know what an entity is, check this page out first.

The following code will automatically display the entity in $entity:

echo elgg_view_entity($entity);

As you'll know from the data model introduction, all entities have a type (object, site, user or group), and optionally a subtype (which could be anything - 'blog', 'forumpost', 'banana'). elgg_view_entity will automatically look for a view called type/subtype; if there's no subtype, it will look for type/type. Failing that, before it gives up completely it tries type/default. (RSS feeds in Elgg generally work by outputting the object/default view in the 'rss' viewtype.)

So for example, the view to display a blogpost might be object/blog. The view to display a user is user/user.

Full and partial entity views

elgg_view_entity actually has a number of parameters, although only the very first one is required. The first three are:

• $entity - The entity to display
• $viewtype - The viewtype to display in (defaults to the one we're currently in, but it can be forced - eg to display a snippet of RSS within an HTML page)
• $full - Whether to display a full version of the entity. (Defaults to false.)

This last parameter is passed to the view as $vars['full']. It's up to you what you do with it; the usual behaviour is to only display comments and similar information if this is set to true.

Listing entities

This is then used in the provided listing functions. To automatically display a list of blog posts (see the full tutorial), you can call:

list_entities('object','blog',0,10,false);

The parameters supplied above are the type of entity, subtype, owner (in this case 0 for all owners), number of elements to display on a page, and whether to display a full version of each element.

This function checks to see if there are any entities; if there are, it first displays the page_elements/pagination view in order to display a way to move from page to page. It then repeatedly calls elgg_view_entity on each entity, before returning the result.

Because it does this, Elgg knows that it can automatically supply an RSS and OpenDD feed - it extends the metatags view (which is called by the header) in order to provide RSS autodiscovery, which is why you can see the orange RSS icon on those pages.

See also Engine/DataModel/Entities.

How-tos

• Creating a new site theme
• Page structure best practice

References

• Useful built-in views to extend
• Quick function reference

views

Last updated 274 days ago by Pete Harris