This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
plugins:hooks_filters [2013/04/19 15:04] 127.0.0.1 external edit |
plugins:hooks_filters [2017/01/19 16:10] (current) lokothodida [Creating and Using Plugin Hooks/Filters] |
||
---|---|---|---|
Line 3: | Line 3: | ||
===== Core Filters ===== | ===== Core Filters ===== | ||
- | <code>add_filter('filter_name','function_to_call');</code> | + | <code>add_filter( 'filter_name', 'function_to_call' );</code> |
* **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. | * **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. | * **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 ===== | ===== Core Hooks ===== | ||
- | <code>add_action('hook_name','function_to_call',array(arguments));</code> | + | <code>add_action( 'hook_name', 'function_to_call', array( arguments ) );</code> |
The last argument is only necessary if function_to_call accepts parameters. | The last argument is only necessary if function_to_call accepts parameters. | ||
Line 15: | Line 23: | ||
hook_name can be any of these and determines where the function will be called. | hook_name can be any of these and determines where the function will be called. | ||
- | **FRONT-END HOOKS** | + | <del>DEPRECATED</del>\\ |
- | * **theme-header** Fired in //<head>// section of theme. Requires //get_header()// in template | + | **NEW**\\ |
- | * **theme-footer** Fired in the footer of the theme. Requires //get_footer()// in template | + | |
- | * **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. | + | |
- | **BACK-END HOOKS** | + | === Front-End Hooks === |
- | * **header** Called in the head section of the rendered page | + | |
- | * **header-body** Called in the body before output of the page | + | ^ Hook ID ^ Description ^ Support ^ |
- | * **admin-pre-header** Called before the header.php template file is loaded (3.1+) | + | | theme-header | Fired in ''<head>'' section of theme. Requires ''get_header()'' in template | | |
- | * **footer** Called in the footer section of the rendered page | + | | 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+) | + | | common | Called immediately after the plugin functions are included in ''common.php'' | 3.1+ | |
- | * **logout** Fired when a user logs out | + | | content-top | Fired right above content area of theme | | |
- | * **index-login** Fired above the login form | + | | content-bottom | Fired right below content area of theme | | |
- | * **login-reqs** Fired on the login sidebar | + | | index-pretemplate | Called before your template files are rendered | | |
- | * **resetpw-success** Fired when password reset and successful | + | | index-posttemplate | Called after your template files are rendered | | |
- | * **resetpw-error** Fired when password reset and error | + | | error-404 | Called if the page does not exist before rendering the error page | | |
- | * **settings-user** Fired before the settings user file is created | + | | **index-post-dataindex** | Called after the page globals are assigned from ''$data_index'' | 3.3+ | |
- | * **settings-website** Fired before the settings website page is created | + | |
- | * **settings-cpsettings** Fired before the settings cp_settings file is created | + | |
- | * **settings-website-extras** Fired on the settings page, before "save settings" button in the website section | + | === Back-End Hooks === |
- | * **settings-user-extras** Fired on the settings page, before "save settings" button in the user section | + | ^ Hook ID ^ Description ^ Support ^ |
- | * **sitemap-additem** Allow insertion of a new sitemap XML entry | + | | admin-pre-header | Called before the ''header.php'' template file is loaded | 3.1+ | |
- | * **sitemap-save** Fired before the sitemap.xml file is saved | + | | archive-backup | Fired when an archive backup has been created | | |
- | * **theme-extras** Fired after the theme screenshot | + | | <del>caching-save</del> | Fired before ''data/other/pages.xml'' file is saved for caching | 3.1-3.3 | |
- | * **theme-edit-extras** Fired in the theme edit screen before the submit button | + | | changedata-aftersave | Called after a page is saved | 3.1+ | |
- | * **welcome-link** Allows additional links on the Welcome page | + | | changedata-updateslug | Called when slug changed on an existing page | | |
- | * **welcome-doc-link** Allows additional documentation links on the Welcome page | + | | changedata-save | Called just before a page is saved | | |
- | * **healthcheck-extras** Allows additional Health-check entries | + | | common | Called immediately after the plugin functions are included in ''common.php'' | 3.1+ | |
- | * **support-extras** Allows additional support setting form entries | + | | component-extras | Fired when creating component sections, allows additional form elements | | |
- | * **support-save** Fired before cp_settings.xml file is created, allows additional support-extras to be saved | + | | edit-extras | Fired within the Page Options toggle-div within ''edit.php'' | | |
- | * **plugin-hook** Fired before the Plugin page is rendered. | + | | file-extras | Fired at the end of the file list | | |
- | * **archive-backup** Fired when an archive backup has been created | + | | file-uploaded | Fired after a file has been successfully uploaded | | |
- | * **component-save** Fired before components are saved | + | | footer | Called in the footer section of the rendered page | | |
- | * **component-extras** Fired when creating component sections, allows additional form elements to be embedded | + | | download-file | Called when downloading files via ''download.php'' | | |
- | * **logfile_delete** fired when a logfile is deleted | + | | header | Called in the head section of the rendered page | | |
- | * **page-delete** fired when a page is deleted | + | | header-body | Called in the body before output of the page | | |
- | * **changedata-save** Called just before a page is saved | + | | healthcheck-extras | Allows additional Health-check entries | | |
- | * **changedata-aftersave** Called after a page is saved (3.1+) | + | | html-editor-init | Called after ckeditor js is output | | |
- | * **caching-save** Fired before //pages.xml// file (in //data/other//) is saved for Caching (3.1+) | + | | index-login | Fired above the login form | | |
- | * **edit-extras** Fired within the Page Options toggle-div within edit.php | + | | logfile_delete | fired when a logfile is deleted | | |
- | * **edit-content** Creating additional data/fields after the textarea on edit.php | + | | login-reqs | Fired on the login page footer | | |
- | * **file-uploaded** Fired after a file has been successfully uploaded | + | | logout | Fired when a user logs out | | |
- | * **files-extras** Fired at the end of the file list | + | | page-delete | fired when a page is deleted | | |
- | * **successful-login-start** | + | | **pagecache-aftersave** | Fired after ''data/other/pages.xml'' pagecache file is successfully saved | 3.3+ | |
- | * **successful-login-end** | + | | 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 | | | ||
+ | | <del>save-sitemap</del> | Fired before the ''sitemap.xml'' file is saved | -3.1 | | ||
+ | | <del>settings-cpsettings</del> | 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 | | | ||
+ | | <del>sitemap-additem</del> | 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 | | | ||
+ | | <del>support-save</del> | 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]]: | The following actions allow the customization of the administration menu and are described on [[plugins:tabs_menus|Tabs and Menus]]: | ||
Line 70: | Line 91: | ||
* **nav-tab** Allow insertion of a new tabbed entry in the navigation bar | * **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''. | ||
+ | |||
+ | <code> | ||
+ | exec_action( 'hook_name' ); | ||
+ | </code> | ||
+ | |||
+ | <code> | ||
+ | exec_filter( 'filter_name', 'value_to_filter' ); | ||
+ | </code> | ||
+ | |||
+ | 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. |