Step 1: Copying the Module

Modules in Drupal are stored in one of the three places under Drupal's root directory:

In this book, we will be storing our modules under the sites/all/ modules/ directory.

However, this directory is not created by default, so we will need to create it by hand.

On my Linux server, Drupal is installed in /var/www/drupal/. (Yours may be somewhere else.) All of the file system paths will be relative to this directory. We will add the appropriate subdirectory inside the sites/all/ directory:

In this example, we change into the appropriate directory, create the new modules/ directory.

On Windows, the same can be done through Windows explorer, and the same goes for Mac and Finder. Simply locate your Drupal installation directory, navigate down to sites\all, and create a new folder named modules.

Next, we need to copy our module into this directory.

Now we have our module in a location where Drupal expects to find modules.

Copying the module to the correct location is all we need to do for Drupal to recognize the module, but new modules are disabled by default. We will need to log in to the web interface and enable the module.

Step 2: Enabling the Module

A module is enabled through the Drupal Administration interface. Once logged into Drupal, navigate to Administer | Site Building | Modules in the left-hand navigation.

This page lists all the modules, beginning with the core modules (those installed by default). At the very bottom of this page is the list of third-party modules. Our module will appear in that list.

To activate the module, simply check the box under the Enabled heading, and then click the Save configuration button.

Next, we need to configure the module to display on our site.

Step 3: Displaying the Module's Content

The module we have created is a block module. Typically, blocks are displayed in specifically defined locations on the screen. What we want to do now is tell Drupal where to display our block content.

Just as with enabling the module, this is done through the administration interface. Go to Administer | Site Building | Blocks to configure block placement.

This tools allows us to configure the details of how blocks appear on the site. In fact, the site uses the templates that a site visitor would see. You can see how the site looks as you configure it.

At the bottom of this page is the block configuration tool—lists of modules along with page placement parameters. We will configure our goodreads module to appear in the right sidebar.

If all goes well, then our goodreads module should display in the right sidebar. Make sure to press the Save Blocks button at the bottom. Otherwise the block's new location will not be saved.

When the block's new location is saved, it will be displayed in the right-hand column on all of our pages.

What is the content in this module? What we see in the above screenshot are the fields returned when Drupal's module manager calls the hook_block() function of our module with something equivalent to this:

goodreads_block('view');

This will return the $blocks array, whose contents look like this:

array(
'subject' => 'On the Bookshelf',
'content' => 'Temporary content'
)

The subject value is used as the block's title, and the content item is used as the block's content.

Our module is installed. But it is doing very little. Next, we will add some sophistication to our module.