Documentation/general/creating_libraries.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>Creating Your Own Libraries</h1>
  55
  56                 <p>Libraries in CarbonPHP are simply PHP classes stored in the <b>carbon/libraries/</b> directory.  We will
  57                 tell you how to create your own CarbonPHP libraries within the <b>application/libraries/</b> directory.
  58                 This allows you to keep your libraries and the CarbonPHP libraries separate.</p>
  59
  60                 <p>CarbonPHP also allows you to extend the CarbonPHP libraries with your own libraries allowing you to add
  61                 functionality to the existing libraries.  You can even replace existing libraries with your own.</p>
  62
  63                 <p><i>Note</i>: you cannot replace or extend the CarbonPHP database classes.  Every other library can be
  64                 replaced or extended.</p>
  65         </div>
  66
  67         <div class="content">
  68                 <h1>Storing Your Libraries</h1>
  69
  70                 <p>As desribed above you should place your own libraries in the <b>application/libraries/</b> directory.
  71                 This is the first directory that CarbonPHP looks in for loading libraries.</p>
  72         </div>
  73
  74         <div class="content">
  75                 <h1>Naming Your Libraries</h1>
  76
  77                 <p>File names for your libraries should be capitalised, like <b>Mylibrary.php</b>.  Class declarations must
  78                 be capitalised just like file names, <b>class Myclass</b>.  Class names and file names must match.</p>
  79         </div>
  80
  81         <div class="content">
  82                 <h1>Class File Skeleton</h1>
  83
  84                 <p>Classes for libraries should have the basic skeleton, the name <b>Some_library</b> is an example.</p>
  85
  86                 <div class="example">
  87                         &lt;?php<br />
  88                         <br />
  89                         if (!defined('CARBON_PATH'))<br />
  90                         &#123;<br />
  91                         &nbsp;&nbsp;&nbsp;&nbsp;exit('Direct script access is not allowed.');<br />
  92                         &#125;<br />
  93                         <br />
  94                         class Some_library<br />
  95                         &#123;<br />
  96                         &nbsp;&nbsp;&nbsp;&nbsp;public function some_function()<br />
  97                         &nbsp;&nbsp;&nbsp;&nbsp;&#123;<br />
  98                         &nbsp;&nbsp;&nbsp;&nbsp;&#125;<br />
  99                         &#125;<br />
 100                         <br />
 101                         ?&gt;
 102                 </div>
 103         </div>
 104
 105         <div class="content">
 106                 <h1>Using Your Libraries</h1>
 107
 108                 <p>As with any other library, you can load your library the same way within your controllers.</p>
 109
 110                 <div class="example">
 111                         $this->load->library('<b>some_library</b>');
 112                 </div>
 113
 114                 <p>Where <b>some_library</b> is the name of your library.  You can use the capitalised and lower case name,
 115                 CarbonPHP can use either.  Once you have loaded your library you can use it by accessing it the same way
 116                 as any other library.</p>
 117
 118                 <div class="example">
 119                         $this-><b>some_library</b>->some_function();
 120                 </div>
 121         </div>
 122
 123         <div class="content">
 124                 <h1>Passing Parameters When Initialising Your Library</h1>
 125
 126                 <p>When you load a library you can pass data via the second parameter and it will be passed to the constructor
 127                 of the library class.</p>
 128
 129                 <div class="example">
 130                         $params = array('Color' => 'Red', 'Size' => 'Small');<br />
 131                         <br />
 132                         $this->load->library('Some_library, <b>$params</b>);
 133                 </div>
 134
 135                 <p>When you do this, you will have to create your constructor so that the constructor expects data to be
 136                 passed to it.</p>
 137
 138                 <div class="example">
 139                         &lt;?php<br />
 140                         <br />
 141                         if (!defined('CARBON_PATH'))<br />
 142                         &#123;<br />
 143                         &nbsp;&nbsp;&nbsp;&nbsp;exit('Direct script access is not allowed.');<br />
 144                         &#125;<br />
 145                         <br />
 146                         class Some_library<br />
 147                         &#123;<br />
 148                         &nbsp;&nbsp;&nbsp;&nbsp;public function __construct($params)<br />
 149                         &nbsp;&nbsp;&nbsp;&nbsp;&#123;<br />
 150                         &nbsp;&nbsp;&nbsp;&nbsp;// Use the $params variable<br />
 151                         &nbsp;&nbsp;&nbsp;&nbsp;&#125;<br />
 152                         &#125;<br />
 153                         <br />
 154                         ?&gt;
 155                 </div>
 156
 157                 <p><i>Note</i>: you are able to pass parameters stored in a configuration file.  You can simply create the
 158                 configuration file stored in <b>application/config/</b> directory.  The configuration file must be identically
 159                 to the library.  If you pass data as described above, this option is not available to you.</p>
 160         </div>
 161
 162         <div class="content">
 163                 <h1>Using CarbonPHP Resources in Your Library</h1>
 164
 165                 <p>You can access the resources in CarbonPHP by calling the <b>get_instance()</b> function.  This function
 166                 returns the CarbonPHP object.  Usually within your controller methods you can access the <b>$this</b>
 167                 variable.</p>
 168
 169                 <div class="example">
 170                         <b>$this</b>->load->utility('form');<br />
 171                         <b>$this</b>->load->library('pagination');<br />
 172                         <b>$this</b>->config->get_item_value('base_url');
 173                 </div>
 174
 175                 <p>The <b>$this</b> variable is only available within your controllers, models, and views.  If you would like
 176                 to access CarbonPHP's libraries and classes within your own library you must do the following.</p>
 177
 178                 <div class="example">
 179                         $carbon =&amp; get_instance();
 180                 </div>
 181
 182                 <p>Once the object has been assigned to a variable, you can use that variable instead of the <b>$this</b>
 183                 variable.</p>
 184
 185                 <div class="example">
 186                         $carbon =&amp; get_instance();<br />
 187                         <br />
 188                         <b>$carbon</b>->load->utility('form');<br />
 189                         <b>$carbon</b>->load->library('pagination');<br />
 190                         <b>$carbon</b>->config->get_item_value('base_url');
 191                 </div>
 192
 193                 <p><i>Note</i>: please note that when <b>get_instance()</b> is being passed by reference.  This is important
 194                 because assigning by reference means you use the original CarbonPHP object instead of creating a copy of it.</p>
 195         </div>
 196
 197         <div class="content">
 198                 <h1>Replacing CarbonPHP Libraries</h1>
 199
 200                 <p>To simply replace the CarbonPHP libraries you just need to name your library the exact same.  This will make
 201                 CarbonPHP use that library instead of the CarbonPHP one.  For example if you were going to replace the
 202                 pagination library, you will create the file <b>application/libraries/Pagination.php</b> and declare the class
 203                 as the following.</p>
 204
 205                 <div class="example">
 206                         &lt;?php<br />
 207                         <br />
 208                         if (!defined('CARBON_PATH'))<br />
 209                         &#123;<br />
 210                         &nbsp;&nbsp;&nbsp;&nbsp;exit('Direct script access is not allowed.');<br />
 211                         &#125;<br />
 212                         <br />
 213                         class Carbon_Pagination<br />
 214                         &#123;<br />
 215                         <br />
 216                         &#125;<br />
 217                         <br />
 218                         ?&gt;
 219                 </div>
 220
 221                 <p><i>Note</i>: CarbonPHP classes are prefixed with <b>Carbon_</b> and classes you intend to replace them with
 222                 must follow this as well.</p>
 223
 224                 <p>To load your library you use the same standard method of loading libraries.</p>
 225
 226                 <div class="example">
 227                         $this->load->library('<b>pagination</b>');
 228                 </div>
 229
 230                 <p><b>Note</b>: as previously stated, database classes cannot be replaced.</p>
 231         </div>
 232
 233         <div class="content">
 234                 <h1>Extending CarbonPHP Libraries</h1>
 235
 236                 <p>If you only want to add a little functionality to an existing CarbonPHP library, then maybe adding one
 237                 or two methods, then it's overkill to fully replace the CarbonPHP library.  It is better in this case to
 238                 extend the existing library.  To extend a library it is nearly exactly the same as replacing a library, minus
 239                 some differences.</p>
 240
 241                 <ul>
 242                         <li>The class declaration must extend the parent class.</li>
 243                         <li>The new class name and file name must be prefixed with the subclass prefix.</li>
 244                 </ul>
 245
 246                 <p>The subclass prefix is configurable in the configuration file.  For example if we were going to extend the
 247                 pagination library, we would create the file <b>application/libraries/Sub_Pagination.php</b> and declare the
 248                 class as below.</p>
 249
 250                 <div class="example">
 251                         &lt;?php<br />
 252                         <br />
 253                         if (!defined('CARBON_PATH'))<br />
 254                         &#123;<br />
 255                         &nbsp;&nbsp;&nbsp;&nbsp;exit('Direct script access is not allowed.');<br />
 256                         &#125;<br />
 257                         <br />
 258                         class Sub_Pagination extends Carbon_Pagination<br />
 259                         &#123;<br />
 260                         <br />
 261                         &#125;<br />
 262                         <br />
 263                         ?&gt;
 264                 </div>
 265
 266                 <p><i>Note</i>: if you decide to use a constructor in your subclass you must remember to call the parent
 267                 classes constructor.</p>
 268
 269                 <div class="example">
 270                         &lt;?php<br />
 271                         <br />
 272                         if (!defined('CARBON_PATH'))<br />
 273                         &#123;<br />
 274                         &nbsp;&nbsp;&nbsp;&nbsp;exit('Direct script access is not allowed.');<br />
 275                         &#125;<br />
 276                         <br />
 277                         class Sub_Pagination extends Carbon_Pagination<br />
 278                         &#123;<br />
 279                         &nbsp;&nbsp;&nbsp;&nbsp;public function __construct()<br />
 280                         &nbsp;&nbsp;&nbsp;&nbsp;&#123;<br />
 281                         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;parent::__construct();<br />
 282                         &nbsp;&nbsp;&nbsp;&nbsp;&#125;<br />
 283                         &#125;<br />
 284                         <br />
 285                         ?&gt;
 286                 </div>
 287
 288                 <p>To load your subclass you use the standard method of loading libraries.  Although you do <b>not</b> include
 289                 the prefix in the name when loading.</p>
 290
 291                 <div class="example">
 292                         $this->load->library('<b>pagination</b>');
 293                 </div>
 294
 295                 <p>Once the library is loaded you can access it as you would normally.  The extended methods will be available
 296                 to you for calling.</p>
 297
 298                 <div class="example">
 299                         $this-><b>pagination</b>->new_function();
 300                 </div>
 301
 302                 <p>You can set your own subclass prefix in the configuration file <b>application/config/config.php</b> and
 303                 edit the <b>subclass_prefix</b> value.</p>
 304
 305                 <div class="example">
 306                         $config['subclass_prefix'] = 'Sub_';
 307                 </div>
 308         </div>
 309 </body>
 310
 311 </html>