? hook-to-functor.diff
? hook-to-functor_2.diff
? hook-to-method.diff
? hook-to-nook.diff
Index: node.php
===================================================================
RCS file: /cvs/drupal-contrib/contributions/docs/developer/hooks/node.php,v
retrieving revision 1.35
diff -u -p -r1.35 node.php
--- node.php	29 Dec 2006 19:36:39 -0000	1.35
+++ node.php	6 Jan 2007 12:32:12 -0000
@@ -3,13 +3,21 @@
 
 /**
  * @file
- * These hooks are defined by node modules, modules that define a new kind
- * of node.
+ * These hooks are defined by modules that act on nodes, with some used only by 
+ * modules that define a new type of node. A subset of these hooks have the name
+ * placeholder "method_" instead of "hook_" to distinguish the node-type-
+ * specific hooks from the other node hooks. Those function templates with the 
+ * "method_"  placeholder represent callbacks that are specific to a single 
+ * node type.  For example, when the 'forum' node type is loaded, the 
+ * corresponding method_load() is forum_load().  This is the only
+ * method_load() that is called.  In contrast, when the 'forum' type is loaded,
+ * hook_nodeapi() is called for each and every module that implements it.
  *
  * If you don't need to make a new node type but rather extend the existing
- * ones, you should instead investigate using hook_nodeapi().
+ * ones, you should be using hook_nodeapi().
  *
- * Node hooks are typically called by node.module using node_invoke().
+ * Node hooks with a "method_" name are typically called by node.module using 
+ * node_invoke().
  */
 
 /**
@@ -35,7 +43,7 @@
  *   sub-array for each node type, with the machine-readable type name as the
  *   key. Each sub-array has up to 10 attributes. Possible attributes:
  *   - "name": the human-readable name of the node type. Required.
- *   - "module": a string telling Drupal how a module's functions map to hooks
+ *   - "module": a string telling Drupal how the node type's methods are named
  *      (i.e. if module is defined as example_foo, then example_foo_insert will
  *      be called when inserting a node of that type). This string is usually
  *      the name of the module in question, but not always. Required.
@@ -79,7 +87,7 @@ function hook_node_info() {
 /**
  * Act on node type changes.
  *
- * This hook allows modules to take action when a node type is modified.
+ * This hook allows any module to take action when any node type is modified.
  *
  * @param $op
  *   What is being done to $info. Possible values:
@@ -110,7 +118,7 @@ function hook_node_type($op, $info) {
 /**
  * Define access restrictions.
  *
- * This hook allows node modules to limit access to the node types they
+ * This method allows node modules to limit access to the node types they
  * define.
  *
  * @param $op
@@ -127,8 +135,8 @@ function hook_node_type($op, $info) {
  *   returned; NULL to not override the settings in the node_access table.
  *
  * The administrative account (user ID #1) always passes any access check,
- * so this hook is not called in that case. If this hook is not defined for
- * a node type, all access checks will fail, so only the administrator will
+ * so this method is not called in that case. If this method is not defined
+ * for a node type, all access checks will fail, so only the administrator will
  * be able to see content of that type. However, users with the "administer
  * nodes" permission may always view and edit content through the
  * administrative interface.
@@ -137,7 +145,7 @@ function hook_node_type($op, $info) {
  *
  * @ingroup node_access
  */
-function hook_access($op, $node) {
+function method_access($op, $node) {
   global $user;
 
   if ($op == 'create') {
@@ -155,8 +163,8 @@ function hook_access($op, $node) {
  * Respond to node deletion.
  *
  * This is a hook used by node modules. It is called to allow the module
- * to take action when a node is being deleted from the database by, for
- * example, deleting information from related tables.
+ * to take action when a node of a specific type is being deleted from the
+ * database by, for example, deleting information from related tables.
  *
  * @param &$node
  *   The node being deleted.
@@ -168,7 +176,7 @@ function hook_access($op, $node) {
  *
  * For a detailed usage example, see node_example.module.
  */
-function hook_delete(&$node) {
+function method_delete(&$node) {
   db_query('DELETE FROM {mytable} WHERE nid = %d', $node->nid);
 }
 
@@ -177,7 +185,7 @@ function hook_delete(&$node) {
  * succeeded and before insert/update. It is used to for actions which must
  * happen only if the node is to be saved. Usually, $node is changed in some
  * way and then the actual saving of that change is left for the insert/update
- * hooks.
+ * methods.
  *
  * @param &$node
  *   The node being saved.
@@ -186,7 +194,7 @@ function hook_delete(&$node) {
  *
  * For a detailed usage example, see fileupload.module.
  */
-function hook_submit(&$node) {
+function method_submit(&$node) {
   // if a file was uploaded, move it to the files directory
   if ($file = file_check_upload('file')) {
     $node->file = file_save_upload($file, file_directory_path(), false);
@@ -194,8 +202,8 @@ function hook_submit(&$node) {
 }
 
 /**
- * This is a hook used by node modules. It is called after load but before the
- * node is shown on the add/edit form.
+ * This is a method used by node modules. It is called after load but before
+ * the node is shown on the add/edit form.
  *
  * @param &$node
  *   The node being saved.
@@ -204,7 +212,7 @@ function hook_submit(&$node) {
  *
  * For a usage example, see image.module.
  */
-function hook_prepare(&$node) {
+function method_prepare(&$node) {
   if ($file = file_check_upload($field_name)) {
     $file = file_save_upload($field_name, _image_filename($file->filename, NULL, TRUE));
     if ($file) {
@@ -227,26 +235,27 @@ function hook_prepare(&$node) {
  * Display a node editing form.
  *
  * This hook, implemented by node modules, is called to retrieve the form
- * that is displayed when one attempts to "create/edit" an item. This form is
- * displayed at the URI http://www.example.com/?q=node/<add|edit>/nodetype.
+ * that is displayed when one attempts to "create/edit" a specific node type. 
+ * This form is displayed at the URI 
+ * http://www.example.com/?q=node/<add|edit>/nodetype.
  *
  * @param &$node
  *   The node being added or edited.
  * @param &$param
- *   The hook can set this variable to an associative array of attributes
+ *   The method can set this variable to an associative array of attributes
  *   to add to the enclosing \<form\> tag.
  * @return
  *   An array containing the form elements to be displayed in the node
  *   edit form.
  *
  * The submit and preview buttons, taxonomy controls, and administrative
- * accoutrements are displayed automatically by node.module. This hook
+ * accoutrements are displayed automatically by node.module. This method
  * needs to return the node title, the body text area, and fields
  * specific to the node type.
  *
  * For a detailed usage example, see node_example.module.
  */
-function hook_form(&$node, &$param) {
+function method_form(&$node, &$param) {
   $type = node_get_types('type', $node);
 
   $form['title'] = array(
@@ -285,8 +294,8 @@ function hook_form(&$node, &$param) {
  * Respond to node insertion.
  *
  * This is a hook used by node modules. It is called to allow the module
- * to take action when a new node is being inserted in the database by,
- * for example, inserting information into related tables.
+ * to take action when a new of a specifc type node is being inserted in the 
+ * database by, for example, inserting information into related tables.
  *
  * @param $node
  *   The node being inserted.
@@ -298,7 +307,7 @@ function hook_form(&$node, &$param) {
  *
  * For a detailed usage example, see node_example.module.
  */
-function hook_insert($node) {
+function method_insert($node) {
   db_query("INSERT INTO {mytable} (nid, extra)
     VALUES (%d, '%s')", $node->nid, $node->extra);
 }
@@ -323,7 +332,7 @@ function hook_insert($node) {
  *
  * For a detailed usage example, see node_example.module.
  */
-function hook_load($node) {
+function method_load($node) {
   $additions = db_fetch_object(db_query('SELECT * FROM {mytable} WHERE nid = %s', $node->nid));
   return $additions;
 }
@@ -332,8 +341,8 @@ function hook_load($node) {
  * Respond to node updating.
  *
  * This is a hook used by node modules. It is called to allow the module
- * to take action when an edited node is being updated in the database by,
- * for example, updating information in related tables.
+ * to take action when an edited node of a specific type is being updated in the
+ * database by, for example, updating information in related tables.
  *
  * @param $node
  *   The node being updated.
@@ -345,7 +354,7 @@ function hook_load($node) {
  *
  * For a detailed usage example, see node_example.module.
  */
-function hook_update($node) {
+function method_update($node) {
   db_query("UPDATE {mytable} SET extra = '%s' WHERE nid = %d",
     $node->extra, $node->nid);
 }
@@ -363,15 +372,15 @@ function hook_update($node) {
  * To validate nodes of all types (not just nodes of the type(s) defined by
  * this module), use hook_nodeapi() instead.
  *
- * Since Drupal 4.7, changes made to a node within hook_validate()
+ * Since Drupal 4.7, changes made to a node within method_validate()
  * will be ignored.  The preferred method change a node's content is to 
- * use hook_submit() or hook_nodeapi($op='submit') instead.  If it is really
+ * use method_submit() or hook_nodeapi($op='submit') instead.  If it is really
  * necessary to change the node at the validate stage, you can use function
  * form_set_value().
  *
  * For a detailed usage example, see node_example.module.
  */
-function hook_validate($node) {
+function method_validate($node) {
   if (isset($node->end) && isset($node->start)) {
     if ($node->start > $node->end) {
       form_set_error('time', t('An event may not end before it starts.'));
@@ -410,7 +419,7 @@ function hook_validate($node) {
  *
  * For a detailed usage example, see node_example.module.
  */
-function hook_view($node, $teaser = FALSE, $page = FALSE) {
+function method_view($node, $teaser = FALSE, $page = FALSE) {
   if ($page) {
     $breadcrumb = array();
     $breadcrumb[] = array('path' => 'example', 'title' => t('example'));