The dashboard is a simple node type designed to work like a static page that can display content in a two column format, with header and footer areas. It is meant to look like this:
+---------+ | | +----+----+ | | | | | | +----+----+ | | +---------+
Each area has its own section, created entirely by
tags and styled via CSS. The CSS tags can be easily overridden in the any theme.
NOTE: Dashboard is probably misnamed at this point; it is merely the start to what the final dashboard functionality ought to be, which includes large amounts of configuration. I'm not entirely interested in coding that, though, so another developer may have to put in some work to get that functionality.
USE
Dashboards can be created in two ways.
First, dashboard provides a basic node, that gives four text areas. By using the PHP filter, PHP code can be placed in each area. Not all areas are required, but without left/right defined, the node is pretty pointless.
Second, modules can simply use theme_dashboard() to create custom dashboards. For many uses, this is without a doubt the most powerful way to do it, but it is not necessarily the most convenient, especially for administrators that are not the most comfortable with code.
FUNCTIONS
The module introduces two themes:
theme_dashboard($id = '', $left = '', $right = '', $top = '', $bottom = '')
theme_dashboard_component($comp = '', $title = '', $id = '')
As well as two functions designed to make creating dashboards a little easier:
dashboard_get_block($modulename, $delta, $id=''')
dashboard_get_node($nid, $teaser = FALSE, $page = FALSE, $links = TRUE, $id='')
dashboard_get_node_list($nodelist, $teaser = FALSE, $page = FALSE, $links = TRUE, $title='', $id='')
EXAMPLES
Placing Blocks in a Panel:
To put a block in a dashboard panel, you simply need to know the name of the module that provides the block, and the 'delta' of the block, which is the number. This is easy to find in the block administration page. The URL to configure any given block is: admin/block/configure/modulename/delta -- simply take those values from the URL.
Placing this code in a panel will put the Active Forum Topics and New Forum Topics blocks in one panel:
<?php
print dashboard_get_block('forum', 0);
print dashboard_get_block('forum', 1);
?>
You can also given optional $id parameter, which is simply passed through as the CSS id of the component, done so that each block can be styled individually for maximum flexibility. This is completely optional and easily ignored.
Placing Nodes in a Panel:
This one is even simpler; all you need is the NID of a node, and some information about how you want to display it. You can display the teaser, or the entire node.
<?php
print dashboard_get_node(1, TRUE, FALSE, TRUE);
?>
Like dashboard_get_block() you can also provide an optional id parameter for CSS.
Placing a list of node teasers in a panel:
The function dashboard_get_node_list() is a quick shortcut to make this a little easier. Simply pass it an array of already loaded nodes (not just NIDs). You can use this to create quick-and-easy two column teaser displays:
(Stealing the query from node_page_default() which is the query used to print the normal Drupal front page nodes)
Put this in the LEFT section:
<?php
$result = pager_query(db_rewrite_sql('SELECT n.nid, n.sticky, n.created FROM {node} n WHERE n.promote = 1 AND n.status = 1 ORDER BY n.sticky DESC, n.created DESC'), variable_get('default_nodes_main', 10));
if (db_num_rows($result)) {
$output = '';
$count = 0;
global $rightList;
while ($node = db_fetch_object($result)) {
$count++;
if ($count % 2 == 0)
$rightList[] = node_load(array('nid' => $node->nid));
else
$leftList[] = node_load(array('nid' => $node->nid));
}
}
print dashboard_get_node_list($leftList, TRUE);
?>
Put this in the RIGHT section:
<?php
print dashboard_get_node_list($rightList, TRUE);
?>
Put this in the BOTTOM section:
<?php
print theme('pager', NULL, variable_get('default_nodes_main', 10));
?>
CAVEATS: Be sure you don't have the dashboard node promoted to frontpage, or you'll get a difficult to understand situation where clicks don't seem to work, because the node tries to view itself.