INTRO TO DRUPAL MODULE INTERNALS

Greg MonroeTriangle Drupal Users Group

Aug 11, 2011

Skills and Tools

A very basic knowledge of PhP (e.g. can kinda follow the basic logic but may not be able to write it)

A decent (plain) text editor ( e.g. Notepad++, Text Edit, Gedit )

Optionally, you could find a more PhP friendly editor that displays a function list and allows for searching thru multiple file/directories. (SciTE, Geany, NotePad++ with plugins, Eclipse, Aptana, Zend…)

What we won’t cover

Finding modules

Downloading modules

Installing modules

Enabling modules

Configuring module

What will be covered

How Modules work overview Basic module file structure Finding modules The .info file The .module file Finding help in the module Finding module menu items (pages) Finding blocks a module supplies What does the module allows to be themed Finding permissions Finding views the module creates

How modules work

Core finds them via admin/build/module Stores info about them in System DB

table Enabling module sets flag in System DB

table, creates required DB tables, does initial setup and registration duties.

Main code for modules loaded at page “boot”.

Module code gets called via “hooks” by core and other modules

Module Magic happens

Some Hook Fundamentals

There are many hooks from many sources but a good starting place is:

http://api.drupal.org/api/drupal/includes--module.inc/group/hooks/6

Hooks are generally documented as hook_name, e.g. hook_menu or hook_block

Hooks implementations are basically functions that follow a specific naming format. So, for the “foo” module to implement hook_menu, it must have a function named, foo_menu.

Useful Module Splunking Hooks

Hook_help

Hook_menu

Hook_block

Hook_theme

Hook_perm

Hook_views_api

Note: You can find full documentation on hook by googling:“Drupal api hook_<name>”

Module File Structure

All module files live under a common directory, who’s name is the module “basename”. E.g., Organic group is “og”, Node Gallery uses node_gallery, CCK uses content.Note: Module base directories can exist under other modules, e.g. og_views is found in og/modules/og_views…

At a minimum, a module base directory needs two files:

<basename>.info (e.g. og.info)<basename>.module (e.g. og.module)

An Example of Module files

The Organic Group Module

Finding a Module Finding a module that is creating some page or block

from the displayed page is hard… and beyond this talk…

If you know the “Human name”, e.g. Organic Groups, you can find the base name using FireBug and the Modules page. Just inspect the enable checkbox and look at the value.

Knowing this, see if you can download it from Drupal.org. Looking at a module outside your web server is MUCH safer.

But if you think your site’s code is different or you can’t find the Drupal Project….

Where’s Wald..err..the Module

Modules can live many places… but by convention they generally live under one of three directories:

<drupal root>/modules (Core only!)<drupal root>/sites/all/modules (for all sites)<drupal root>/sites/default/modules

Note: In multisite setups, the default part above may be your host name, e.g. www.my.com

Next check to see if a basename directory exists… if not, use a file search tool to look for <basename>.info under these directories.

Module Files

Required:<basename>.info<basename>.module

Recommended:README(.txt)LICENSE(.txt)<basename>.install

Naming Conventions:

*.inc – Include files loaded

as needed

*.pages.inc – code needed

for general pages

*.admin.inc – code needed

for admin pages

*.tpl.php – Override-able theme template files

The .info file

The module.info file contains the basic description of the module.

The .Module File

The <Basename>.module file contains the core code for the module and generally all the hooks we’re interested in.

Finding Hooks

With the .module file in an editor:

If your editor show functions, just look for the _<hook name> postfix

Search for “hook_<hook name>”

Search for <basename>_<hook name>

Look for _<hook name>

Hook_Help

Notes:

Supplies text for DrupalAdvanced help system

Case statements – URL help applies to

Return statements - Help text

Hook_MenuNotes:

Defines URLs (as menuitems or just pages) for “pages” the module creates

$items[…] statements – URL of page - %xxx indicate argument substitution

‘title’ array key - Menu/Page title

‘page callback’ array key - function to create page

‘access callback’ array key - function that determines access

Hook_BlockNotes:

If ($op == list) section- Defines blocks this module adds

‘info’ array key– Name shown in block admin display

The “view” op (not shown)defines how the block contents are created

The “configure” op (not shown) defines any blockspecific configuration options

Hook_ThemeNotes:

‘<basename>_xxx’ keys - These define the theme “hooks” for this module

‘arguments’ key - Defines the values passed to the theme hook

‘template’ key - Indicates this theme hook is a .tpl.php template file

‘path’ key - The directory the tpl.php file is located.

Code for non-template hookswill be in theme_<name> functions.

Hook_Perm

Notes:

Defines the permissions thismodule uses.

Note that many modules usePhP constants to define permissions. So, look at these to get the names usedin the permission settings screens.

Hook_views_api

If you find this hook, you know that this module supports views and might be supplying blocks and pages thru views it installs.

The path option will indicate where the views related .inc files will “live”. If you look thru these you will generally find the names of views this module creates

Questions / More Info

Pro Drupal Development is the “bible”

Drupal API site has lots of docs on hook

DrupalContrib.org has lots of docs on non-core hooks

Of course Drupal.org and general search will help you find lots of good stuff.