Groking the Form API & Node API

Working out callback ordering is trickyThere are now lots of levels of callbacks to work with:

  1. Old node hooks (hook_load, hook_form, etc)
  2. nodeapi hooks - based on $op, they all happen after the corresponding node hook
  3. hook_form_alter - replaces old hook_nodeapi:form call
  4. Validate and Submit callbacks set up in form with FormAPI - So there are now potentially 3 different places to do validation

Some ordering:

  1. _load
    • inputs: &$node, but ignore it - nothing useful in it yet, and any changes are rejected.  Pull data from db.
    • outputs: object(hash) that will get merged with node.
    • goal: move data from db into node
    • ? why not just allow you to modifiy $node?
  2. _prepare
    • inputs: &$node with info from _load.  Pull data from $_POST and $_SESSION
    • outputs: changes to $node persist down chain.
    • goal: make changes to $node based on non-submit actions
  3. _form (does not go to _nodeapi, now use _form_alter)
    • inputs: &$node - now fully loaded with $_POST['edit'] array (and data from _load and _prepare)
    • outputs: returns the bad-ass form array. Can modify $node, but that would be odd(?)
    • goal: build the form array
  4. _validate
    • inputs: $node: filled with all form_values(RO), $form: form array
    • outputs:
      changes to $node are lost, and changes to $form are pointless.  Use
      form_set_value( $form['id'], new_value ) to modify the values in $node
      before submission (weird). Use form_set_error( 'id', 'message' ) to
      abort the submission.
    • goal: change to reject the form submission.
    • ? why make it so hard to modify $node, but still possible ?
  5. _submit
    • inputs: &$node with all the trimmings
    • outputs: modificatons to $node persist
    • goal: last chance for tweaking before heading to the db(?) Mostly for _form_alter chaining
  6. _update/insert
    • inputs: $node (RO)
    • outputs: updated db tables
    • goal:
      persist extra node info to the db.  Called after node_u/i.  If this is
      an insert, this is the first moment you have a nid (important if you
      are doing bonus db changes that need to link back to this node).