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
plugins:hooks_filters [2013/10/30 16:02]
shawn_a login hooks
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 ​                                          ^ 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 ​          | Fired after authentication success and before redirect ​                          ​| ​          ​| ​ | successful-login-end ​          | Fired after authentication success and before redirect ​                          ​| ​          ​| ​
 | successful-login-start ​        | Fired when before login authentication starts ​                                   |           ​| ​ | successful-login-start ​        | Fired when before login authentication starts ​                                   |           ​| ​
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_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.
plugins/hooks_filters.1383148936.txt.gz · Last modified: 2013/10/30 16:02 by shawn_a