Core callbacks reference

This comprehensive reference provides detailed information about all callbacks used in Textpattern, including their events and steps.

On this page:

Public-side callbacks

These all trigger at various points during the rendering of publicly viewable content served by Textpattern. Use them to inject content - JavaScript, CSS or HTML - into the page or to alter various facets of visitor interaction with the site. They have events, but no steps.

publish.php

The callbacks in this section all deal with the web page content itself.

pretext

  • When it occurs: At the very top of the pretext() function, just after the prefs have been extracted.
  • What it allows: Injection/alteration of variables in the prefs array or to set up anything that affects the whole page.

pretext_end

  • When it occurs: Just after pretext() has run but before its variables have been extracted into the global scope.
  • What it allows: Altering anything set in pretext() or adding variables to it.

file_download

  • When it occurs: As soon as a file_download is detected.
  • What it does: Intercepts the regular file downloading process.

textpattern

  • When it occurs: Just before the page is rendered.

textpattern_end

  • When it occurs: Once the page has been fully rendered.
  • What it allows: Replacement of content in the output buffer via search/replace.

publish/atom.php

If you wish to alter atom feeds, these callbacks will help.

atom_head

  • When it occurs: After the feed’s header has been set.
  • What it allows: Adding items to the Atom feed’s header.

atom_entry

  • When it occurs: As soon as the article’s data has been populated.
  • What it allows: Injection of extra markup after the standard Atom feed items have been generated.

publish/rss.php

If you wish to alter rss feeds, these callbacks will help.

rss_head

  • When it occurs: After the feed’s header has been set.
  • What it allows: Adding items to the RSS feed’s header.

rss_entry

  • When it occurs: As soon as the article’s data has been populated.
  • What it allows: Injection of extra markup after the standard RSS feed items have been generated.

publish/comment.php

Any time a comment form is rendered or a comment is posted on an article, the following callbacks fire, so use them to intercept or alter comment layout/payloads.

comment.form

  • When it occurs: At the end of the commentForm() function.
  • What it allows: Injection of markup after the textarea generated by the <txp:comment_message_input /> tag.

comment.save

  • When it occurs: Just before a comment is posted.
  • What it allows: Additional decisions to be made, based on the comment content (e.g. for anti-spam plugins).

comment.saved

  • When it occurs: Just after a comment is posted to the database.
  • What it allows: Additional processing that might affect other related tables. Argument #3 is an array of name-value pairs containing the message text, name, email, web, parentid, commentid, ip, and visible status of the posted comment.

publish/log.php

As long as Logging is switched on from the Preferences panel, whenever a visitor requests a web page from Textpattern, a hit is registered. Use the callback here to intercept it.

log_hit

  • When it occurs: Just before a log message is recorded in the ‘txp_log’ table.
  • What it allows: Alteration of the log message.

Admin-side callbacks

Admin-side callbacks are split into three flavours. The first are easy to recognize from the address bar of your browser. If you select any admin-side panel link, you’ll see the URL contains ?event=panelname, and if you select any link in that panel that performs an action, you’ll see ?event=panelname&step=action. Those values correspond to the $event and $step parameters you can use during plugin or theme development. In fact, they will call any user-defined function that is registered for said $event and $step, allowing you to add your own events and steps as you need them.

If you wish to utilise such core hooks, consult the admin-side events and steps document, which lists them all.

The second type of callback relate to actions that occur in response to various page-level signals. These could be when certain parts of the administration interface are rendered or when actions (such as deletion) complete, and are listed below.

The final type of callback is pluggable_ui(). These deal with specific chunks of content that appear on the page and allow direct manipulation of individual elements or blocks. They are listed in the pluggable_ui document.

Major block-level callbacks

These callbacks relate to the <head> and <footer> sections, and navigation area of each admin panel. Raising callbacks on these event > step combinations will call your plugin on every panel. Check the global $event if you only wish to target a specific panel.

admin_side > head_end

  • When it occurs: Just before the closing </head> tag on every admin-side panel.
  • What it allows: Injecting JavaScript or style rules into the page’s header.

admin_side > pagetop

  • When it occurs: Immediately before control is handed to the theme.
  • What it does: Renders the navigation bar.

admin_side > pagetop_end

  • When it occurs: Immediately after the theme has been loaded and its header rendered. Just before the closing </header> tag.
  • What it allows: Injection of admin-wide markup below the panel navigation area.

admin_side > main_content

  • When it occurs: Immediately after the ‘announce’ area (where feedback messages appear) and before the panel’s main content begins. Just inside the <main> tag.
  • What it allows: Addition of information at the top of any panel, below the navigation area.

admin_side > main_content_end

  • When it occurs: Immediately before the closing </main> tag at the bottom of the panel.
  • What it allows: Addition of information at the bottom of any panel, above the footer area.

admin_side > body_end

  • When it occurs: After the theme’s footer has been rendered, before the closing </body> tag.
  • What it allows: Injection of non-blocking JavaScript <script> tags.

Widget callbacks

These callbacks are raised when input elements or constructs are rendered. They allow you to target input controls such as multi-edit options, pagination widgets, etc.

{event}_ui > multi_edit_options

  • When it occurs: Whenever a list of multi-edit options is rendered. The {event} is the panel on which the multi-edit control appears.
  • What it allows: Alteration or augmentation of the multi-edit select list. Argument #3 contains the options array, passed by reference so it may be altered directly.

{event}_ui > pageby_values

  • When it occurs: Whenever a set of pagination options are rendered. The {event} is the panel on which the pagination options appear.
  • What it allows: Alteration or augmentation of the steps in which pagination may occur, i.e. how many ‘rows’ of data are shown per page.
  • Argument #3: The array of sizes, passed by reference so it may be altered directly.

Panel-level callbacks

Write panel

article_posted

  • When it occurs: Immediately after article creation.
  • What it allows: Interception of the article create process to append or prepend content to the record, or to perform some additional processing.
  • Additional parameter: The posted contents as an array.

article_saved

  • When it occurs: Immediately after article update/save.
  • What it allows: Interception of the article save process to append or prepend content to the record, or to perform some additional processing.
  • Additional parameter: The posted contents as an array.

ping

  • When it occurs: Just before a ping notification is sent upon publication of an article.
  • What it allows: Interception of the ping so you can provide your own.

article_ui > partials_meta

  • When it occurs: Just before the partials are refreshed on an Ajax save.
  • What it allows: Alter or augment the interface, usually based on the data sent to/from the Ajax save process.
  • Argument #3: The record set of the article being edited.
  • Argument #4: The partials array comprised of:
    • key: Unique name of the item available to alter, then an array as follows:
      • mode: The mechanism by which the partial may be updated
      • selector: The wholly encapsulated DOM selector to which the partial applies
      • callback The callback function to utilize to update the nominated part of the interface
      • html An optional return value of the callback function

Articles panel

articles_deleted

  • When it occurs: After one or more articles have been deleted and any associated comments have had their visibility removed.
  • What it allows: To do any additional cleanup after one or more articles are removed from Textpattern.
  • Additional parameter: An array of deleted article IDs.

Categories panel

categories_deleted

  • When it occurs: After one or more categories have been deleted and the tree has been rebuilt.
  • What it allows: To do any additional cleanup after one or more categories are removed from Textpattern.
  • Additional parameter: An array of deleted category IDs.

Images panel

image_deleted

  • When it occurs: Before an image and its thumbnail are deleted.
  • What it allows: To do any additional cleanup after one or more images are removed from Textpattern.
  • Additional parameter: The ID of the deleted image.

thumbnail_deleted

  • When it occurs: Before a thumbnail is deleted.
  • What it allows: To do any additional cleanup after a thumbnail is removed from Textpattern.
  • Additional parameter: The ID of the deleted thumbnail.

image_uploaded

  • When it occurs: After an image has been uploaded or replaced by another image.
  • What it allows: To do any additional processing after an image is added or replaced from Textpattern.
  • Additional parameter: The ID of the image.

Files panel

file_deleted

  • When it occurs: Before each file is deleted.
  • What it allows: To do any additional cleanup after one or more files are removed from Textpattern.
  • First additional parameter: The file ID of the deleted file.
  • Second additional parameter: The full path to the deleted file.

links_deleted

  • When it occurs: After one or more links have been deleted.
  • What it allows: To do any additional cleanup after one or more links are removed from Textpattern.
  • Additional parameter: An array of deleted link IDs.

Comments panel

discuss_deleted

  • When it occurs: After one or more comments have been deleted, but before the comment counts have been updated in the affected articles.
  • What it allows: To do any additional cleanup after one or more comments are removed from Textpattern.
  • Additional parameter: An array of deleted comment IDs.

Sections panel

sections_deleted

  • When it occurs: After one or more sections have been deleted.
  • What it allows: To do any additional cleanup after one or more sections are removed from Textpattern.
  • Additional parameter: An array of deleted section names.

Pages panel

page_deleted

  • When it occurs: After a page template has been deleted.
  • What it allows: To do any additional cleanup after a page template is removed from Textpattern.
  • Additional parameter: The name of the deleted page.

Forms panel

forms_deleted

  • When it occurs: After one or more forms have been deleted.
  • What it allows: To do any additional cleanup after one or more forms are removed from Textpattern.
  • Additional parameter: An array of deleted form names.

form.create > done

  • When it occurs: After a form has been created from the UI.
  • What it allows: To do any additional processing when a form is created in Textpattern.
  • Additional parameter: An array comprising the new Form name, its type and its Form contents.

Styles panel

css_deleted

  • When it occurs: After a stylesheet has been deleted.
  • What it allows: To do any additional cleanup after a stylesheet is removed from Textpattern.
  • Additional parameter: The name of the deleted stylesheet.

Diagnostics panel

diag_results > low or > high

  • When it occurs: At the end of the doDiagnostics() function that renders the content of the Diagnostics panel.
  • What it allows: To add any extra information to the diagnostic output depending on the level of output the user has chosen (high or low).

Users panel

authors_deleted

  • When it occurs: After user(s) have been deleted and all assets have been reassigned.
  • What it allows: To do any additional cleanup after a user is removed from Textpattern.
  • Additional parameter: An array of deleted user names.

user.assign_assets > done

  • When it occurs: After user(s) have been deleted and all assets have been reassigned. Only runs if the existing user and new owner accounts both exist.
  • What it allows: To do any additional cleanup after a user is removed from Textpattern.
  • Additional parameter: An array containing the existing owner, the new_owner and a list of columns that have been affected by the reassignment.

See also user.assign_assets > columns.

user.create > done

  • When it occurs: After a user has been successfully created.
  • What it allows: To do any additional processing after a user has been created.
  • Additional parameter: An array containing the entire set of columns and their data about the new user.

user.update > done

  • When it occurs: After an existing user account has been successfully altered.
  • What it allows: To do any additional processing after user metadata has been modified.
  • Additional parameter: An array containing the name, email, realname and any additional metadata.

user.password_change > done

  • When it occurs: After an existing user has successfully changed their password.
  • What it allows: To do any additional processing after user metadata has been modified.
  • Additional parameter: An array containing the user name, password, and hash.

user.remove > done

  • When it occurs: After an existing user account has been successfully deleted.
  • What it allows: To do any additional processing after user removal.
  • Additional parameter: An array containing the list of deleted user names, and the new_owner of the deleted authors’ assets.

See also authors_deleted.

user.rename > done

  • When it occurs: After an existing user login name has been changed.
  • What it allows: To do any additional processing after user metadata has been modified.
  • Additional parameter: An array containing the original user name, and the newname.

user.change_group > done

  • When it occurs: After privileges of an existing user account has been successfully altered.
  • What it allows: To do any additional processing after user metadata has been modified.
  • Additional parameter: An array containing a list of the user names affected and new privilege level they have been assigned.

Admin-side criteria callbacks

These callbacks allow you to alter the criteria used in the various panels. You can append SQL to the criteria to apply additional filtering.

Note the criteria is appended, so existing search parameters are honoured. Therefore your returned statement should begin with " AND …". If you wish to ignore any previous filtering, begin " AND 1 AND …".

The third argument to your callback function contains the current criteria used, so you may make decisions based on its contents (e.g. you may not want to filter the results if a search has been performed).

These callbacks all have the same $event called admin_criteria.

Panel $step
Articles list_list
Comments discuss_list
Files file_list
Forms form_list
Images image_list
Links link_list
Pages page_list
Sections section_list
Styles css_list
Themes skin_list
Users author_list
Visitor logs log_list

Admin-side validation callbacks

These callbacks allow you to alter or append to the constraints imposed by the core when saving data. Textpattern will check that the passed values for things like categories, sections, and so forth actually exist in the database to avoid new ones being introduced at unexpected places.

If you’re developing plugins, you may wish to open up or restrict data in certain types of actions, or create entirely new constraints and take advantage of the built-in validator. If so, these callbacks are the ones to use.

These additional arguments are all passed by reference to your application, so you can alter them directly:

  • Argument #3 is the incoming array of values posted from the save operation, unsanitized.
  • Argument #4 is the array of constraints.
Panel $event $step
Articles article_ui validate_save
Articles article_ui validate_publish
Comments discuss_ui validate_save
Files file_ui validate_save
Images image_ui validate_save
Links link_ui validate_save

Admin-side theme callbacks

When performing theme operations such as import and export, you can intercept or alter the content. These allow you to do additional processing or file system operations, such as importing prefs and additional content when a theme is updated or installed.

$event $step $pre Argument #4 What it allows / does
txp.skin create 1 Theme metadata and theme name Prepare or check content prior to theme creation
txp.skin create 0 Theme metadata, theme name, and result of creation (false, or the name of the theme that was successfully created) Perform additional content, database or file manipulation on completion of the create process
txp.skin update 1 Theme metadata and theme name Prepare or check content prior to theme update/resynchronisation with the file system
txp.skin update 0 Theme metadata, theme name, and result of update (false, or the name of the theme that was successfully updated) Perform additional content, database or file manipulation on completion of the update/resynchronisation process
txp.skin duplicate 1 List of theme names to be processed Prepare or check content prior to theme duplication
txp.skin duplicate 0 List of theme names scheduled for duplication, and the name of each successfully duplicated theme Perform additional content, database or file manipulation on completion of the duplication process
txp.skin import 1 List of theme names to be processed Prepare or check content prior to theme import from the file system
txp.skin import 0 List of theme names scheduled for importing, and the name of each successfully imported theme Perform additional content, database or file manipulation on completion of the import process from the file system
txp.skin export 1 List of theme names to be processed Prepare or check content prior to theme export to the file system
txp.skin export 0 List of theme names scheduled for exporting, and the name of each successfully exported theme Perform additional content, database or file manipulation on completion of the export process to the file system
txp.skin delete 1 List of theme names to be deleted Prepare or check content prior to theme deletion
txp.skin delete 0 List of theme names scheduled for deletion, and the name of each successfully deleted theme Perform additional content, database or file manipulation on completion of the deletion process
txp.css, txp.form, txp.page import 1 Theme name and a list of its assets to be processed Prepare or check content prior to asset import from the file system
txp.css, txp.form, txp.page import 0 Theme name, the list of its assets to be processed, and the name of each successfully imported asset Perform additional content, database or file manipulation on completion of the import process from the file system
txp.css, txp.form, txp.page export 1 Theme name and a list of its assets to be processed Prepare or check content prior to asset export to the file system
txp.css, txp.form, txp.page export 0 Theme name, the list of its assets to be processed, and the name of each successfully imported asset Perform additional content, database or file manipulation on completion of the export process to the file system

Modification callbacks

Like pluggable_ui() callbacks, this type of callback is performed ‘pass by reference’ and allows you to directly alter the passed content by importing it by reference and manipulating it directly in your function. Use an ampersand in front of the data attribute to do so, like this which adds a new status level after the existing core set:

register_callback('abc_my_function', 'status.types', 'types');

function abc_my_function($evt, $stp, &$data)
{
    $data[6] = 'supersticky';
    return $data;
}

form.types > types

  • When it occurs: When the list of Form types are first retrieved on a panel.
  • What it allows: To alter or extend the available list of Form types.
  • Additional parameter: An array containing a list of the current form types, which you can directly alter if you wish and return.

form.essential > forms

  • When it occurs: When the list of ‘essential’ (fixed) Forms are first retrieved on a panel.
  • What it allows: To alter or extend the available list of essential Forms.
  • Additional parameter: An array containing a list of the current essential forms. The array key is the form name, and the array value is its group.

user.assign_assets > columns

  • When it occurs: The first time user assets are reassigned on a panel call.
  • What it allows: To alter or extend the available list of asset types that are affected when a user is deleted.
  • Additional parameter: An array containing a list of the currently affected columns. The aray key is the table name, and value is the name of the author column in that table.

status.types > types

  • When it occurs: When the list of Article publication status values are first retrieved on a panel.
  • What it allows: To alter or extend the available list of Status values.
  • Additional parameter: An array containing a list of the current statuses. The key is its numeric value (usually a constant) and the value (language key) is its name. Note the value is not its label as that is fetched from the txp_lang table for the current languauge.

API callbacks

form.fetch

  • When it occurs: The first time any Form is read from the database. Anything returned from your custom handler is used as Form contents for the named form.
  • What it allows: To alter where the Form contents is read.
  • Additional parameter: An array containing the name of the Form being fetched and the theme (skin) to which it is assigned. Note the skin may be the working theme if the site is being previewed.

page.fetch

  • When it occurs: The first time any Page is read from the database. Anything returned from your custom handler is used as Page contents for the named page.
  • What it allows: To alter where the Page contents is read.
  • Additional parameter: An array containing the name of the Page being fetched and the theme (skin) to which it is assigned. Note the skin may be the working theme if the site is being previewed.

site.update > {event}

  • When it occurs: Every time the site’s hidden lastmod value is updated in the preferences.
  • What it allows: To perform additional processing (e.g. caching) after one or more events have triggered the site modification datastamp to change.
  • Additional parameter: An array containing some details (like id etc) of the affected rows, plus an array containing the whenStamp (time now) and whenDate (database-friendly timestamp of time now).

preference.create > done

  • When it occurs: After a preference value has been successfully created.
  • What it allows: To do any additional processing after a preference value has been created.
  • Additional parameter: An array containing the entire set of columns and their data about the new preference.

preference.update > done

  • When it occurs: After a preference value has been successfully altered.
  • What it allows: To do any additional processing after a preference value has been changed.
  • Additional parameter: An array containing the entire set of columns and the new data that defines the preference.

preference.rename > done

  • When it occurs: After a preference value has been successfully renamed.
  • What it allows: To do any additional processing after a preference name has been changed.
  • Additional parameter: An array containing the preference’s original name, its newname and user_name to whom it is assigned. The user_name will be null if it’s a core preference value.

Plugin callbacks

In order to process these callbacks, your plugin must raise the PLUGIN_LIFECYCLE_NOTIFY flag to register its intent. In addition, if you wish to offer a link to your plugin’s preferences from the Plugins panel, you must raise the PLUGIN_HAS_PREFS flag.

$event $step When it occurs
plugin_lifecycle.abc_your_plugin enabled When somebody switches abc_your_plugin to “Enabled” (Yes) from the Plugins panel.
plugin_lifecycle.abc_your_plugin disabled When somebody switches abc_your_plugin to “Disabled” (No) on the Plugins panel.
plugin_lifecycle.abc_your_plugin installed When abc_your_plugin has been installed by the act of the user pasting its code in the Plugins panel and selecting Install button on the next screen.
plugin_lifecycle.abc_your_plugin deleted When abc_your_plugin has been removed by the act of a user selecting it and deleting it from the Plugins panel (note that the plugin_lifecycle.abc_your_plugin / disabled callback fires first).

Function- and tag-based callbacks

In lib/txplib_misc.php there are some callbacks that allow you to modify the default behaviour of some of the core functions. These are listed below:

$event $step When/where it occurs What it allows/does
sanitize_for_url - At start of the sanitizeForUrl() function. Apply your own URL sanitization rules; passes the text to be sanitized as the callback’s 4th argument.
sanitize_for_file - At start of the sanitizeForUrl() function. Apply your own filename sanitization rules; passes the text to be sanitized as the callback’s 4th argument.
sanitize_for_page - At start of the sanitizeForPage() function Apply your own page name sanitization rules; passes the text to be sanitized as the callback’s 4th argument.
txp_die http_status_code Once the page’s HTTP status has been determined. Passes the numerical HTTP status code as the callback’s step (e.g. 410, 301, etc) allowing you to target particular status codes and take action.

See something wrong in this document? Outdated info, a broken link, faulty code example, or whatever? Please write an issue and we’ll fix it.