Theming a Module [ 102 ] if (is_array($elements['#items'][$key]['data'])) { $elements['#items'][$key]['data'] = drupal_render($elements['#items'][$key]['data']); } } return $elements; } In our single_blog_item_list_child_render() function, we simply loop through all the #items, determine if they have an array in their data element and call drupal_render() on its contents. Attaching CSS to render arrays If you look at the screenshot of the rst version, you can see that the default styling of our block is less then inspiring, so let's tweak that by giving our content some sensible default styling by adding a CSS stylesheet. Since version 5, Drupal has had a drupal_add_css() function to add CSS stylesheets to pages. What's new in Drupal 7 is that, due to Drupal's block and page caching and the capabilities of hook_page_alter(), we now need to attach our stylesheet directly to the render element that we are creating. If we were to use drupal_add_css(), the stylesheet would not be cached with its block and it would also be considerably more difcult to alter the stylesheet if a hook_page_alter() implementation desired to (For example if it removed the block and wanted to remove the CSS too.) So instead of calling drupal_add_css() from within our single_blog_block_view() function, we add it to the returned render array: // Add a CSS file to style the block. $block['content']['#attached']['css'][] = drupal_get_path('module', 'single_blog') . '/single-blog.css'; We use drupal_get_path() to nd the path to our module relative to the website root. The #attached array can contain a list of CSS les and JS les to attach to our render element. For JavaScript les, just append them to the js array via ['#attached']['js'][]. And here are the contents of our single-blog.css stylesheet: /* $Id$ */ .block-single-blog .content ul { padding-left: 0; /* LTR */ } Chapter 4 [ 103 ] .block-single-blog .content ul li { margin-bottom: 10px; list-style-type: none; } RTL languages One thing you'll need to be aware of when writing stylesheets is Drupal's support for RTL languages, those languages that are read Right To Left, for example Arabic or Hebrew. Users of RTL websites expect everything about that website to ow right- to-left instead of English's normal left-to-right. The convention used by websites that support both RTL and LTR languages is to ip the layout of the design horizontally depending on the directionality of the language. A great live example of how right-to-left website layouts are ipped is Amnesty International's website; compare the Arabic language version at http://www. amnesty.org/ar with the English language version at http://www.amnesty.org/en. Notice how the sidebar changes sides depending on the language: From a CSS standpoint, this means HTML elements whose left-side styling differs from their right-side styling need to have their styling altered when the current language is RTL. If a RTL language is being displayed, Drupal will, for each stylesheet, look for a supplemental RTL stylesheet to load. So, if Hebrew is the active language, Drupal will look for single-blog-rtl.css to load in addition to (and just after) the requested single-blog.css le. Since our -rtl stylesheet is loaded in addition to the standard stylesheet, we simply need to include the rules and properties needed to override the LTR version of our styles. To make it easier to keep track of those properties, Drupal modules should place a /* LTR */ comment next to each property that needs to be overridden. Theming a Module [ 104 ] Notice that the .block-single-blog .content ul rule in the single-blog.css stylesheet species a left padding. Since that's the only property that is directional, it's the only one we need to override in the single-blog-rtl.css le. /* $Id$ */ .block-single-blog .content ul { padding-right: 0; } Note that if our original left padding was 10px, we would have needed to override that in our RTL stylesheet by setting padding-left to 0 and then setting padding-right to 10px. The following is a screenshot of version two of our module block: If you look at the screenshot, you can see the new More link and how the display of our block has improved. Chapter 4 [ 105 ] After all these modications, the second draft of our single_blog_block_view() function is now complete and should look like this: /** * Implements hook_block_view(). * * Second draft! * * @pararm $delta * The name of the requested block. */ function single_blog_block_view($delta = '') { // Create an empty block. $block = array( 'subject' => '', 'content' => '', ); // Check which block is being requested. if ($delta == 'recent') { // Set the block title. $block['subject'] = t('Recent blog posts'); // Check if the user can access content. if (user_access('access content')) { // Retrieve the most recent nodes. $result = single_blog_list(SINGLE_BLOG_LIST_COUNT); // Create links for each blog entry. $items = array(); foreach ($result as $node) { $items[] = array( 'data' => array( '#type' => 'link', '#title' => $node->title, '#href' => 'node/' . $node->nid, ), 'class' => array('node-' . $node->nid), ); } if (!empty($items)) { // Theme the list of blog entries. Theming a Module [ 106 ] $block['content']['list'] = array( '#theme' => 'item_list__single_blog', '#items' => $items, '#pre_render' => array('single_blog_item_list_child_render'), ); // Add a link to the full list of blog entries. $block['content']['more'] = array( '#theme' => 'more_link', '#url' => 'blog', '#title' => t('Read the latest blog entries.'), ); // Add a CSS file to style the block. $block['content']['#attached']['css'][] = drupal_get_path('module', 'single_blog') . '/single-blog.css'; } } } return $block; } Steps to build a default theme implementation Okay, now it's time to exorcise our lazy-developer habit and practice building our own theme hook. From Chapter 3, you should recall that we'll need to do the following things: 1. Register the theme hook and dene default variables. 2. Build the default implementation of our theme hook. 3. Re-build the theme registry. 4. Build a render element to use the theme hook. Our current implementation of the Recent blog posts block simply shows a list of blog titles. But it would be nice to include the date of each post, as well as the author (if we have multiple people creating posts). So in this third and nal version of our module, we're going to create a single-blog-block-item.tpl.php to render the contents of each item in our list of blog posts. By convention in Drupal, any CSS, JavaScript, or template les needed by a module should use dashes instead of underscores in their lenames. Chapter 4 [ 107 ] Before we begin building the required single_blog_block_item theme hook, let's rst add all the data we will need for the third version of our module. Looking back at how we generate the items for our list, we can see that all the data we want is in the $node variable. // Create links for each blog entry. $items = array(); foreach ($result as $node) { $items[] = array( 'data' => array( '#type' => 'link', '#title' => $node->title, '#href' => 'node/' . $node->nid, ), 'class' => array('node-' . $node->nid), ); } So, instead of creating a simple render element using bits of the $node variable, let's just pass that entire variable to our new theme hook: // Create links for each blog entry. $items = array(); foreach ($result as $node) { $items[] = array( 'data' => array( '#theme' => 'single_blog_block_item', '#node' => $node, ), 'class' => array('node-' . $node->nid), ); } hook_theme() implementations We'll need to create a single_blog_theme() implementation of hook_theme() and register a single_blog_block_item theme hook. /** * Implements hook_theme(). */ function single_blog_theme($existing, $type, $theme, $path) { return array( 'single_blog_block_item' => array( Theming a Module [ 108 ] 'variables' => array( 'node' => NULL, ), 'template' => 'single-blog-block-item', ), ); } I'll explain the variables array in the very next section, but let's quickly go over the other key now. Since this is a theme hook, and is to be implemented using a template instead of a theme function, we'll need to include the template key and specify the base name of the template le, single-blog-block-item. Drupal will automatically add the .tpl.php to the end of the base name when looking for the le, so we shouldn't include it. Variables versus render element In Chapter 3, we learned about the differences between using the variables key and using the render element key in your hook_theme(). One and only one of those keys must be present in each theme hook declaration. However it still can be somewhat confusing as to which to use when you are building your theme implementation. There is only one situation in which you could use the render element key: if your data could be represented by a single render element or by a single renderable array containing nested render elements. If that is not the case, then you must specify the variables key and specify the variables you will be passed to theme() and their default values. So does our data conform to the render element requirement above? Our $node variable is just a partial node object and not a render element, so we must use the variables key and specify the default values for all our variables. As a side note, if we instead look at the way we've built the data element in the second version of our module (a link #type render element), we can see that we could go ahead and use render element as the key if our second version of the module had a hook_theme() implementation. Since the node variable is an object, we set the default value to simply be the NULL value. Chapter 4 [ 109 ] Preprocess functions Our theme hook is now given a $node object, but template les expect variables containing strings or render elements. So we're going to need to transform the $node object's data into a series of variables. Technically, we could have performed this business logic directly inside our single_blog_block_view() function, but instead we're going to do this transformation in a preprocess function. That's actually the purpose of the preprocess function: to transform raw data into variables needed for a theme hook's template or theme function. (Also, recall that preprocess functions should never query for raw data; the raw data should be passed as variables.) Since we own this theme hook, we'll need to dene our preprocess function with a template_ prex. /** * Preprocesses single blog block item variables. */ function template_preprocess_single_blog_block_item(&$variables) { $node = $variables['node']; To make it easier to access all the object properties of our node variable, we're going to rst create a $node local variable which we'll use inside the preprocess function: // Create a renderable array for the title. $variables['title'] = array( '#type' => 'link', '#title' => $node->title, '#href' => 'node/' . $node->nid, ); Next we'll create the $title variable as a render element; it is identical to what we saw in the second version of our module: // Format the creation date of the node. $variables['created'] = $node->created; $variables['date'] = format_date($node->created, 'custom', 'F d, Y'); Date timestamps don't make very good render elements, so we'll just create two variables, one with the raw, unformatted date value and one with formatted date: // Load the account object with the node's creator and store // in a variable for themer convenience. $variables['user'] = user_load($node->uid); Theming a Module [ 110 ] // Theme the username. $variables['name'] = theme('username', array( 'account' => $variables['user'])); } And nally, we'll pass the $user object of the author and theme the username. All that's left is to order the variables the way we desire in our template le! However, since we've made the last change to our .module le, let's look at the nished product: <?php // $Id$ /** * @file * Enables a single blog for an individual or multiple users. */ // After you learn Form API in Chapter 5, you'll be able to // make these settings configurable. define('SINGLE_BLOG_NODE_TYPE', 'article'); define('SINGLE_BLOG_LIST_COUNT', 5); define('SINGLE_BLOG_DATE_FORMAT', 'F d, Y'); /** * Returns a list of blog entries. * * @param $number * The number of blog entries to return. * @return * A result set object containing the list of blog entries. */ function single_blog_list($number) { // Use the Database API to retrieve our data. // @see http://drupal.org/node/310069 $query = db_select('node', 'n') ->fields('n', array('nid', 'title', 'created', 'uid')) ->condition('type', SINGLE_BLOG_NODE_TYPE) ->condition('status', 1) ->orderBy('created', 'DESC') ->range(0, $number) ->addTag('node_access') ->execute(); Chapter 4 [ 111 ] return $query; } /** * Implements hook_block_info(). */ function single_blog_block_info() { $blocks = array(); // The array key defines the $delta parameter used in all // other block hooks. $blocks['recent'] = array( // The name of the block on the blocks administration page. 'info' => t('Recent blog posts'), ); return $blocks; } /** * Implements hook_block_view(). * * Third draft! * * @pararm $delta * The name of the requested block. */ function single_blog_block_view($delta = '') { // Create an empty block. $block = array( 'subject' => '', 'content' => '', ); // Check which block is being requested. if ($delta == 'recent') { // Set the block title. $block['subject'] = t('Recent blog posts'); // Check if the user can access content. if (user_access('access content')) { // Retrieve the most recent nodes. $result = single_blog_list(SINGLE_BLOG_LIST_COUNT); [...]... http://api .drupal. org/api /drupal/ developer topics forms_api html /7 • Form API Full Reference: http://api .drupal. org/api /drupal/ developer topics forms_api_ reference.html /7 Using drupal_ get_form() In our first menu implementation seen earlier, we defined the page callback as drupal_ get_form() This Form API function returns a structured array that represents an HTML form This gets rendered by Drupal and... the sites/default/modules directory in our Drupal installation We can then create a user_warn.info file as shown in the following: ;$Id$ name = User Warn description = Exposes an admin interface to send behavior warning e-mails to users core = 7. x package = Drupal 7 Development files[] = user_warn .module You should be pretty familiar with this now We will also create our user_warn module file and add... interfaces for your module So while the Single Blog module used slightly-funky constants that defined some hard-coded settings, the module in the next chapter will have a rich administrative interface to allow site admins to configure its settings [ 118 ] Building an Admin Interface In this chapter we will create a module with an administrative interface This module will build upon many of the module creation... central gatekeepers of Drupal security Drupal module developers can map paths to Drupal functions by implementing hook_menu(), which adds paths to the menu system, assigns them access rules, and optionally creates navigational elements for them Defining a page callback with hook_menu For our module we will need to implement two new pages—a configuration page for the User Warn module, and a tab in the... site administration it must begin with admin This places it into Drupal' s administrative interface and applies the admin theme defined by the site settings Module- specific settings should always be present under admin/config Drupal 7 offers several categories which module developers should use to better organize their settings according to Drupal functional groups like People and Permissions or Content... chapter are: • Mapping Drupal functions to menu items using hook_menu() • Creating basic forms with the Form API • Managing Drupal settings using variable_set() and variable_get() • Sending mail using drupal_ mail() and hook_mail() • Using Drupal 7' s new token system After this chapter is finished you should have a good handle on many concepts that are at the core of almost every module you will write... changed in Drupal 7 in order to allow more flexibility in theming and easier form manipulation drupal_ get_form() now returns an unrendered form array which must be passed to drupal_ render() for final output In the preceding example the menu system handles the change transparently, but other code converted from Drupal 6 may need to be changed Building a form callback function For the User Warn module we... saved successfully Our needs for validation are handled by Drupal' s built-in form validation, so we don't even need a validate function for this data The function drupal_ set_message() sets a simple message that is displayed in a specific area at the top of a Drupal page For more details see http://api .drupal. org/api/function /drupal_ set_message /7 After a form is submitted, it will reload the form submission... details, developers should check out the API documentation at: http://api .drupal. org/api/function/hook_menu /7 The example is as follows: /** * Implement hook_menu() */ function user_warn_menu() { $items = array(); $items['admin/config/people/user_warn'] = array( 'title' => 'User Warn', 'description' => 'Configuration for the User Warn module. ', 'page callback' => 'drupal_ get_form', 'page arguments' => array('user_warn_form'),... be prefaced by the name of your module followed by an underscore, in order to prevent name collision [ 1 27 ] Building an Admin Interface Other parameters can be passed into drupal_ get_form() in addition to the form ID These extra parameters simply get passed through to the callback function for its own use We will see how this works later in the chapter In Drupal 6, drupal_ get_form() returned a fully . e-mails to users. core = 7. x package = Drupal 7 Development files[] = user_warn .module You should be pretty familiar with this now. We will also create our user_warn. module le and add an implementation. a CSS stylesheet. Since version 5, Drupal has had a drupal_ add_css() function to add CSS stylesheets to pages. What's new in Drupal 7 is that, due to Drupal& apos;s block and page caching. to keep track of those properties, Drupal modules should place a /* LTR */ comment next to each property that needs to be overridden. Theming a Module [ 1 04 ] Notice that the .block-single-blog