There are several fundamentally different kinds of hooks. Some work has been done in Drupal 5 to split the different kinds of hooks into different files that don't all have to be loaded every time a page is viewed, but that's limited so far to the first group,
System Management
These hooks are used when you install and upgrade modules. They're a bit special because they go in a separate mymodule.install file, which thankfully is only loaded when you view certain administration pages -- not on every page of your site.
hook_installis called when a module is activated for the first time. It's usually used to create any database tables that the module might need. hook_uninstall is called when the module is explicitly uninstalled by the user, and is supposed to drop tables that were created and generally clean up anything the module may have created. Deactivating the module does not trigger the uninstall hook. That's the job of:hook_disable, which is run when a module is deactived. The corresponding hook_enable runs when a module is activated.hook_requirementsallows a module to abort its installation if a system requirement is not met, as well as display warnings on the administration UI if some underlying software is not the ideal version.hook_update_Nis drupal's upgrade and migration mechanism. You define code in functions starting from hook_update_1 (and increasing the number each time), and the Drupal will run each one in order when update.php is run, keeping track of which updates have already been applied)
System Configuration
hook_permreturns an array of strings. These strings represent a certain type of permission that you would like to grant certain (or all) users of your site. "edit your own blog posts" or "use the search form" might be examples. It's legal to use any string, like "09joaijdsfoijas", but it's a good idea to follow the convention that the strings are short lower-case English descriptions of a kind of activity on your site.hook_formscontains a map of form IDs to form functions, and is used by the forms API so that most calls todrupal_get_form()need one less parameter than they did before.hook_help: another database of strings that gets loaded every page view. This one adds help text to certain pages on the site.hook_xmlrpc: contains a map of what function gets called when an XMLRPC call is made to Drupal.
Extending Drupal Functionality
1. Creating Your Own Node Type
Remember that there are node types ("blog post", "forum topic", "photo") and individual node instances (a particular forum topic or a single blog post). Drupal manages for you the flow of creating, updating and deleting instances of your custom node type, calling these hooks to customize the different steps of the process.
- You declare your intention to create a new node type with
hook_node_info, which returns a list of node type names defined by the module. Generally this callback is implemented with a single return statement, returning an array with a bunch of text in it. Perhaps in the future, this hook will go away and be replaced with some text in a file that gets sucked into the database.
- You control access to your node type with
hook_access, which determines dynamically if the current user is allowed to create, delete, update, or view a given node. - You define a UI for your node with
hook_form, which defines the form used for creating and editing nodes of your type.hook_prepareis called before the form is created,hook_validateis called when the user submits the form to check for errors, andhook_submitis called after validation has succeeded. Finally,hook_viewis called when the node is displayed on a page (in certain situations). - And if you think about the base schema of the abstract node type ("creation date", "title", "author/owner", etc), and you think of your custom node type as an extention to that schema, you define the way those extentions are stored in the database with
hook_load(forSELECT),hook_insert,hook_update, andhook_delete.
2. Form Elements
You can define new form elements (like core's "checkboxes") usinghook_elements, which works in a kind of template fashion. You return an exemplar of the form element -- when you then create a form element elsewhere and include '#type' => 'mycustomelement', the form system will act as if you had been creating a form element on top of your the exemplar instead of in an empty array.3. Filters
Hooks (hook_filter) are also how you create custom filters to do things like change text smileys (=)) into graphical ones, or filter out certain malicious HTML tags, censor certain words, or any other transformation on text. hook_filter_tips is another hook which exists only to contain a bunch of text -- in this case, help text for the custom filters defined in hook_filter. 4. Custom Authentication
hook_auth and the strangely named hook_info are used to define alternative methods for authenticating a user when they log in. Although these methods are only needed when a user attempts to log in, they get included on every page view, and are good candidates for loading on-demand.
Genearating Dynamic Content
hook_menuallows you to associate functionality with URLs. If you want a page to appear athttp://example.com/some/path, you can attach a function to/some/pathusinghook_menu.hook_blockdefines a dynamic "block" which, if turned on, will by default be included on every page of your site. These pieces of content are called blocks because they often appear in the sidebars of websites
Behavioral Tweaks
These hooks modify the default runtime behavior of Drupal in various ways. Because a lot of them are meant to be dynamic, these are by far the hooks best suited best to be loaded on every page view.. just in case they're needed. These types of callbacks are where the name "hook" probably came from.hook_initandhook_exitwhich are called at the beginning and end of every page view.hook_commentis called whenever a comment is inserted, updated, viewed, published, unpublished, or deleted -- in some cases allowing you to change the comment before the action takes place. It's also called when a comment form (the UI for doing those things to comments) is presented to the user, allowing you to add to the form before the user sees it. It's also called when a comment is benig validated, allowing you to add additional form validations (probably on the form elements you just added)hook_db_rewrite_sqlis called whenever a database query is run, and is allowed to modify the query before it gets sent to the database. Generally this is used by core modules and lower-level modules like i18n. But be aware when optimizing your queries that they'll be munged before going to the database.hook_file_downloadis called when a user tries to download a file (but only if you've set up your download type to private). It has the power to deny access to the file.hook_footerinserts HTML at the bottom of the page. Not in the$footer_message, but in the$closure. The$footer_messagecontains blocks (described above).hook_nodeapiis called whenever a node (not defined by your own module) is about to be:- selected, inserted, updated, or deleted from the database
- viewed by itself on a page, in an RSS feed, in search results, or in a printable view
- indexed by the search module
or whenever a form for the node is being created, validated, or processed. (Whew!)- But if you want to set access permissions, you should use
hook_node_access_recordsandhook_node_grantsinstead hook_form_altergives you the opportunity to modify any form that's created in The Drupal Way.hook_link: every node and every comment in the system is displayed with some links (usually under it), which give the user the option to perform certain actions with that node or comment. There might be a "delete" or "edit" link if the user has permission, a "login to comment" link if the user is logged out, or maybe a "view printable version of this article" link. This link allows you to add to (but not otherwise modify) that list of links for every comment and node on the system. Altering or deleting links is available to hook_link_alter, which only can act on node links-
hook_mail_alter: gives you the chance to modify any mail being sent out using the "Drupal Way".
- hook_user: do something whenever a user is created, is updated, is pulled from the database, is deleted, logs in, logs out, registers, is viewed, etc.
Where to put these?
hook_node_operations developer/hooks/core.php Add mass node operations.hook_user_operations developer/hooks/core.php Add mass user operations.
hook_node_type developer/hooks/node.php Act on node type changes.
Cron and Other Module-Specific Functions
- hook_cron is called on every module that defines it whenever the main drupal cron job is run, which is suggested to be once an hour, but could be at any time, since the cron.php trigger mechanism is public.
- hook_ping is called from ping.module's ping_cron, but only if there's been new content since the last call.
Other Module-Specific Customization Functions
- hook_profile_alter allows some customization of profile.module's behavior.
hook_searchallows you to create a new set of content to search. (think of Google's Image vs. News vs. Web search) If you want "one search to rule them all", then the Drupal Way is to wrestle all your content into nodes, or to use hook_update_index. hook_search_item lets you change the format of search results, and hook_search_preprocess allows you to change the text that gets fed into the indexer.hook_taxonomylets you react to taxonomy changes.
