Views

Elgg's view system creates the response sent to the requester. It could be an HTML page, RSS feed, XML document or any other format. The generation of the response is divided into two parts: rendering the data related to the request and including the rendered data into the full response. Elgg uses a template system to create the response.

View templates

Templates allow dynamic content to be included in a static structure. Consider the following simple example of an Elgg view:

<h2><?php echo $vars['title']; ?></h2>

This view creates the HTML for displaying a title. The h2 tag is static while the value between the tags is dynamic.

The $vars[] associative array contains the variables passed into the view. The function elgg_view() is used to generate the output of a view (a string):

echo elgg_view('page/elements/title', array('title' => 'Hi'));

The name of a view is determined by its path. A core view with the name 'input/button' is located at /views/default/input/button.php.

Views can be nested. The 'page/elements/header' view includes other views:

<?php
/**
 * Elgg page header
 * The header lives between the topbar and main content area.
 */

// link back to main site.
echo elgg_view('page/elements/header_logo', $vars);

// drop-down login
echo elgg_view('core/account/login_dropdown');

// insert site-wide navigation
echo elgg_view_menu('site');

Views are not limited to the variables in the $vars[] array. They can pull information from the data model or helper functions.

Page shells and layout

Rendering the response is divided into two steps. The first is rendering the data specific to a request and the second step is laying out the page. In code, it looks like the following:

// render the latest bookmarks as a list
$options = array(
  'type' => 'object',
  'subtype' => 'bookmarks'
);
$content = elgg_list_entities($options);

// render the response
$title = elgg_echo('bookmarks:latest');
$body = elgg_view_layout('one_sidebar', array('content' => $content));
echo elgg_view_page($title, $body);

The function elgg_view_layout() lays out the central portion of the page identified as 'layout' in the preceding layout diagram. The output of the layout is passed to elgg_view_page() and is inserted into the final response.

Elgg includes generic layouts for one, two, and three columns in addition to a layout specifically for content pages (viewing blogs, bookmarks, files, and similar types of content). The views for these layouts are located in /views/default/page/layouts/. Additional layouts can be added through plugins.

The elgg_view_page() function uses a page shell view to create the complete response. The default page shell for HTML is located at /views/default/page/default.php. This view includes the HTML head, topbar, header, and footer.

View type

The view type parameter determines the response format. A request for http://example.org/blog/ owner/johndoe returns HTML formatted for a web browser. A request for http://example.org/blog/owner/joh ndoe?view=rss returns an RSS feed. The standard HTML view type uses the default view, which is why those views are located in /view/default/. Likewise, the RSS views are in /views/rss/. Each top level directory in /views/ is a different view type.

Overriding and extending views

Overriding a view replaces a core view with a plugin's view. When a view exists in the same relative location in a plugin as it does in the core views, Elgg uses the plugin's view. A plugin that has a file at /mod/<plugin name>/views/default/page/elements/header.php overrides the 'page/elements/header' view of the core. In addition to overriding core views, plugins can override views from other plugins.

The content from one view can be added to that of another view by extending it. The syntax for this is as follows:

elgg_extend_view('page/elements/header', 'mytheme/site_menu');

Special views

There are certain views that Elgg automatically checks for and uses, if they exist. This is one instance of convention over configuration in Elgg. A primary example of this is that each entity has a special view used to display it. The name of the view is based on the entity's type and subtype. The view for displaying a blog post is 'object/blog' and the view for a user is 'user/default'. Rendering an entity is performed by passing it to the elgg_view_entity() function, as follows:

$html = elgg_view_entity($blog);

Other special views include the following:

• Plugin settings: /mod/<plugin name>/views/default/plugins/<plugin name>/settings.php

• User settings: /mod/<plugin name>/views/default/plugins/<plugin name>/usersettings.php

• Widget settings: Widget settings: /mod/<plugin name>/views/default/widgets/<widget name>/edit.php

• Widget content: /mod/<plugin name>/views/default/widgets/<widget name>/content.php

Code location

Functions: /engine/lib/views.php

Core views: /views/