Integrating Views 2 into Your Modules
an attempt at an explanation
Note: If I have anything wrong in this article, please correct me. I want to get a decent draft together and then add it to drupal.org somewhere.
Audience
This article is for experienced Drupal developers.
In order for this article to make sense, you would need to know:
* PHP - intermediate (you do not need to have magical PHP powers, but understanding the difference between an array and an object would help)
* how to use the Drupal API - can look up Drupal functions on the internet. api.drupal.org
* know the Views UI interface (configuring, exporting, importing views. what the filters, arguments, fields, settings, attachments do when you create a view at admin/build/views )
* can create a basic Drupal module (.info, .module, using some of the main 'hook' like hook_help, hook_block, hook_menu etc.)
* basic MYSQL queries (you have used phpMyAdmin, the mysql commandline or other Mysql interfaces like Navicat, and have typed in an SQL query and seen the list of results that it produces.)
* integrating a module with the theme layer (implementing hook_theme, making theme function, theme_blahblahblah, know to clear & rebuild the theme registry)
Making Views modules half as hard as making a theme
If you can theme Drupal sites, you can do this! :) This article will try to connect you with the resources so you can learn how to do this. It might take a bit of learning, but if you could learn how to theme Drupal sites, you can totally make modules that extend what Views can do, and make the database data suit your needs perfectly. I would estimate that learning how to make views modules is half as hard as themeing Drupal sites (timewise.)
Document as you learn
The reason I am writing this article is because when I had to write a views module, I couldn't find anything on the internet that helped me understand how to know where to start. Knowing the tools I had available to me, I could see that it would have taken a long time to figure out what to do. The only reason I learned was because my co-worker showed me how to do it. Most of us do not have anyone to show us how, so that is why I am writing this article.
As you learn and find things that are not accounted for 'in the internet' (and especially on drupal.org) you can 'add an issue' to the issue queue (for the module) and add your notes there? or make additions to the handbook pages - something like that (I need to figure that part out.)
Review
Object Oriented syntax (refer to PHP manual and /add: these sources/ ) - also called 'OOP'
OOP is just a slightly different way of writing PHP. There are some minor changes in how you set up your files, some special syntax, and a few conceptual uses.
Concepts that would help to review
Classes
'Extending classes'
Inheritance
:: - the double colon thing (used to 'pull down' a function from the 'parent' class, the one you are extending')
order of execution in classes
Introduction
As you may know, the Views 2 module in Drupal is so powerful that it is sometimes called magical. 'Magical' because due to the way it was created, people, including the creator Earl Miles (merlinofchaos), are still discovering the uses.
Something so powerful is hard to document. But, rather than telling you how to build something, in this article, I will share with you a path to figuring out how to integrate views into your modules.
We are going to "Views Empower" you.
Why?
The main thing I didn't understand about Views was that rather that themeing & preprocessing nodes & fields, you can make little modules for Views that take care of some of the things you might do if you were themeing. This can be handy if you built many Drupal sites for different clients.
I would have been resistant to learning this at first because themeing and preprocessing is so fast & easy & Views was a huge pain to learn how to build custom modules.
Other things you can do (which is why I am sharing this with you)
You can do stuff with data imported into your database. One thing that I usually shy away from is dealing with data from other places. I usually feel safer in CCK and the theme system because I know I can control the output. I usually wouldn't wind up importing lots of data into a Drupal site, and if I did have to do that, my 'safe route' would have been to use Feed API and map content to nodes & fields, and then theme it. (All theoretical, I haven't actually played with it that much.)
My 'un'-safe route would've been to make a views thing that would do this for me. But that would be really hard because I don't think I would have been able to frame a description of what I needed to build in a way that would have worked for Views. My goal in this article is to describe how I would frame a problem so that it could work with Views. It isn't difficult, it is just a matter of knowing what is possible, and what the names of the tools are.
Stuff you can make using the Views API
Style plugins: wrap views data in the css markup that you want, so you don't have to theme it over & over again
Make your view data themeable: take data that wasn't connected to your drupal site, and make it so you can theme it special for each website)
Make a filter - allow any item anywhere in your database to act as a 'filter': A 'filter' is just where you say 'if this is true, then add it to the list'
Make a special field that says anything you want it to say: a combination of stuff from the database and stuff people give as labels
Other stuff: You can also make more arguments, funky attachments and probably all kinds of other stuff, but I'm just going to stick to these things because that's what I know how to do.
(Anyone? Why else should you make Views plugins?)
Things to remember
All Views does is create SQL queries that pull out data from your database tables. You can get data from your database in lists that filter and join and mix and match in a bazillion different ways. 'Views' provides 'views' of your database. 'Lists' of data. 'Items' of data. 'Results' of data.
The Views User Interface (Views UI) is one half of the magical features of Views. The Views UI is the place where you click, construct and edit 'Views.'
The other half of the magic is that when you save your views settings, you make a 'Views Object' which contains everything Views needs to know to build that SQL query whenever it is supposed to. When you 'export' a view - that code that you paste to 'import' the view is the views object. It is just a big old array.
The 'Views Object' connects a whole bunch of components that are responsible for building different parts of that SQL query. Cause remember, all Views does is build SQL queries and hand them over to the theme system.
(REVIEW : Is this true?)
Views Review
Something helpful that I learned in a presentation on Views 2 by Larry Garfield (crell) is that all of the parts of the Views UI map to part of an SQL query.
Here is a typical query that views might spit out:
----------- * MAKE DIAGRAM *
Select ........ from ........ Where ...... AND ......
This is how the Views 'components' map to the view:
context of view (where, when view happens, views display)
argument - field - filter = output (results) run results through styles
(draw a picture?)
Views Vocabulary:
The hardest part of views (for me) what that I would hear and see terms and I did not know how the terms mapped to the views codebase.
The most important words to know for making views modules
(write definitions of these...requires research, i *sort of * know what these mean, but i do see where they connect in the code)
handler
filter
plugin
styles plugin
views module
views plugin (?)
views integration
Making a Views Module
After I learned how what a views module does, this article made sense, and it contains all of the things you would need to know in order to put together a views module.
A very, very fantastic tutorial by Neil Hastings of Treehouse Agency:
-> http://treehouseagency.com/blog/neil-hastings/2010/01/19/views-handler-e...
As you can see in that article, you need a module that has:
(make downloadable example)
mymodule.info
This is a normal module .info file
* add a views dependency (example)
mymodule.module
Your module. This can be a module that only does views stuff, or you can add this same views stuff into an existing module. This is what people mean when they say 'views integration' (I am pretty sure.)
* must include hook_views_api() -- this connects your module to the views module (example)
* must provide a link/path to your special views includes files
* if your view has theme functions, they go in hook_theme (example) (I think this is the recommended practice. Personally, if I had a module that had extra views stuff that wasn't totally necessary, I would consider putting it in its own module mymoduleviews and have a separately named hook_mymoduleviews_theme.
includes/mymodule.views.inc
* hook_views_handlers()
(explain)
* hook_views_plugins() [check this]
(explain)
* hook_views_data()
(explain)
(this does crazy fancy stuff and is very important)
includes/mymodule.nameofpluginthing.inc
* a class that extends blah
includes/mymodule.nameofsomeotherfeature.inc
* a class that extends blah
includes/mymodule.default.inc (to do, look up the correct name)
* a view you are providing by default
* how to export a Views UI and make a default view
* hook_views_default... (look up) -- this had some of the code, some wrong documentation...show working example & how to stitch together.
* Question: how to add more default views?
How to know what to do
In this article, my goal is to set you up so you can start inventing modules that integrate with views. What helped me was having a goal that was well suited for Views. It wasn't until I was presented with this kind of problem that I had a reason to make a custom view module, and while that seems kind of obvious, there is something more subtle there.
I did not understand what I could do with a views handler module. I only had a vague understanding. I think I thought I could do the following:
* provide a default view to go with a module
* make a style
Really, that's all I thought. I hate admitting this here because I usually am expected to know everything about programming and I always work in situations where I am not allowed to admit I do not know something. But I want others in my situation to know you aren't alone if you were having a hard time figuring out what to do.
So that said, views actually does some other stuff - but it probably only makes sense if you have the right puzzle to apply it to. Themeing a website with data generated by CCK is probably not the best place to start, because a lot of that work you already use every day.
So, to understand views, you need an out-of-the-ordinary situation. If you are not a professional module developer, you might not often get into out-of-the-ordinary situations because the way you might solve the problem would be
look for a module that does the task
try to use the theme system to solve your problem
avoid the problem as too expensive and time consuming
When would you make a views module
* I welcome more ideas.
When I had to make some views filters, it was because we had a module that was importing data from another webserver. The data was imported into its own tables (not CCK.)
We created filters that performed a special query with a bunch of joins that returned very specific information. These filters were also treated as exposed filters, and given some special formatting.
We also made style plugins that grouped results by month, and fixed multiple events so that each event showed its date.
[Think of a more generic example & make a sample module for it]
[OK - must stop for the night, have deadline...will come back to this this weekend. Leaving published in case anyone is curious. May 12, 2010]
----[ WORKING ON THE GUTS OF EXPLAINING WHAT I LEARNED HOW TO DO - WORK IN PROGRESS ]
Final Words
If Views confuses you it does not mean you are stupid or a bad programmer. It means that you probably do not have the same mental image of Views that other Drupallers have. If I knew how they knew this stuff, I would totally tell you. They all say 'I just figured it out' - and usually that means that they pieced together their views module by looking at the contributed views modules. I head someone say that there is no one right way, and everyone builds differently.
Call for Documentation
Views could use more help with documentation.
* Views issue queue requests for documentation: [see if there is a link that would pop up]
* Recommended procedure for making documentation issue requests [what is it?]
* Work on the handbook (for various Views audiences, whatever they might be.)
* Virtual Documentation Sprint: (if there is a documentation queue for views, it would be possibly to organized a documentation sprint. i would invite everyone i know who said they made views modules before and guilt trip them into helping out. but then also i would make an even bigger spectacle to the various businesses that profit off of views...cause really, people rely on views about as much as they do Drupal.
Resources
Where to look when you are learning how to build custom views modules
* Views 2 API
* Advanced Help in the Views module
(Investigate)
Terms to Google
contributed modules
example modules
Good tutorials
Good screencasts
Books
Videos
Podcasts
Drupal pages
Handbook
Hidden Handbook pages (that should be linked from the front page, but are somehow buried in drupal.org)
Status of views documentation issue queue