User Tools

Site Tools


plugins:hooks_filters

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
Last revision Both sides next revision
plugins:hooks_filters [2013/04/19 15:04]
127.0.0.1 external edit
plugins:hooks_filters [2017/01/19 16:07]
lokothodida [Creating and Using Plugin Hooks]
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 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 );
 +</​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.
plugins/hooks_filters.txt · Last modified: 2017/01/19 16:10 by lokothodida