Communauté Elgg francophone

Créer un compteAide  
Connexion

Views - les vues (en "cascade")

Le fonctionnement des vues dans Elgg est similaire au fonctionnement des feuilles de style : c'est un emboîtement de petits fichiers (les "vues") les uns dans les autres, qui vont du plus général au plus spécifique et particulier.

Ainsi, toute page affichée à aprtir d'Elgg suit un schéma d'organisation qui ressemble en gros à :

pageshells --> canvas --> layouts --> "grands blocs" / conteneurs -> blocs de contenus --> wrappers --> bloc d'un contenu --> éléments du contenu --> éléments "atomiques"

 

Définition, principes d'organisation et utilisation des vues

à compléter et traduire depuis http://docs.elgg.org/wiki/Views

 

Elgg follows a MVC pattern and Views are the V in MVC. Views are responsible for creating the output. Generally, this will be HTML sent to a web browser, but it could also be RSS, JSON or any number of other data formats.

The Views system handles both the layout of pages and generation of chunks of presentation output (like a footer or a toolbar).

View Types

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);

Important note: From Elgg 1.5 the views system caches view locations. This means if you are a plugin developer who has added a new view to their plugin during development you must either enable/disable the plugin or run upgrade.php for the new view to be discovered.

Extending views

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

elgg_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.

If you extend the core css view like this:

elgg_extend_view('css', 'my/custom/css');

you must do so within code that is executed by engine/start.php (normally this would mean your plugin's init code). Because the core css view is loaded separately via a "<link>" tag, any extensions you add will not have the same context as the rest of your page. It may be easier to extend some other view with a "<style>" block when attempting to add page-specific CSS customizations.

Post processing views

Sometimes it is desirable to post process certain views without overriding or extending the view itself.

An example of this would be to activate certain links - for example turning "#foo" in a wire post into a link to the elgg search page.

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.

Views can also be used to display entities via Elgg's Export Interface.

See also Engine/DataModel/Entities.

Using a different templating system

You can write your own templating system if you want to.

Before going through the motions of drawing views, Elgg checks the $CONFIG->template_handler variable to see if it contains the name of a callable function. If it does, the function will be passed the view name and template vars, and the return value of this function will be returned instead of the standard output:

return $template_handler($view, $vars);

How-tos

References