Template & Form Hooks

Form hooks allow you to run a function at three times in the form's life cycle: before the data has been processed by field types, after the data has been processed and inserted into the database, and when the data has been published.

Prior to BigTree 4.2, pre-processing and post-processing hooks were referred to as "Preprocess Function" and "Callback Function". BigTree 4.2 introduces publishing hooks. Pre-processing and post-processing documentation are accurate representations of BigTree 4.0/4.1 behavior as well.

BigTree 4.3 introduces template hooks that function almost exactly the same as module form hooks but on a per-template basis. Edit, pre, and post template hooks receive the page's resource array rather than the full page array. A template's publish hook contains the full page array.

Hooks are entered as just a function name or class method (i.e. "myProcessFunction" or "MyClass::processMe").

Editing Hook

BigTree 4.2.12 and later add support for an editing hook. The editing hook is run when a user hits the form to begin editing an existing entry. The hook is expected to return a modified entry array and accepts the following parameters:

  1. entry array — The decoded row from the database.
  2. form array — The decoded form (from bigtree_module_forms, for use when you're using the same editing hook on multiple forms). If this is a template hook, the template is passed in instead.
  3. template bool — Whether this is a template or a form (true = template)

Pre-processing Hook

Your pre-processing hook should accept a single parameter which will be an array of POST data. You are expected to return an array of key/value pairs that represent the data you want changed from the POST data. You can choose to return only the key/value pairs you wish to change or you can return the whole POST data array with the values you wish to change adjusted.

You can also return key/value pairs that were not present in the POST data. This allows you to modify columns in the form's table that were not fields in the form. The key/value pairs not associated with a field will not be processed by any field type but the key must match a column name in the form's table or it will be ignored.

Post-processing Hook

Post-processing hooks take place after your data has been processed and stored. Your post-processing hook should accept three parameters:

  1. id string — This will either be a number representing the "id" column of the table row that was modified/created OR a number prefixed with a "p" (i.e. "p15") indicating that the data is stored in the bigtree_pending_changes table and has not yet been published (the numeric part being the "id" column of the entry in bigtree_pending_changes).
  2. data array — This is an array of the data that was stored in the database.
  3. published boolean — This is a boolean indicating whether a publish occurred during the submission. If a change was submitted to a previously published row, this will still equate to false but the id string will be the id column of the published row.

Post-processing hooks do not expect a return value. Though the published state is still passed into post-processing hooks in BigTree 4.2 it is recommended that you use the publishing hook if you need to have something occur on publish. Post-processing hooks will not run when a pending change is published through the Pending Changes dashboard — only publishing hooks will be.

Publishing Hook

Publishing hooks are run after a publish has taken place. This can occur when:

  • A new row is created and published via a form
  • A pending row is edited and published via a form
  • An existing row with no pending changes is edited and published via a form
  • An existing row with pending changes is edited and published via a form
  • A pending row is published via the Dashboard
  • An existing row with pending changes is published via the Dashboard
  • An item in a list view has the approved, archived, or featured state changed (in BigTree 4.2.22+)

These are the parameters your publishing hook should accept:

  1. table string — The database table that is being updated.
  2. id integer — The "id" column of the row that was created/updated.
  3. changes array — When published via the Dashboard, this is an array of the changes that were published (columns that were not changed are not included). When published via a form, this is an array of the entire form's processed data.
  4. many_to_many array — An array of many to many data that is associated with the form. (null is passed in when an item is approved, archived, or featured from a list view)
  5. tags array — An array of tags that were tagged to this row. (null is passed in when an item is approved, archived, or featured from a list view)

Because the data received is slightly different depending on whether the change was published from the dashboard or via a form, if you need the full row it is always recommended that you query for it yourself using the table/id provided.