Installing a Module
We have a working module. Now we need to install it. This is typically done in three steps:
- Copying the module to the correct location
- Enabling the module
- Configuring Drupal to display the module's content
Note
Some of the contributed modules for Drupal require additional setup steps. Such steps are documented by the module's authors. In Chapter 4, we will create a module that requires a few additional steps before the module is useful.
We will walk through each of these three steps.
Step 1: Copying the Module
Modules in Drupal are stored in one of the three places under Drupal's root directory:
modules/:This is the directory for core modules. Only modules supplied as part of the Drupal distribution should be stored here. None of our modules will ever be located here.sites/all/modules/:This is the directory for modules that should be available to all of the sites hosted on this Drupal installation. Usually, this is where you want to put your module.sites/<site name>/modules:Drupal can host multiple sites. Each site has a directory inside thesites/folder. For example, the default site is located insites/default/. If you want to install site-specific modules on an instance of Drupal that runs multiple sites, the modules should go into thesites/<site name>/modules/directory, where<site name>should be replaced by the correct site name.
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.
Note
UNIX and Linux users: Don't move it; link it!
If you are actively developing a module, sometimes it is more convenient to create a symbolic link to the module directory instead of moving or copying the directory: ln -s /home/mbutcher/modules/goodreads /var/www/drupal/sites/all/modules/goodreads
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.