====== Plugin Hooks & Filters ======
===== Core Filters =====
add_filter( 'filter_name', 'function_to_call' );
* **content** Will allow you to alter or filter the //$content// variable. The function that you pass $content to should then return your results back to the system.
* **menuitems** Will allow you to alter or filter the main navigation that is shown with the //get_navigation// template tag. The function that you pass //$menu// to should then return your results back to the system.
^ Filter ID ^ Description ^ arg type ^ Support ^
|content |filters page content data | string | |
|menuitems |filters the menu html returned in ''get_navigation()'' | string | |
|**pagecache** |filters the page cache xml object before saving | simplexmlobj | 3.3+ |
|**sitemap** |filters the ''$sitemap'' xmlobj before saving | simplexmlobj | 3.3+ |
|**indexid** |filters global page ''$id'' | string | 3.3+ |
|**data_index** |filters global page ''$data_index'' obj | simplexmlobj | 3.3+ |
|**editorlinks**|filters editor links ''get_link_menu_array'' | array| 3.3+ |
===== Core Hooks =====
add_action( 'hook_name', 'function_to_call', array( arguments ) );
The last argument is only necessary if function_to_call accepts parameters.
hook_name can be any of these and determines where the function will be called.
DEPRECATED\\
**NEW**\\
=== Front-End Hooks ===
^ Hook ID ^ Description ^ Support ^
| theme-header | Fired in '''' section of theme. Requires ''get_header()'' in template | |
| theme-footer | Fired in the footer of the theme. Requires ''get_footer()'' in template | |
| common | Called immediately after the plugin functions are included in ''common.php'' | 3.1+ |
| content-top | Fired right above content area of theme | |
| content-bottom | Fired right below content area of theme | |
| index-pretemplate | Called before your template files are rendered | |
| index-posttemplate | Called after your template files are rendered | |
| error-404 | Called if the page does not exist before rendering the error page | |
| **index-post-dataindex** | Called after the page globals are assigned from ''$data_index'' | 3.3+ |
=== Back-End Hooks ===
^ Hook ID ^ Description ^ Support ^
| admin-pre-header | Called before the ''header.php'' template file is loaded | 3.1+ |
| archive-backup | Fired when an archive backup has been created | |
| caching-save | Fired before ''data/other/pages.xml'' file is saved for caching | 3.1-3.3 |
| changedata-aftersave | Called after a page is saved | 3.1+ |
| changedata-updateslug | Called when slug changed on an existing page | |
| changedata-save | Called just before a page is saved | |
| common | Called immediately after the plugin functions are included in ''common.php'' | 3.1+ |
| component-extras | Fired when creating component sections, allows additional form elements | |
| edit-extras | Fired within the Page Options toggle-div within ''edit.php'' | |
| file-extras | Fired at the end of the file list | |
| file-uploaded | Fired after a file has been successfully uploaded | |
| footer | Called in the footer section of the rendered page | |
| download-file | Called when downloading files via ''download.php'' | |
| header | Called in the head section of the rendered page | |
| header-body | Called in the body before output of the page | |
| healthcheck-extras | Allows additional Health-check entries | |
| html-editor-init | Called after ckeditor js is output | |
| index-login | Fired above the login form | |
| logfile_delete | fired when a logfile is deleted | |
| login-reqs | Fired on the login page footer | |
| logout | Fired when a user logs out | |
| page-delete | fired when a page is deleted | |
| **pagecache-aftersave** | Fired after ''data/other/pages.xml'' pagecache file is successfully saved | 3.3+ |
| pages-main | Fired when the pages maincontent in rendered | |
| plugin-hook | Fired before the Plugin page is rendered | |
| resetpw-error | Fired when password reset and error | |
| resetpw-success | Fired when password reset and successful | |
| save-sitemap | Fired before the ''sitemap.xml'' file is saved | -3.1 |
| settings-cpsettings | Fired before the settings cp_settings file is created | 2.x-3.0 |
| settings-user | Fired before the settings user file is created | |
| settings-user-extras | Fired on the settings page, before //Save Settings// in the user section | |
| settings-website | Fired before the settings website page is created | |
| settings-website-extras | Fired on the settings page, before //Save Settings// in the website section | |
| sitemap-additem | Allow insertion of a new sitemap XML entry | -3.1 |
| **sitemap-aftersave** | Called after the sitemap is successfully saved | 3.3+ |
| successful-login-end | Fired after authentication success and before redirect | |
| successful-login-start | Fired when before login authentication starts | |
| support-extras | Allows additional support setting form entries | |
| support-save | Fired before ''cp_settings.xml'' file is created | -3.0 |
| theme-edit-extras | Fired in the theme edit screen before the submit button | |
| theme-extras | Fired after the theme screenshot | |
| welcome-doc-link | Allows additional documentation links on the Welcome page | |
| welcome-link | Allows additional links on the Welcome page | |
The following actions allow the customization of the administration menu and are described on [[plugins:tabs_menus|Tabs and Menus]]:
* **backups-sidebar, files-sidebar, pages-sidebar, plugins-sidebar, settings-sidebar, support-sidebar, theme-sidebar** Allows additional sidebar menu items
* **nav-tab** Allow insertion of a new tabbed entry in the navigation bar
=== Back-End GUI ===
^ Hook ID ^ Description ^ Support ^
| backups-sidebar | Sidebar item on Backups Page | |
| files-sidebar | Sidebar item on Files Page | |
| pages-sidebar | Sidebar item on Pages Page | |
| plugins-sidebar | Sidebar item on Plugins Page | |
| settings-sidebar | Sidebar item on Settings Page | |
| support-sidebar | Sidebar item on Support Page | |
| theme-sidebar | Sidebar item on Theme Page | |
| nav-tab | Insert navigation bar tab | |
===== Creating and Using Plugin Hooks/Filters =====
Similar to core hooks and filters, plugins can create their own by using the functions ''exec_action'' and ''exec_filter''.
exec_action( 'hook_name' );
exec_filter( 'filter_name', 'value_to_filter' );
If your plugin uses a GS hook to alter content before it is saved (e.g, the [[http://get-simple.info/extend/plugin/multi-user/133/|MultiUser plugin]] changes the output to the ''user.xml'' file and makes all changes from other plugins in this hook undone), it is especially important to add a custom hook, so that other plugin developers can make their plugins compatible with yours if they need to alter the data too.
If you created a plugin hook called 'your-plugin-hook', as described in the paragraph above, other plugin developers could then:
- (1) detect whether your plugin is active by using ''pluginIsActive('your-plugin-name')'' (GS 3.3.4+) or by checking for existence of your init function/a constant you defined, and
- (2) use your hook with ''add_action('your-plugin-hook', 'their-function')''.
This is an important step to take in making multiple plugins from different authors compatible with one another.
When naming hooks in your plugins //be sure to use a unique name// to not step on core hook ids.