Code / drupal / how to
October 4, 2011 0

The Views module can be broken down into three main parts: the query builder, the display builder and the user interface. Usually, we use the interface to control the other two parts, but sometimes situations call for query and display logic that the interface cannot provide.

A good introduction to dynamic views is the function views_embed_view(). Using this, one can render the finished display of a view stored in the database or in code. It returns rendered HTML:

  1.  
  2. $display = views_embed_view("name_of_view", "display_id", $arg1, $arg2);
  3.  

Often this function is a good alternative to using views blocks, for situations where the view display should be more tightly integrated in a certain area. By using func_get_args(), views_embed_view lets you pass arguments into the view that would normally have to be in the URL.

However, there are situations where views_embed_view just won’t cut it. Here are some examples:

1) The user needs be able to choose what filters/fields exist in the view.
2) Groupings need to be dynamically generated based on user input

The functionality listed above cannot be achieved merely by passing arguments into the view. Rather, one must employ methods of the View object ([views module]/includes/view.inc) in order to build up elements of the view from the foundation.

This approach starts with the function views_get_view(). This function loads a view from any storage, but does not execute or render it.

Now comes the most important function to master, View::add_item(). The code is in views/includes/view.inc. The following snippet demonstrates how to add a node id filter to a view named “example.”

  1.  
  2. $view = views_get_view(‘example’);
  3.  
  4. $options = array(
  5.   ‘value’ => 5
  6. );
  7.  
  8. $view->add_item(‘default’, ‘filter’, ‘node’, ‘nid’, $options, ‘nid_identifier’);
  9.  

Here is a breakdown of arguments found in View::add_item:

1) display id
2) type – can be filter, relationship, field, sort
3) table – can also be table alias
4) options – see below
5) identifier – an internal reference to this filter, useful for establishing predictable dynamic keys for fields/filters/relationships that may get added twice. If you don’t pass anything for this argument, Views will create a unique id using an incremental variable if necessary.

Here is a breakdown of the $options argument, at least that of it which I have used:

1) value – meaningful only to filters. Specifies the conditions that will pass the filter. This can be an array in order to imply the IN operator
2) operator – may assume any of the standard db operators. It is not necessary to specify IN if you provide an array as value.
3) relationship – specifies a relationship for this item to use. Remember that doing this will require that you change the table alias to reflect the relationship table alias.
4) group – filters only. Specifies a group for this filter to be a part of. Numeric or string values will work.

The majority of the work can be done with the add_item function. If I were to choose one more important method to learn within this subject it would be set_option(). Suppose you have defined several filters as being part of groups 0 and 1. Here is how you would use set_option to tell Views what to do with those groupings:

  1.  
  2. $groups = array(
  3.   0 => ‘OR’
  4.   1 => ‘AND’
  5. );
  6.  
  7. $view->display_handler->set_option(‘filter_groups’, $groups);
  8.  

This snippet would create two conditional groups, 0 conjoined by OR and 1 conjoined by AND.

Set_option is a method of the views handler, not the view. It can be used to set any of the other characteristics defined the in the options element of the handler. It can do the same things as add_item but add_item performs additional procedures that help things come out the way you want (in most cases) and is definitely more useful for adding filters, relationships, fields and sorts.

Once you have your view prepared the way you want it, you need to execute and probably render it. The following code will do just that:

  1.  
  2.   $view->init_display();
  3.   $view->pre_execute();
  4.   $view->execute();
  5.  
  6.   // at this point, your view will have results added
  7.  
  8.   $view->post_execute();
  9.  
  10.   // this is the final output  
  11.   $output = $view->display_handler->preview();
  12.  

There is a lot more you can do with dynamic views than I have outlined here. Generally, the best way to learn more about this is to first use the UI to build a view that contains the elements and characteristics that you want to dynamically add in your function. Then look at the export of that view. You will gain a good understanding of what the $view object and its display handler need to look like in code. Having a PHP debugger is also immensely helpful, but short of that, just use dpm liberally.

Leave a Reply