Documentation/general/extensions.html

   1 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   2 <head>
   3         <title>CarbonPHP Documentation</title>
   4         <style type="text/css">
   5                 * {
   6                         margin: 0;
   7                         padding: 0;
   8                 }
   9
  10                 html {
  11                         font-family: "Lucida Sans Unicode", "Lucida Grande";
  12                         font-size: 12px;
  13                 }
  14
  15                 body {
  16                         background: #fff;
  17                         color: #666;
  18                 }
  19
  20                 h1 {
  21                         font-size: 15px;
  22                         font-weight: bold;
  23                         margin-bottom: 5px;
  24                 }
  25
  26                 ol, ul {
  27                         margin: 10px 0 10px 0;
  28                         list-style-position: inside;
  29                 }
  30
  31                 p {
  32                         margin: 5px 0 5px 0;
  33                 }
  34
  35                 .content {
  36                         border: 1px dotted #444;
  37                         margin: 10px;
  38                         padding: 10px;
  39                         text-align: justify;
  40                         width: 700px;
  41                 }
  42
  43                 .example {
  44                         border: 1px solid #ccc;
  45                         background: #eee;
  46                         margin: 10px;
  47                         padding: 10px;
  48                 }
  49         </style>
  50 </head>
  51
  52 <body>
  53         <div class="content">
  54                 <h1>Extending the Framework Core With Extensions</h1>
  55
  56                 <p>CarbonPHP has the feature to allow users to extend the framework core without hacking the core classes.
  57                 When CarbonPHP runs it follows a specific flow.  There are some times when you might want an action to occur
  58                 at a stage during the execution.  If you want to run a method right before the controller gets loaded you
  59                 can declare an extension to do this.</p>
  60         </div>
  61
  62         <div class="content">
  63                 <h1>Enabling Extensions</h1>
  64
  65                 <p>The extensions feature can be enabled or disabled by changing the item in the
  66                 <b>application/config/config.php</b> configuration file.</p>
  67
  68                 <div class="example">
  69                         $config['enable_extensions'] = true;
  70                 </div>
  71         </div>
  72
  73         <div class="content">
  74                 <h1>Declaring an Extension</h1>
  75
  76                 <p>Extensions are declared in the <b>application/config/extensions.php</b> configuration file.  Each extension
  77                 follows the following prototype.</p>
  78
  79                 <div class="example">
  80                         $extension['pre_controller'] = array(<br />
  81                         &nbsp;&nbsp;&nbsp;&nbsp;'class' => 'Ext_class',<br />
  82                         &nbsp;&nbsp;&nbsp;&nbsp;'method' => 'ExtMethod',<br />
  83                         &nbsp;&nbsp;&nbsp;&nbsp;'filename' => 'Ext_class.php',<br />
  84                         &nbsp;&nbsp;&nbsp;&nbsp;'filepath' => 'extensions',<br />
  85                         &nbsp;&nbsp;&nbsp;&nbsp;'params' => array('small', 'medium', 'large')<br />
  86                         );<br />
  87                 </div>
  88
  89                 <p><i>Note</i>: the array index correlates to the name of the extension you wish to use.  In the above example
  90                 the extension point is <b>pre_controller</b>.  The list of available extension points are outlined below.</p>
  91
  92                 <ul>
  93                         <li><b>class</b> - the name of the class you wish to invoke for the extension.  You can use a standard
  94                         procedural function by leaving this index blank.</li>
  95                         <li><b>method</b> - the name of the method or function you wish to call.</li>
  96                         <li><b>filename</b> - the name of the file containing the class method or function.</li>
  97                         <li><b>filepath</b> - the name of the directory containing the file.  The file must be located inside
  98                         the <b>application/</b> directory.  So the filepath is relative to this directory.</li>
  99                         <li><b>params</b> - Any parameters you wish to pass to your file.  This is optional.</li>
 100                 </ul>
 101         </div>
 102
 103         <div class="content">
 104                 <h1>Calling an Extension Multiple Times</h1>
 105
 106                 <p>If you wish to use the same extension point with more than once, you simply just create a multi-dimensional
 107                 array.</p>
 108
 109                 <div class="example">
 110                         $extension['pre_controller']<b>[]</b> = array(<br />
 111                         &nbsp;&nbsp;&nbsp;&nbsp;'class' => 'Ext_class',<br />
 112                         &nbsp;&nbsp;&nbsp;&nbsp;'method' => 'ExtMethod',<br />
 113                         &nbsp;&nbsp;&nbsp;&nbsp;'filename' => 'Ext_class.php',<br />
 114                         &nbsp;&nbsp;&nbsp;&nbsp;'filepath' => 'extensions',<br />
 115                         &nbsp;&nbsp;&nbsp;&nbsp;'params' => array('small', 'medium', 'large')<br />
 116                         );<br />
 117                         <br />
 118                         $extension['pre_controller']<b>[]</b> = array(<br />
 119                         &nbsp;&nbsp;&nbsp;&nbsp;'class' => 'Ext_otherclass',<br />
 120                         &nbsp;&nbsp;&nbsp;&nbsp;'method' => 'ExtOtherMethod',<br />
 121                         &nbsp;&nbsp;&nbsp;&nbsp;'filename' => 'Ext_otherclass.php',<br />
 122                         &nbsp;&nbsp;&nbsp;&nbsp;'filepath' => 'extensions',<br />
 123                         &nbsp;&nbsp;&nbsp;&nbsp;'params' => array('blue', 'red', 'green')<br />
 124                         );<br />
 125                 </div>
 126
 127                 <p><i>Note</i>: the order in which you declare the array is the order in which they will get executed.</p>
 128         </div>
 129
 130         <div class="content">
 131                 <h1>Extension Points</h1>
 132
 133                 <p>The following is a list of extension points that you can use.</p>
 134
 135                 <ul>
 136                         <li><b>pre_system</b> - Called during the early stage of system execution.  Only the benchmark and
 137                         extensions classes have been loaded.  No routing or other processes have occured.</li>
 138                         <li><b>pre_controller</b> - Called immediately prior to any controllers being called.  All core classes,
 139                         routing, and security checks have occured.</li>
 140                         <li><b>post_controller_constructor</b> - Called immidiately after the controllers constructor is called,
 141                         but before any class method is called.</li>
 142                         <li><b>post_controller</b> - Called immediately after the controller has finished executing.</li>
 143                         <li><b>display_override</b> - Overrides the <b>_display()</b> method.  You can get the final data by
 144                         calling the <b>$this->output->get_output()</b> method.</li>
 145                         <li><b>cache_override</b> - Overrides the <b>_display_cache()</b> method in the output class.  This
 146                         allows you to use your own caching solution.</li>
 147                         <li><b>scaffolding_override</b> - Allows a scaffolding requests to trigger your own class instead.</li>
 148                         <li><b>post_system</b> - Called after the final rendered page has been sent to the browser.</li>
 149                 </ul>
 150         </div>
 151 </body>
 152
 153 </html>