Creating blocks and pages

by Gisle Hannemyr

This chapter describes how to create blocks and pages in Drupal 7 using code.

Introduction
The “Hello world” block
The “Hello world” page
Final word

Introduction

Previous chapters in this ebook has described how to create content using the Drupal 7 GUI, and how to create custom content types in the GUI using fields.

In this chapter you will describe how to create content without using the GUI. It will demonstrate how to create a block and the page with some minimal content.

The “Hello world” block

To create a block, you use two functions provided by the Drupal 7 API:

hook_block_info: Define all blocks provided by the module.
hook_block_view: Return a rendered or renderable view of a block.

First declare what blocks are provided by the module. It this case, only a single block is declared. The string helloworld is a unique identifier (within the module) that will identify the block. This code will go into a custom module with the short name mymodule.

/**
 * Implements of hook_block_info()
 */
function mymodule_block_info() {
  $blocks = array();
  $blocks['helloworld'] = array(
   'info' => t('Hello world'),
  );
  // Add more blocks here.
  return $blocks;
}

Below is a minimal hook_block_view(). The delta parameter is used to identify the block. The hook is expected to retun an array with two elements:

subject: The title of the block as plain text wrapped in t() for localisation.
content: The render array of the block's content (preferred), but it may also be a HTML string.

/**
 * Implements of hook_block_view()
 */
function mymodule_block_view($delta = '') {
  switch ($delta) {
    case 'helloworld':
      $blocks['subject'] = t('Hello world');
      $blocks['content']['raw_markup'] = array(
        '#markup' => '<p>Some contents</p>',
      );
      break;
    // Add more deltas here.
  }
  return $blocks;
}

If you place these two hooks inside mymodule.module, and provide the following in mymodule.info, you should have a working module to create this minimal block.

name = mymodule
description = Create a minimal block
core = 7.x

After creating a module with these two hooks, the block shall be available (after clearing the cache). To insert it into a region on the website, visit Structure » blocks and locate the block named “Hello world”.

In the above example, the render array that is assigned to content contains a single render element that is just some simple markup.

A render array is an associative array containing properties that the theme system will use when rendering it as HTML. Render arrays separates content from its presentation add another layer of flexibility to Drupal. By altering the render array developers and themers may alter the page content and layout without having to parse the presentation.

See also To learn more about Drupal 7 render elements, you may visit the Newsignature.com blog.

The “Hello world” page

To create a custom page programmatically, you need to provide a custom path to make it accessible to users. This is done in a custom module by implementing hook_menu() and make it return an associative array with the menu router as index to title, page callback and access agruments.

Here is how a minimal hook_menu() may look like in a module with the short name mymodule:

/**
 * Implements hook_menu().
 */
function mymodule_menu() {
  $items['helloworld'] = array(
    'title' => 'Hello world',
    'page callback' => 'mymodule_custom',
    'access callback' => TRUE, 
  );
  return $items;
}

note Drupal requires the short names of modules to be unique. If you've already created a module with the short name “mymodule”, as suggested in the previous section, you need a pick a different short name for this module.

This hook registers a path helloworld. The page title is set to “Hello world“, which will be used as the title when viewing the page and used as link text for the menu item. A callback function called mymodule_custom() is registered. This will be created later to provide the actual content. And finally, access callback is set to TRUE. This means that anyone will be able to view the custom page. Using TRUE instead of a real access callback function is not recommended, but used here for demonstration purposes.

The next step is to add the callback function. This is the function that actually populates the page with a render array.

/**
 * Menu callback, return render array for page.
 */
function mymodule_custom() {
  $content['raw_markup'] = array(
    '#markup' => '<p>Hello world</p>',
  );
  return $content;
}

The render array for the page content is the same a used above for the block.

If you place these two functions inside mymodule.module, and provide the following in mymodule.info, you should have a working module to create this minimal page.

name = mymodule
description = Create a minimal page at a specified path
core = 7.x

To test, install the module and clear the cache. Provide the site's top URL is example.com, to visit the custom page, go to the URL http://example.com/helloworld.

Final word

This chapter described how you may create blocks and pages programatically, rather than by using the GUI. Drupal also let developers create forms programatically. This is discussed in the chapters about the Form API, and in a case study of the ctools forms Wizard.

Last update: 2019-01-26 [gh].

Creating blocks and pages

Table of contents

Introduction

The “Hello world” block

The “Hello world” page

Final word