OK, you've installed that new Drupal module but the documentation is skimpy.. what now? You don't need to be a coder to suss out the secrets within if you know a little about key module internals. This TriDUG presentation was designed to help Drupal "power users" (or people aspiring to be) understand how to find information from the code (without knowing a lot of Ph). This includes things like: Menu/Page URLs, Blocks, Themable items, and the like. Note: Sorry the finding views part is skimpy in the presentation... time limitation kept me from fleshing this out more.

1. Intro To DRUPAL Module Internals Greg Monroe Triangle Drupal Users Group Aug 11, 2011

2. 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…)

3. What we won’t cover Finding modules Downloading modules Installing modules Enabling modules Configuring module

4. 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

5. 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

6. 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.

7. 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: “Drupalapi hook_<name>”

8. 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)

9. An Example of Module files The Organic Group Module

10. 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….

11. 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/modulesNote: In multisite setups, the default part above may be your host name, e.g. www.my.comNext check to see if a basename directory exists… if not, use a file search tool to look for <basename>.info under these directories.

12. 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

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

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

15. 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>

16. Hook_Help Notes: Supplies text for Drupal Advanced help system Case statements – URL help applies to Return statements - Help text

17. Hook_Menu Notes: Defines URLs (as menu items 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

18. Hook_Block Notes: 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 block specific configuration options

19. Hook_Theme Notes: ‘<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 hooks will be in theme_<name> functions.

20. Hook_Perm Notes: Defines the permissions this module uses. Note that many modules use PhP constants to define permissions. So, look at these to get the names used in the permission settings screens.

21. 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

22. 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.