Core callback list
From Textpattern CMS User Documentation
The following is a list of callbacks in Textpattern. It is current as of Textpattern 4.5.4:
Regular public-side callbacks
publish.php
- event = pretext
- occurs at the very top of the
pretext()function, just after the prefs have been extracted - event = pretext_end
- occurs just after
pretext()has run but before its variables have been extracted into the global scope - useful for overriding anything set in
pretext()or adding variables to it - event = file_download
- occurs as soon as a file_download is detected, allowing you to intercept the regular file downloading process
- event = textpattern
- occurs just before the page is rendered
- event = textpattern_end
- occurs once the page has been fully rendered
publish/atom.php
- event = atom_head
- occurs after the feed's header has been set
- allows you to add items to the feed's header
- event = atom_entry
- occurs as soon as the article's data has been populated
- allows you to inject extra markup after the standard feed items have been generated
publish/rss.php
- event = rss_head
- occurs after the feed's header has been set
- allows you to add items to the feed's header
- event = rss_entry
- occurs as soon as the article's data has been populated
- allows you to inject extra markup after the standard feed items have been generated
publish/comment.php
- event = comment.form
- occurs at the end of the
commentForm()function - allows you to inject markup after the textarea generated by the
<txp:comment_message_input />tag - event = comment.save
- occurs just before a comment is posted
- allows you to make additional decisions based on the comment content, e.g. anti-spam plugins
- event = comment.saved
- occurs just after a comment is posted to the database
- 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
- event = log_hit
- occurs just before a log message is recorded in the txp_log table
- allows you to alter the log message
Function- and tag-based callbacks
lib/txplib_misc.php
- event = sanitize_for_url
- occurs at the start of the
sanitizeForUrl()function allowing you to apply your own URL sanitization rules - passes the text to be sanitized as the callback's 4th argument
- event = sanitize_for_file
- occurs at the start of the
sanitizeForFile()function allowing you to apply your own filename sanitization rules - passes the text to be sanitized as the callback's 4th argument
- event = sanitize_for_page
- occurs at the start of the
sanitizeForPage()function allowing you to apply your own page name sanitization rules - passes the text to be sanitized as the callback's 4th argument
- event = txp_die
step = http_status_code - occurs 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
Plugin callbacks
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 Admin>Plugins panel, you must raise the PLUGIN_HAS_PREFS flag.
- event = plugin_lifecycle.abc_your_plugin
step = enabled - occurs when somebody switches abc_your_plugin to Yes from the Admin>Plugins panel
- event = plugin_lifecycle.abc_your_plugin
step = disabled - occurs when somebody switches abc_your_plugin to No from the Admin>Plugins panel
- event = plugin_lifecycle.abc_your_plugin
step = installed - occurs when abc_your_plugin has been installed by the act of the user pasting its code in the Admin>Plugins panel and clicking Install on the next screen
- event = plugin_lifecycle.abc_your_plugin
step = deleted - occurs when abc_your_plugin has been removed by the act of the user selecting it and deleting it from the Admin>Plugins panel
- note that the plugin_lifecycle.abc_your_plugin / disabled callback fires first
Regular admin-side callbacks
lib/txplib_head.php
- event = admin_side
step = head_end - occurs just before the closing
</head>tag on every admin side panel - useful for injecting javascript or style rules into the page's header
- event = admin_side
step = pagetop - occurs immediately before control is handed to the theme to render the navigation bar
- event = admin_side
step = pagetop_end - occurs immediately after the theme has finished rendering the navigation bar
- useful for adding admin-wide markup below pagetop
lib/txplib_html.php
- event = admin_side
step = body_end - occurs once the theme has rendered its footer
- allows you to tack on any extra admin-wide information immediately before the closing
</body>tag - event = some_event_ui
step = multi_edit_options - allows you to alter or augment the multi-edit select list.
- argument #3 contains the options array which is passed by reference so it may be altered directly
include/txp_article.php
- event = article_posted
- called immediately after article creation
- event = article_saved
- called immediately after article update/save
- event = ping
- occurs just before a ping notification is sent upon publication of an article so you may intercept the ping and provide your own
- event = article_ui
step = partials_meta - allows you to alter or augment 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, which comprises:
- 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 utilise to update the nominated part of the interface
- html (optional) return value of the callback function
- key unique name of the item available to alter, then an array:
include/txp_diag.php
- event = diag_results
step = high or low - occurs at the end of the
doDiagnostics()function for rendering the content of the Admin->Diagnostics 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
- event = authors_deleted
- occurs just after user(s) have been deleted and all assets have been reassigned
- an array of deleted user names is passed as a parameter
include/txp_category.php
- event = categories_deleted
- occurs just after one or more categories have been deleted and the tree has been rebuilt
- an array of deleted category IDs is passed as a parameter
include/txp_css.php
- event = css_deleted
- occurs just after a stylesheet has been deleted
- the name of the deleted stylesheet is passed as a parameter
include/txp_discuss.php
- event = discuss_deleted
- occurs just after one or more comments have been deleted, but before the comment counts have been updated in the affected articles
- an array of the deleted comment IDs is passed as a parameter
include/txp_file.php
- event = file_deleted
- occurs just before each file is deleted
- the first additional parameter is the file's ID
- the second additional parameter is the full path to the file
include/txp_form.php
- event = forms_deleted
- occurs just after one or more forms have been deleted
- an array of deleted form names is passed as a parameter
include/txp_image.php
- event = image_deleted
step = image - occurs just before an image and its thumbnail are deleted
- the image ID is passed as a parameter
- event = image_uploaded
step = image - occurs just after an image has been uploaded or replaced by another image. The image ID is passed as a parameter
include/txp_link.php
- event = links_deleted
- occurs just after one or more links have been deleted
- an array of deleted link IDs is passed as a parameter
include/txp_list.php
- event = articles_deleted
- occurs just after one or more articles have been deleted and any associated comments have had their visibility removed
- an array of deleted article IDs is passed as a parameter
include/txp_page.php
- event = page_deleted
- occurs just after a page template has been deleted
- the name of the deleted page is passed as a parameter
include/txp_section.php
- event = sections_deleted
- occurs just after one or more sections have been deleted
- an array of deleted section names is passed as a parameter
Admin-side criteria callbacks
These callbacks allow you to alter the criteria that are used in the various panels. You can append SQL to the criteria so you may apply additional filtering.
Note that 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 with " AND 1 AND ...".
The third argument to your callback function contains the current criteria used so you may make decisions based on its contents (for example, you may not want to filter the results if a search has been performed).
The callbacks all have event = admin_criteria and the following steps:
- Articles panel: list_list
- Comments panel: discuss_list
- Files panel: file_list
- Forms panel: form_list
- Images panel: image_list
- Links panel: link_list
- Pages panel: page_list
- Sections panel: section_list
- Styles panel: css_list
- Users panel: author_list
- Visitor logs panel: log_list
Admin side validation callbacks
The following 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.
Inside 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.
Argument #3 is the incoming array of values posted from the save operation, unsanitized. Argument #4 is the array of constraints.
Note that these additional arguments are all passed by reference to your application, so you can alter them directly.
Articles panel
- event = article_ui
step = validate_publish - event = article_ui
step = validate_save
Comments panel
- event = discuss_ui
step = validate_save
Files panel
- event = file_ui
step = validate_save
Images panel
- event = image_ui
step = validate_save
Links panel
- event = link_ui
step = validate_save
pluggable_ui() callbacks
Argument #1 passed to your function is the event and argument #2 is the step. Arguments 3 and 4 (and occasionally 5) vary depending on the functionality of the UI component. In general, the following holds true unless otherwise stated:
- argument #3 is the default markup
- argument #4 is the record set of the item that is being edited (if applicable)
Parsing argument #3 allows you to alter what was originally going to be displayed, and then return it. Or you may discard this markup and return your own instead.
Write panel (include/txp_article.php)
All of the UI elements on this page have the same event = article_ui.
- step = sidehelp
- allows you to replace or alter the 'Textile Help' lever and its entire contents
- step = extend_col_1
- allows you to add your own markup below the sidehelp
- argument #3 is empty as there is no default content here
- step = markup
- allows you to replace or alter the two select lists for article and excerpt markup
- step = override
- allows you to alter or replace the override form select list
- step = view
- allows you to alter or replace the view/HTML/Preview icons
- step = sort_display
- allows you to alter or replace the section and category select lists
- step = timestamp
- allows you to alter or replace the article's posted timestamp area
- step = expires
- allows you to alter or replace the article expiry area
- step = custom_fields
- allows you to alter or replace the block of custom field input controls
- step = keywords
- allows you to alter or replace the keywords area
- step = article_image
- allows you to alter or replace the article_image area
- step = url_title
- allows you to alter or replace the URL title input area
- step = recent_articles
- allows you to alter or replace the recent articles list
- step = title
- allows you to alter or replace the article's title element
- step = body
- allows you to alter or replace the article's body element
- step = excerpt
- allows you to alter or replace the article's excerpt element
- step = author
- allows you to alter or replace the author / published-at info
- step = status
- allows you to alter or replace the article's status area
- step = categories
- allows you to alter or replace the article's category1/category2 area
- step = section
- allows you to alter or replace the article's section select list
- step = annotate_invite
- allows you to alter or replace the article's comments on/off and comments invite area
Categories panel (include/txp_category.php)
- event = category_ui
step = extend_detail_form - allows you to add markup above the category Save button when editing an individual category
- argument #3 is empty because there is no default content
Images panel (include/txp_image.php)
- event = image_ui
step = extend_controls - allows you to add markup to the txp-control-panel area
- argument #3 is empty because there is no default content
- event = image_ui
step = extend_detail_form - allows you to add markup above the image Save button when editing an image
- argument #3 is empty because there is no default content
- event = image_ui
step = thumbnail - allows you to alter/replace the thumbnail in the image list
- event = image_ui
step = fullsize_image - allows you to alter/replace the main image in the image edit panel
- event = image_ui
step = image_edit - allows you to alter/replace the area containing the upload (replace) image form
- event = image_ui
step = thumbnail_image - allows you to alter/replace the thumbnail image in the image edit panel
- event = image_ui
step = thumbnail_edit - allows you to alter/replace the area containing the thumbnail upload form
- event = image_ui
step = thumbnail_create - allows you to alter/replace the 'thumbnail create' area containing the width / height input fields and crop checkbox
Files panel (include/txp_file.php)
- event = file_ui
step = extend_detail_form - allows you to add markup above the file 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
Links panel (include/txp_links.php)
- event = link_ui
step = extend_detail_form - allows you to add markup above the link Save button
- argument #3 is empty because there is no default content
Sections panel (include/txp_section.php)
- event = section_ui
step = extend_detail_form - allows you to add markup immediately above the Save button in the section edit panel
- argument #3 is empty because there is no default content
- the record set in argument #4 contains only the columns page and css when in the default area, and contains all columns at other times
Users panel (include/txp_admin.php)
- event = author_ui
step = extend_detail_form - allows you to add markup immediately above the author Save button
- argument #3 is empty because there is no default content
Preferences panel (include/txp_prefs.php)
- event = prefs_ui
step = gmtoffset - allows you to alter or replace the Time zone select list (just the 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)
- event = prefs_ui
step = is_dst - allows you to alter or replace the DST enabled radio buttons (just the input control, 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)
- event = prefs_ui
step = weeks - allows you to alter or replace the Comments disabled after select list (just the input 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)
- event = prefs_ui
step = custom_set - allows you to alter or replace the Custom Field text boxes on the Advanced Prefs panel (just the 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)
- event = prefs_ui
step = theme_name - allows you to alter or replace the Admin theme select list on the Advanced Prefs panel (just the input control, not the label)
Theme callbacks
The following callbacks are all usable to alter various elements within admin-side themes.
lib/txplib_theme.php
- event = admin_side
step = theme_name - allows you to alter a theme's name when it is being initialised
- there is no argument #4
lib/txplib_head.php
- event = admin_side
step = header - allows you to replace the standard pagetop header with something of your choosing. Theme authors do this by writing a
header()function in their theme's PHP file - there is no argument #4
lib/txplib_html.php
- event = admin_side
step = footer - allows you to replace the standard end_page footer with something of your choosing. Theme authors do this by writing a
footer()function in their theme's PHP file - there is no spoon
- event = some_event_ui
step = upload_form - allows you to alter or replace 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'.
