| Index: trunk/phase3/docs/hooks.txt |
| — | — | @@ -75,15 +75,15 @@ |
| 76 | 76 | option-specific stuff in our mainline code. Using hooks, the function |
| 77 | 77 | becomes: |
| 78 | 78 | |
| 79 | | - function showAnArticle($article) { |
| | 79 | + function showAnArticle($article) { |
| 80 | 80 | |
| 81 | | - if (wfRunHooks('ArticleShow', array(&$article))) { |
| 82 | | - |
| 83 | | - # code to actually show the article goes here |
| 84 | | - |
| 85 | | - wfRunHooks('ArticleShowComplete', array(&$article)); |
| | 81 | + if (wfRunHooks('ArticleShow', array(&$article))) { |
| | 82 | + |
| | 83 | + # code to actually show the article goes here |
| | 84 | + |
| | 85 | + wfRunHooks('ArticleShowComplete', array(&$article)); |
| | 86 | + } |
| 86 | 87 | } |
| 87 | | - } |
| 88 | 88 | |
| 89 | 89 | We've cleaned up the code here by removing clumps of weird, |
| 90 | 90 | infrequently used code and moving them off somewhere else. It's much |
| — | — | @@ -96,25 +96,25 @@ |
| 97 | 97 | in showAnArticle, deleteAnArticle, exportArticle, etc., we can |
| 98 | 98 | concentrate it all in an extension file: |
| 99 | 99 | |
| 100 | | - function reverseArticleTitle($article) { |
| 101 | | - # ... |
| 102 | | - } |
| | 100 | + function reverseArticleTitle($article) { |
| | 101 | + # ... |
| | 102 | + } |
| 103 | 103 | |
| 104 | | - function reverseForExport($article) { |
| 105 | | - # ... |
| 106 | | - } |
| | 104 | + function reverseForExport($article) { |
| | 105 | + # ... |
| | 106 | + } |
| 107 | 107 | |
| 108 | 108 | The setup function for the extension just has to add its hook |
| 109 | 109 | functions to the appropriate events: |
| 110 | 110 | |
| 111 | | - setupTitleReversingExtension() { |
| 112 | | - global $wgHooks; |
| 113 | | - |
| 114 | | - $wgHooks['ArticleShow'][] = 'reverseArticleTitle'; |
| 115 | | - $wgHooks['ArticleDelete'][] = 'reverseArticleTitle'; |
| 116 | | - $wgHooks['ArticleExport'][] = 'reverseForExport'; |
| 117 | | - } |
| | 111 | + setupTitleReversingExtension() { |
| | 112 | + global $wgHooks; |
| 118 | 113 | |
| | 114 | + $wgHooks['ArticleShow'][] = 'reverseArticleTitle'; |
| | 115 | + $wgHooks['ArticleDelete'][] = 'reverseArticleTitle'; |
| | 116 | + $wgHooks['ArticleExport'][] = 'reverseForExport'; |
| | 117 | + } |
| | 118 | + |
| 119 | 119 | Having all this code related to the title-reversion option in one |
| 120 | 120 | place means that it's easier to read and understand; you don't have to |
| 121 | 121 | do a grep-find to see where the $wgReverseTitle variable is used, say. |
| — | — | @@ -124,8 +124,8 @@ |
| 125 | 125 | performance at runtime. Admins who want to have all the reversed |
| 126 | 126 | titles can add: |
| 127 | 127 | |
| 128 | | - require_once('extensions/ReverseTitle.php'); |
| 129 | | - |
| | 128 | + require_once('extensions/ReverseTitle.php'); |
| | 129 | + |
| 130 | 130 | ...to their LocalSettings.php file; those of us who don't want or need |
| 131 | 131 | it can just leave it out. |
| 132 | 132 | |
| — | — | @@ -143,31 +143,31 @@ |
| 144 | 144 | Hooks are registered by adding them to the global $wgHooks array for a |
| 145 | 145 | given event. All the following are valid ways to define hooks: |
| 146 | 146 | |
| 147 | | - $wgHooks['EventName'][] = 'someFunction'; # function, no data |
| 148 | | - $wgHooks['EventName'][] = array('someFunction', $someData); |
| 149 | | - $wgHooks['EventName'][] = array('someFunction'); # weird, but OK |
| 150 | | - |
| 151 | | - $wgHooks['EventName'][] = $object; # object only |
| 152 | | - $wgHooks['EventName'][] = array($object, 'someMethod'); |
| 153 | | - $wgHooks['EventName'][] = array($object, 'someMethod', $someData); |
| 154 | | - $wgHooks['EventName'][] = array($object); # weird but OK |
| | 147 | + $wgHooks['EventName'][] = 'someFunction'; # function, no data |
| | 148 | + $wgHooks['EventName'][] = array('someFunction', $someData); |
| | 149 | + $wgHooks['EventName'][] = array('someFunction'); # weird, but OK |
| 155 | 150 | |
| | 151 | + $wgHooks['EventName'][] = $object; # object only |
| | 152 | + $wgHooks['EventName'][] = array($object, 'someMethod'); |
| | 153 | + $wgHooks['EventName'][] = array($object, 'someMethod', $someData); |
| | 154 | + $wgHooks['EventName'][] = array($object); # weird but OK |
| | 155 | + |
| 156 | 156 | When an event occurs, the function (or object method) will be called |
| 157 | 157 | with the optional data provided as well as event-specific parameters. |
| 158 | 158 | The above examples would result in the following code being executed |
| 159 | 159 | when 'EventName' happened: |
| 160 | 160 | |
| 161 | | - # function, no data |
| 162 | | - someFunction($param1, $param2) |
| 163 | | - # function with data |
| 164 | | - someFunction($someData, $param1, $param2) |
| | 161 | + # function, no data |
| | 162 | + someFunction($param1, $param2) |
| | 163 | + # function with data |
| | 164 | + someFunction($someData, $param1, $param2) |
| 165 | 165 | |
| 166 | | - # object only |
| 167 | | - $object->onEventName($param1, $param2) |
| 168 | | - # object with method |
| 169 | | - $object->someMethod($param1, $param2) |
| 170 | | - # object with method and data |
| 171 | | - $object->someMethod($someData, $param1, $param2) |
| | 166 | + # object only |
| | 167 | + $object->onEventName($param1, $param2) |
| | 168 | + # object with method |
| | 169 | + $object->someMethod($param1, $param2) |
| | 170 | + # object with method and data |
| | 171 | + $object->someMethod($someData, $param1, $param2) |
| 172 | 172 | |
| 173 | 173 | Note that when an object is the hook, and there's no specified method, |
| 174 | 174 | the default method called is 'onEventName'. For different events this |
| — | — | @@ -176,8 +176,8 @@ |
| 177 | 177 | The extra data is useful if we want to use the same function or object |
| 178 | 178 | for different purposes. For example: |
| 179 | 179 | |
| 180 | | - $wgHooks['ArticleSaveComplete'][] = array('ircNotify', 'TimStarling'); |
| 181 | | - $wgHooks['ArticleSaveComplete'][] = array('ircNotify', 'brion'); |
| | 180 | + $wgHooks['ArticleSaveComplete'][] = array('ircNotify', 'TimStarling'); |
| | 181 | + $wgHooks['ArticleSaveComplete'][] = array('ircNotify', 'brion'); |
| 182 | 182 | |
| 183 | 183 | This code would result in ircNotify being run twice when an article is |
| 184 | 184 | saved: once for 'TimStarling', and once for 'brion'. |
| — | — | @@ -195,12 +195,12 @@ |
| 196 | 196 | users to a custom system (LDAP, another PHP program, whatever), you |
| 197 | 197 | could do: |
| 198 | 198 | |
| 199 | | - $wgHooks['UserLogin'][] = array('ldapLogin', $ldapServer); |
| 200 | | - |
| 201 | | - function ldapLogin($username, $password) { |
| 202 | | - # log user into LDAP |
| 203 | | - return false; |
| 204 | | - } |
| | 199 | + $wgHooks['UserLogin'][] = array('ldapLogin', $ldapServer); |
| | 200 | + |
| | 201 | + function ldapLogin($username, $password) { |
| | 202 | + # log user into LDAP |
| | 203 | + return false; |
| | 204 | + } |
| 205 | 205 | |
| 206 | 206 | Returning false makes less sense for events where the action is |
| 207 | 207 | complete, and will normally be ignored. |
| — | — | @@ -210,14 +210,15 @@ |
| 211 | 211 | A calling function or method uses the wfRunHooks() function to run |
| 212 | 212 | the hooks related to a particular event, like so: |
| 213 | 213 | |
| 214 | | - class Article { |
| 215 | | - # ... |
| 216 | | - function protect() { |
| 217 | | - global $wgUser; |
| 218 | | - if (wfRunHooks('ArticleProtect', array(&$this, &$wgUser))) { |
| 219 | | - # protect the article |
| 220 | | - wfRunHooks('ArticleProtectComplete', array(&$this, &$wgUser)); |
| 221 | | - } |
| | 214 | + class Article { |
| | 215 | + # ... |
| | 216 | + function protect() { |
| | 217 | + global $wgUser; |
| | 218 | + if (wfRunHooks('ArticleProtect', array(&$this, &$wgUser))) { |
| | 219 | + # protect the article |
| | 220 | + wfRunHooks('ArticleProtectComplete', array(&$this, &$wgUser)); |
| | 221 | + } |
| | 222 | + } |
| 222 | 223 | } |
| 223 | 224 | |
| 224 | 225 | wfRunHooks() returns true if the calling function should continue |