Core callbacks reference TODO

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 administration 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 click on any admin-side panel link, you’ll see the URL contains ?event=panelname, and if you click on 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.

include/txp_article.php

TODO: intro para about what this callback is concerned with

`$event` `$step` When it occurs What it allows/does ------------------ ----------------- ------------------------------------------------------------------------- --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- `article_posted` - Immediately after article creation. - `article_saved` - Immediately after article update/save. - ping - Just before a ping notification is sent upon publication of an article. You may intercept the ping and provide your own. `article_ui` `partials_meta` - Alters or augments the interface, usually based on the data sent to/from the AJAX save process. Argument \#3 is the record set of the article being edited. Argument \#4 is the partials array comprised of a ***key*** (unique name of the item available to alter), then an array: ***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), and ***html*** (an optional return value of the callback function).

include/txp_diag.php

TODO: intro para about what this callback is concerned with

`$event` `$step` When it occurs What it allows/does ---------------- ----------------- ----------------------------------------------- --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- `diag_results` `high` or `low` At the end of the `doDiagnostics()` function. Renders the content of the ****[Diagnostics](https://docs.textpattern.io/administration/diagnostics-panel) panel. Allows you to add any extra information to the diagnostic output depending on the level of output the user has chosen (high or low).

include/txp_admin.php

[todo:intro para about what this callback is concerned with]

notextile.

`$event` `$step` When it occurs What it allows/does ------------------- --------- ---------------------------------------------------------------------- ------------------------------------------------------- `authors_deleted` - After user(s) have been deleted and all assets have been reassigned. Passes an array of deleted user names as a parameter. notextile.

include/txp_category.php

[todo:intro para about what this callback is concerned with]

notextile.

`$event` `$step` When it occurs What it allows/does ---------------------- --------- ------------------------------------------------------------------------------- --------------------------------------------------------- `categories_deleted` - After one or more categories have been deleted and the tree has been rebuilt. Passes an array of deleted category IDs as a parameter. notextile.

include/txp_css.php

[todo:intro para about what this callback is concerned with]

notextile.

`$event` `$step` When it occurs What it allows/does --------------- --------- -------------------------------------- ----------------------------------------------------------- `css_deleted` - After a stylesheet has been deleted. Passes the name of the deleted stylesheet as a parameter. notextile.

include/txp_discuss.php

[todo:intro para about what this callback is concerned with]

notextile.

`$event` `$step` When it occurs What it allows/does ------------------- --------- --------------------------------------------------------------------------------------------------------------------------- ------------------------------------------------------------ `discuss_deleted` - After one or more comments have been deleted, but *before* the comment counts have been updated in the affected articles. Passes an array of the deleted comment IDs as a parameter. notextile.

include/txp_file.php

[todo:intro para about what this callback is concerned with]

notextile.

`$event` `$step` When it occurs What it allows/does ---------------- --------- ------------------------------ -------------------------------------------------------------------------------------------------------- `file_deleted` - Before each file is deleted. First additional parameter is the file's ID. Second additional parameter is the full path to the file. notextile.

include/txp_form.php

[todo:intro para about what this callback is concerned with]

notextile.

`$event` `$step` When it occurs What it allows/does ----------------- --------- -------------------------------------------- ------------------------------------------------------- `forms_deleted` - After one or more forms have been deleted. Passes an array of deleted form names as a parameter. notextile.

include/txp_image.php

[todo:intro para about what this callback is concerned with]

notextile.

`$event` `$step` When it occurs What it allows/does ------------------ --------- ---------------------------------------------------------------- ------------------------------------- `image_deleted` `image` Before an image and its thumbnail are deleted. Passes the image ID as a parameter `image_uploaded` `image` After an image has been uploaded or replaced by another image. Passes the image ID as a parameter. notextile.

include/txp_link.php

[todo:intro para about what this callback is concerned with]

notextile.

`$event` `$step` When it occurs What it allows/does ----------------- --------- -------------------------------------------- ----------------------------------------------------- `links_deleted` - After one or more links have been deleted. Passes an array of deleted link IDs as a parameter. notextile.

include/txp_list.php

[todo:intro para about what this callback is concerned with]

notextile.

`$event` `$step` When it occurs What it allows/does -------------------- --------- ------------------------------------------------------------------------------------------------------------- -------------------------------------------------------- `articles_deleted` - After one or more articles have been deleted and any associated comments have had their visibility removed. Passes an array of deleted article IDs as a parameter. notextile.

include/txp_page.php

[todo:intro para about what this callback is concerned with]

notextile.

`$event` `$step` When it occurs What it allows/does ---------------- --------- ----------------------------------------- ----------------------------------------------------- `page_deleted` - After a page template has been deleted. Passes the name of the deleted page as a parameter. notextile.

include/txp_section.php

[todo:intro para about what this callback is concerned with]

notextile.

`$event` `$step` When it occurs What it allows/does -------------------- --------- ----------------------------------------------- ---------------------------------------------------------- `sections_deleted` - After one or more sections have been deleted. Passes an array of deleted section names as a parameter. notextile.

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 (= admin_criteria).

notextile.

Panel `$event` `$step` ----------------------------------------------------------------------------------- ------------------ ---------------- "Articles":https://docs.textpattern.io/administration/articles-panel `admin_criteria` `list_list` "Comments":https://docs.textpattern.io/administration/comments-panel " discuss_list "Files":https://docs.textpattern.io/administration/files-panel " `file_list` "Forms":https://docs.textpattern.io/administration/forms-panel " `form_list` "Images":https://docs.textpattern.io/administration/images-panel " `image_list` "Links":https://docs.textpattern.io/administration/links-panel " link_list "Pages":https://docs.textpattern.io/administration/pages-panel " `page_list` "Sections":https://docs.textpattern.io/administration/sections-panel `admin_criteria` `section_list` "Styles":https://docs.textpattern.io/administration/styles-panel " `css_list` "Users":https://docs.textpattern.io/administration/users-panel " `author_list` "Visitor logs":https://docs.textpattern.io/administration/visitor-logs-panel " `log_list` notextile.

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.

notextile.

Panel `$event` `$step` ----------------------------------------------------------------------------- -------------- -------------------- "Articles":https://docs.textpattern.io/administration/content/articles-panel `article_ui` `validate_save` "Articles":https://docs.textpattern.io/administration/content/articles-panel `article_ui` `validate_publish` "Comments":https://docs.textpattern.io/administration/content/comments-panel `discuss_ui` `validate_save` "Files":https://docs.textpattern.io/administration/content/files-panel `file_ui` `validate_save` "Images":https://docs.textpattern.io/administration/content/images-panel `image_ui` `validate_save` "Links":https://docs.textpattern.io/administration/content/links-panel `link_ui` `validate_save` notextile.

Admin-side user-interface callbacks

These callbacks allow you to modify the admin-side panels in some way by targeting their associated widgets or individual controls. Modifications include:

  • adding new elements,
  • replacing elements, or
  • changing existing elements.

These callbacks are grouped here by the panel they are associated with.

Write panel

All calls are made to the include/txp_article.php file.

The same $event is used in each case: article_ui.

Blue means new in upcoming Textpattern 4.x.x.

notextile.

Concerned widget `$step` What it alters or replaces ---------------------- ------------------- ------------------------------------------------------------------------------------------------------------------------------------------ - `title` The **Title** field. - `body` The **Body** field. - `excerpt` The **Excerpt** field. - `view` The **View**, **HTML**, and **Preview** icon buttons. - `author` The *author* and *published-at* info. **Advanced options** `markup` The **Article markup** and **Excerpt markup** select lists. **Advanced options** `override` The **Override form** select list. **Article image** `article_image` The widget and **Article image** field. **Comment options** `annotate_invite` The **Off/On** and **Invitation** controls. **Custom fields** `custom_fields` The widget and contained input fields. **Date and time** `timestamp` The **Timestamp** controls. **Date and time** `expires` The **Expires** controls. **Meta** `keywords` The **Keywords** field. **Meta** `url_title` The **URL-only title** field. **Recent articles** `recent_articles` The widget and contained articles list. **Sort and display** `sort_display` The **Section** and **Category** select lists. **Sort and display** `section` The **Section** select list. **Sort and display** `categories` The **Category 1** and **Category 2** select lists. **Status** `status` The widget and contained radio buttons. **Textile help** `sidehelp` The widget and its contents. **Textile help** `extend_col_1` Adds (not alters or replaces) markup below `sidehelp`. Argument \#3 is empty as there is no default content here. See *Example 2* below. notextile.

Example 1: Altering the Status widget’s radio button list

In this example we’ll alter the Status widget’s radio button list by adding a new button option to it:

register_callback('abc_altered_status', 'article_ui', 'status');

function abc_altered_status($event, $step, $data, $rs) {
    $stat = isset($rs['Status']) ? $rs['Status'] : '';
    $new_status = n.t.'&lt;li&gt;'.radio('Status', 6, ($stat == 6) ? 1 : 0, 'status-6').'&lt;label for=&quot;status-6&quot;&gt;Velcro&lt;/label&gt;&lt;/li&gt;';
    $data = str_replace('&lt;/ul&gt;', $new_status.'&lt;/ul&gt;', $data);

    return $data;
}

We’ve used register_callback() to define our callback function, and in this case we’ve employed the $event/@$step@ combination for targeting the Status widget in the Write panel. The function then pulls the default record set, defines a new status button option for inclusion, and returns (outputs) the resulting altered list.

Example 2: Adding text to the **Textile help widget**

Note the last record in the callbacks table above is different from the others; it adds a new, unique element to the panel instead of changing one that already exists, as in the previous example. Let’s do that one. We’ll add some text - “Textile, the humane web text generator.” - in the Textile help widget:

register_callback('abc_add_text', 'article_ui', 'extend_col_1');

function abc_add_text($event, $step, $data, $rs) {
   return 'Textile, the humane web text generator.';
}

Easy-peasy. The text is added immediately below the widget header link, which is where the extend_col_1 step outputs its markup.

include/txp_category.php

[todo:intro para about what this callback is concerned with]

For the **Categories panel.

notextile.

Panel `$event` `$step` What it allows/does ------------ --------------- ---------------------- -------------------------------------------------------------------------------------------------------------------------------------------- Categories `category_ui` `extend_detail_form` adds markup above the category *Save* button when editing an individual category argument \#3 is empty because there is no default content notextile.

include/txp_image.php

[todo:intro para about what this callback is concerned with]

For the **Images panel. These callbacks have a single $event (i.e. image_ui).

notextile.

Panel `$event` `$step` What it allows/does Argument notes -------- ------------ ---------------------- -------------------------------------------------------------------------------------------------------------- ------------------------------------------------------------ Images `image_ui` `extend_controls` Adds markup to the `txp-control-panel` area. Argument \#3 is empty because there is no default content. " " `extend_detail_form` Adds markup above the image **Save** button when editing an image. Argument \#3 is empty because there is no default content. " " `thumbnail` Alters or replaces the thumbnail in the image list. - " " `fullsize_image` Alters or replaces the main image in the image edit panel. - " " `image_edit` Alters or replaces the area containing the upload (replace) image form. - " " `thumbnail_image` Alters or replaces the thumbnail image in the image edit panel. - " " `thumbnail_edit` Alters or replaces the area containing the thumbnail upload form. - " " `thumbnail_create` Alters or replaces the 'thumbnail create' area containing the width / height input fields and crop checkbox. - notextile.

include/txp_file.php

[todo:intro para about what this callback is concerned with]

For the **Files panel.

notextile.

Panel `$event` `$step` What it allows/does Argument notes ------- ----------- ---------------------- ----------------------------------------------------------- -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Files `file_ui` `extend_detail_form` Add markup above the **Save** button when editing a file. Argument \#3 is empty because there is no default content. The same callback is used whether the file you are editing exists or is missing from the database. Use the absence or availability of the 4th argument (record set) to determine which state the panel is in. notextile.

include/txp_links.php

[todo:intro para about what this callback is concerned with]

For the **Links panel.

notextile.

Panel `$event` `$step` What it allows/does Argument notes ------- ----------- ---------------------- -------------------------------------------- ------------------------------------------------------------ Links `link_ui` `extend_detail_form` Add markup above the link **Save** button. Argument \#3 is empty because there is no default content. notextile.

include/txp_section.php

[todo:intro para about what this callback is concerned with]

For the **Sections panel.

notextile.

Panel `$event` `$step` What it allows/does Argument notes ---------- -------------- ---------------------- ------------------------------------------------------------------------------- --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Sections `section_ui` `extend_detail_form` Add markup immediately above the **Save** button in the *section edit* panel. Argument \#3 is empty because there is no default content. Argument \#4 contains only the columns *page* and *css* when in the default area, and contains all columns at other times. notextile.

include/txp_admin.php

TODO: intro para about what this callback is concerned with

For the **Users panel.

notextile.

Panel `$event` `$step` What it allows/does Argument notes ------- ------------- ---------------------- ---------------------------------------------------------- ------------------------------------------------------------ Users `author_ui` `extend_detail_form` Add markup immediately above the author **Save** button. Argument \#3 is empty because there is no default content. notextile.

include/txp_prefs.php

TODO: intro para about what this callback is concerned with

See the Preferences administration panel documentation.

notextile.

Panel `$event` `$step` What it allows/does Argument notes ---------- ------------ -------------- --------------------------------------------------------------------------------------------------------------------------------------------------------- ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Basic `prefs_ui` `gmtoffset` Alters or replaces the **Time zone** select list input control (not the label). Argument \#4 is the preference name in the 'txp_prefs' table (`timezone_key` in this case). Argument \#5 is the preference's value (i.e. the chosen item). Basic `prefs_ui` `is_dst` Alters or replaces the **DST enabled** radio buttons (not the label). Argument \#4 is the preference name in the 'txp_prefs' table (`is_dst` in this case). Argument \#5 is the preference's value (i.e. the numerical state of the radio button). Basic `prefs_ui` `weeks` Alter or replace the **Comments disabled after** select list control (not the label). Argument \#4 is the preference name in the 'txp_prefs' table (`comments_disabled_after` in this case). Argument \#5 is the preference's value (i.e. the numerical value of the selected item; in this case the number of days to keep commenting open). Advanced `prefs_ui` `custom_set` Alter or replace the Custom field input controls (not the labels). Each text box is called separately; you distinguish between them using argument \#4. Argument \#4 is the preference name in the 'txp_prefs' table (`custom_set_N` by default, where *N* is the custom field number). Argument \#5 is the preference's value (i.e. the name of the custom field). Advanced `prefs_ui` `theme_name` Alters or replace the **Admin theme** select list control (not the label). - notextile.

Admin-side theme callbacks

These callbacks are all used to alter various elements within admin-side themes.

lib/txplib_theme.php

[todo:intro para about what this callback is concerned with]

notextile.

</div>

lib/txplib_head.php

[todo:intro para about what this callback is concerned with]

notextile.

</div>

lib/txplib_html.php

[todo:intro para about what this callback is concerned with]

notextile.

some_event_ui upload_form Alters or replaces Textpattern’s standard upload forms throughout the admin side. some_event is the name of the event on the panel upon which the input form appears (e.g. on the Files panel, the event is file so the pluggable_ui() event name is file_ui). Argument #4 contains the remainder of the arguments to the upload_form() function (i.e. ‘label’, ‘pophelp’, ‘step’, ‘event’, ‘id’, ‘max_file_size’, ‘label_id’ and ‘class’).

notextile.

</div> Plugin callbacks {#sec3} —————-

TODO: intro para about plugin callbacks in general

include/txp_plugin.php

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 What it allows/does ------------------------------------ ------------- ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ --------------------- `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 clicking **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

TODO: intro para about function- and tag-based callbacks in general

lib/txplib_misc.php

TODO: intro para about what this callback is concerned with

`$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 `sanitizeForUrl()` 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.