A Gentle Introduction to the Views API

Dan Muzykadan@danmuzyka.com

drupal.org/user/48685

Target AudienceExperience creating views through the UI

Basic working knowledge of PHP

Basic understanding of object-oriented PHP helpful, not required

No Views development experience

What we will coverHow to act upon and change Views using Views hooks

Building blocks for creating your own custom fields and filters (and by extrapolation, your own custom sorts, arguments, etc.)

What we will not coverHow to use the Views UI

How to theme views

BackgroundDrupal themer and site builder for several years

Module development for about a year

Needed to do highly custom views for a client

Checking Documentation

Better, but without a conceptual overview I don't understand this.

Much better!

GoalsProvide conceptual overview

Show where to find documentation

Give tips for searching and deciphering Views code

Illustrate the concepts with examples

Equip you to learn more on your own

Strike a balance between clarity and not insulting your intelligence

Example Use Case

Zombie Outbreak!Report of zombies reanimated and destroyed, and

number of brains consumed

Image “Brackishfairy of the DEAD” by Shannon Hayward used under a Creative Commons Attribution 2.0 License http://www.flickr.com/photos/sketchink/2314369576/

Modules UsedViews (Duh!)

CTools

Advanced Help

Devel

Field Collection

Date

Drush

Views API OverviewViews Hooks

Procedural programming Syntax familiar to

module developers and to themers who use preprocess functions

Useful for simple overrides and for exposing data to Views classes

Views Classes and Objects Object-oriented PHP Useful for creating

custom fields, filters, sorts, arguments, relationships, etc.

Good Overview of Views Hooks and Classes

Chapter 11

Views HooksAbsolutely, positively essential: hook_views_api()

(This goes in zombies.module)

Views HooksMerlinofchaos recommends putting your other hooks in

mymodule.views.inc

Views HooksA lot of useful views hooks intercept and change a

view as it's being built

Each of these hooks acts on the view at a particular stage of the 'Views Lifecycle'

Views Lifecycle HooksView Phase Hook Run Before Hook Run After Usepre_execute() hook_views_pre_view() NA Affect the view early in its lifecycle

build() hook_views_pre_build() hook_views_post_build() Affect the view immediately before or after it builds the query

execute() hook_views_pre_execute() hook_views_post_execute() Affect the view immediately before or after the query runs

render() hook_views_pre_render()(Themes can also use this hook)

hook_views_post_render()(Themes can also use this hook)

Affect the view immediately before or after the HTML markup is generated

Learning about Views Lifecycle Hooks

Method 1: Contrib Module API Documentation Sites (e.g. drupalcontrib.org)

Yes, you get SOME information by searching for hook_views_pre_build, hook_views_pre_execute, etc.

BUT, you get more context by seeing where these hooks are invoked in the view build process

Search for: view::pre_execute view::build view::execute view::render

Learning about Views Lifecycle Hooks

Learning about Views Lifecycle Hooks

Method 2: Look at where the hooks are invoked in the view object

You can find the $view->pre_execute(), $view->build(), $view->execute(), and $view->render() methods in:views/includes/view.inc

Sample fromviews/includes/view.inc

Views hook exampleswith Zombies!!!

Views HandlersCreate custom:

Fields Filters Sorts Arguments Etc.

Adding a Handler Create the handler file Make Drupal aware of your handler Expose your data to your handler Clear cache!

Adding a HandlerFirst, an overview of each step

Then, an example with the zombie view

Creating a Handler FileFind an existing handler similar to what you want to

create

Copy the file with the handler definition into your module directory

Rename the handler filemerlinofchaos recommends this naming convention:

[module]_handler_[type]_[tablename]_[fieldname]

(You don't actually have to be this verbose)

Creating a Handler File Change the class name in the handler file Delete the functions you don't want to override Edit the functions you DO want to override

Making Views Aware of Your Handler

Drupal 6 method: hook_views_handlers()

Making Views Aware of Your Handler

Drupal 7 method: Load in your module's .info file

Exposing Data to Your Handler

hook_views_data() Use to create new handlers (e.g., a new field you can add

through the Views UI) Expose data from the database that is not already

exposed to Views hook_views_data_alter()

Use to force existing fields, filters, etc to load your handler instead of the existing handler -or-

Change the data exposed to the existing handler

node_views_data() excerpt

hook_views_data() Documentation

Excellent resource: advanced_help

help/views/api-tables

hook_views_data_alter()

Easier place to start – just override an existing handler

Figuring out what to override

1. Determine the existing handler: dpm($view) inside one of the Views lifecycle hooks

2. Determine where in the $data array to put your override: dpm($data) in hook_views_data_alter() and clear cache

Slightly Contrived Example:Custom Date of Destruction Field

Class Inheritancein Field Example

zombies_handler_field_field_data_field_destruction_date

views_handler_field_field

views_handler_field

views_handler

views_object

Handler Method Documentation

A few commonly-used methods documented in advanced_help

Drupalcontrib.org: search for class_name::method_name (e.g. views_handler_field_field::render_items)

Comments in the code itself

When in doubt, dpm() everything

Less Contrived Example:Custom Date Filter

Filter Handler Example

Default filter: zombie destruction date >= input date

If the zombie destruction date is NULL (zombie has not been destroyed, yet), this does not give us result we want

Filter Handler Example

Add new check box in admin UI:

'Allow content with an empty date field to pass filter'

Class Inheritancein Filter Examplezombies_handler_filter_field_destruction_date

date_views_filter_handler_simple

views_handler_filter_date

views_handler_filter_numeric

views_handler_filter

views_handler

views_object

Recap

Views HooksMake Views aware of your module: hook_views_api()

Act on your view during the view build process: Views lifecycle hooks

Provide data to your handlers: hook_views_data() and hook_views_data_alter()

Views HandlersProvide custom fields, filters, sorts, arguments,

relationships, etc.

Documentation

advanced_help

Comments and code in the Views module itself

DocumentationEach of these sources has areas of strength and

weakness; if you don't find a helpful answer in one, try another

General TipsWhen in doubt, dpm() everything

grep through the Views directory to find the closest ancestor class that defines the function you want to override

CreditsArtwork by Shannon Hayward used under a Creative Commons

Attribution 2.0 license

Brackishfairy of the DEAD: http://www.flickr.com/photos/sketchink/2314369576/

JASON of the DEAD: http://www.flickr.com/photos/sketchink/2776234924/

RANDI of the DEAD: http://www.flickr.com/photos/sketchink/2776238718/

Untitled: http://www.flickr.com/photos/sketchink/5476952538/

Untitled: http://www.flickr.com/photos/sketchink/5476953706/

CreditsMiles, E., Miles, L., Hogbin, E. J., & Stevenson, K. (2011). Drupal's

building blocks: Quickly building web sites with CCK, Views, and Panels. Upper Saddle River, NJ: Addison-Wesley.

How to Stalk Medan@danmuzyka.com

drupal.org/user/48685

groups.drupal.org/user/8040

@danmuzyka

facebook.com/danmuzyka

linkedin.com/in/danmuzyka

IRC: danmuzyka

Questions?