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/10/30 15:45]
shawn_a added tables and new stuff
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 ​                                          ^ Support ^ +^ Filter ID     ^ Description ​                                          ^ arg type      ​^ Support ^ 
-|content ​       |filters page content data                              |         | +|content ​       |filters page content data                              ​| string ​       ​|         | 
-|menuitems ​     |filters the menu html returned in ''​get_navigation()''​ |         | +|menuitems ​     |filters the menu html returned in ''​get_navigation()'' ​| string ​       ​|         | 
-|**pagecache** ​ |filters ​''​$pagesarray''​ data before saving ​            ​| 3.3+    | +|**pagecache** ​ |filters ​the page cache xml object ​before saving ​       | simplexmlobj  ​| 3.3+    | 
-|**sitemap** ​   |filters the ''​$sitemap''​ xmlobj before saving ​         | 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 29: Line 31:
 | theme-header ​                  | Fired in ''<​head>''​ section of theme. Requires ''​get_header()''​ in template ​             |           ​| ​ | theme-header ​                  | Fired in ''<​head>''​ section of theme. Requires ''​get_header()''​ in template ​             |           ​| ​
 | theme-footer ​                  | Fired in the footer of the theme. Requires ''​get_footer()''​ 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-top ​                   | Fired right above content area of theme                                          |           ​| ​
 | content-bottom ​                | Fired right below content area of theme                                          |           ​| ​ | content-bottom ​                | Fired right below content area of theme                                          |           ​| ​
Line 34: Line 37:
 | index-posttemplate ​            | Called after 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                |           ​| ​ | 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 === === Back-End Hooks ===
Line 59: Line 64:
 | logout ​                        | Fired when a user logs out                                                       ​| ​          ​| ​ | logout ​                        | Fired when a user logs out                                                       ​| ​          ​| ​
 | page-delete ​                   | fired when a page is deleted ​                                                    ​| ​          ​| ​ | page-delete ​                   | fired when a page is deleted ​                                                    ​| ​          ​| ​
-| **pagecache-saved**            | Fired after ''​data/​other/​pages.xml''​ pagecache file is successfully saved        | 3.3+      | +| **pagecache-aftersave**            | Fired after ''​data/​other/​pages.xml''​ pagecache file is successfully saved        | 3.3+      | 
 | pages-main ​                    | Fired when the pages maincontent in rendered ​                                    ​| ​          ​| ​ | pages-main ​                    | Fired when the pages maincontent in rendered ​                                    ​| ​          ​| ​
 | plugin-hook ​                   | Fired before the Plugin page is rendered ​                                        ​| ​          ​| ​ | plugin-hook ​                   | Fired before the Plugin page is rendered ​                                        ​| ​          ​| ​
Line 71: Line 76:
 | settings-website-extras ​       | Fired on the settings page, before //Save Settings// in the website section ​     |           ​| ​ | 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      |  | <​del>​sitemap-additem</​del> ​    | Allow insertion of a new sitemap XML entry                                       | -3.1      | 
-| **sitemap-saved**              | Called after the sitemap is successfully saved                                   | 3.3+      |  +| **sitemap-aftersave**              | Called after the sitemap is successfully saved                                   | 3.3+      |  
-| successful-login-end ​          ​| ​                                                                                 |           |  +| successful-login-end ​          ​| ​Fired after authentication success and before redirect ​                          |           |  
-| successful-login-start ​        ​| ​                                                                                 |           ​| ​+| successful-login-start ​        ​| ​Fired when before login authentication starts ​                                   ​|           ​| ​
 | support-extras ​                | Allows additional support setting form entries ​                                  ​| ​          ​| ​ | support-extras ​                | Allows additional support setting form entries ​                                  ​| ​          ​| ​
 | <​del>​support-save</​del> ​       | Fired before ''​cp_settings.xml''​ file is created ​                                | -3.0      |  | <​del>​support-save</​del> ​       | Fired before ''​cp_settings.xml''​ file is created ​                                | -3.0      | 
Line 96: Line 101:
 | theme-sidebar ​   | Sidebar item on Theme Page    |         | | theme-sidebar ​   | Sidebar item on Theme Page    |         |
 | nav-tab ​         | Insert navigation bar tab     ​| ​        | | 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