Everybody on the Drupal ecosystem knows that the View module is a query builder.
You select some database fields and some rules (equals, not equals, etc) from
the View builder and gets the output of the query in page or block or some
other format. All's fine so far. The problem started when I actually tried to
create a View instead of reading its praises. The problem was simple - I
couldn't find the database fields of my love in View builders field list. I was
eventually enlightened by Mr. Nobleman.
As it turned out, View is not an entirely point-and-click module like most others.
If I want to invite an artibrary database field into the View club, then an active
module must send it an invitation, just like gmail :-)
Really, there's no invitation and only arrays. Which means an active module must
list that specific tables and its fields in an array. This inclusion happens inside the
views_table hook of the module. The format of the array goes like this:
$tables["tablename"] = array(
"name" => "table_name",
"join" => array(
"left" => array(
"table" => "users",
"field" => "uid"
),
"right" => array(
"field" => "userid"
)
),
"fields" => array(
"field_name_0" => array(
"name" => "Name-of-Field",
"sortable" => TRUE,
"help" => "..."
)
"field_name_1" => array(
"name" => "Name-of-Field",
"sortable" => TRUE,
"help" => "..."
)
)
);
Let me explain this array. The first array key is "name" and its value is the name of the table we are asking View module to acknowledge. Next key is "join". It tells with which table our table will be joined. If we have no particular table in mind, then the answer is "node". If we have the "Y" table in mind, then we should mention it and View will create a query like "... node LEFT JOIN Y ON node.field = Y.field AND Y LEFT JOIN our_table ON Y.field = our_table.field ..." This is because everytable View deals with must be somehow related to the "node" table. Please note that our table will be always on the right side of the join.
"join" => array(
"left" => array(
"table" => "users",
"field" => "uid"
),
"right" => array(
"field" => "userid"
)
)
The "join" key has an array as its value. This array itself is seen to have two keys. As already explained, the "left" key describes the other table we want to join. The "right" key says which field of our table will be used in the join. We don't have to mention the name of our table using the "table" key as View assumes that it's OUR table. In the above example, View will produce a query like "... users LEFT JOIN our_table on users.uid = our_table.userid ..."
This leaves us with the "fields" key. The value of this key, again, is an array. This is the place where we mention the list of our beloved fields:
"fields" => array(
"field_name_0" => array(
"name" => "Name-of-Field",
"sortable" => TRUE,
"help" => "..."
)
"field_name_1" => array(
"name" => "Name-of-Field",
"sortable" => TRUE,
"help" => "..."
)
)
For each field, we must mention three properties. These are:
- The name we want to see for this field in the field list of View builder.
- Can this field be used for sorting?
- Some help text describing what this field is for.
There are some other properties, but these three are the main ones.
That's all. Now you have to return this $tables array from the views_tables hook of your module. What if you want to include fields from some other table? Easy! Just add another key to the $tables array and follow the approach mentioned above.
Another list similar to the field list in the view builder is the arguments
list. If you want your favourite database field to appear in this list too,
then you have to implement the views_arguments hook in an active module. The
structure of the array is different in this case:
array(
"details" => array(
"name" => "Gal_balance: details: Details of ...",
"sortable" => TRUE,
"help" => "..."
)
);
All these information and more are available at http://drupal.org/handbook/modules/views/api. Unfortunately the View users' manual doesn't give any hint to it. Even the afore mentioned URL doesn't discuss everything about Views. So Mr. Nobleman's parting advice was, when in doubt,
read the source!