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").
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:
- entry array — The decoded row from the database.
- 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.
- template bool — Whether this is a template or a form (true = template)
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 hooks take place after your data has been processed and stored. Your post-processing hook should accept three parameters:
- 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).
- data array — This is an array of the data that was stored in the database.
- 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 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:
- table string — The database table that is being updated.
- id integer — The "id" column of the row that was created/updated.
- 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.
- 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)
- 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.