From 2067d1a727e7eb5e5ffb40e967f3d1fc4c8a41b2 Mon Sep 17 00:00:00 2001 From: Derek Allard Date: Thu, 13 Nov 2008 22:59:24 +0000 Subject: Changing EOL style to LF --- user_guide/general/creating_libraries.html | 594 ++++++++++++++--------------- 1 file changed, 297 insertions(+), 297 deletions(-) (limited to 'user_guide/general/creating_libraries.html') diff --git a/user_guide/general/creating_libraries.html b/user_guide/general/creating_libraries.html index 15dfcec1e..beac1959f 100644 --- a/user_guide/general/creating_libraries.html +++ b/user_guide/general/creating_libraries.html @@ -1,298 +1,298 @@ - - - - - -Creating Libraries : CodeIgniter User Guide - - - - - - - - - - - - - - - - - - - - - -
- - - - - -

CodeIgniter User Guide Version 1.7

-
- - - - - - - - - -
- - -
- - - -
- -

Creating Libraries

- -

When we use the term "Libraries" we are normally referring to the classes that are located in the libraries -directory and described in the Class Reference of this user guide. In this case, however, we will instead describe how you can create -your own libraries within your application/libraries directory in order to maintain separation between your local resources -and the global framework resources.

- -

As an added bonus, CodeIgniter permits your libraries to extend native classes if you simply need to add some functionality -to an existing library. Or you can even replace native libraries just by placing identically named versions in your application/libraries folder.

- -

In summary:

- - - -

The page below explains these three concepts in detail.

- -

Note: The Database classes can not be extended or replaced with your own classes, -nor can the Loader class in PHP 4. All other classes are able to be replaced/extended.

- - -

Storage

- -

Your library classes should be placed within your application/libraries folder, as this is where CodeIgniter will look for them when -they are initialized.

- - -

Naming Conventions

- - - - -

The Class File

- -

Classes should have this basic prototype (Note: We are using the name Someclass purely as an example):

- -<?php if ( ! defined('BASEPATH')) exit('No direct script access allowed'); -

-class Someclass {
-
-    function some_function()
-    {
-    }
-}

-?> - - -

Using Your Class

- -

From within any of your Controller functions you can initialize your class using the standard:

- -$this->load->library('someclass'); - -

Where someclass is the file name, without the ".php" file extension. You can submit the file name capitalized or lower case. -CodeIgniter doesn't care.

- -

Once loaded you can access your class using the lower case version:

- -$this->someclass->some_function();  // Object instances will always be lower case - - - - -

Passing Parameters When Initializing Your Class

- -

In the library loading function you can dynamically pass data via the second parameter and it will be passed to your class -constructor:

- - -$params = array('type' => 'large', 'color' => 'red');
-
-$this->load->library('Someclass', $params); - -

If you use this feature you must set up your class constructor to expect data:

- -<?php if ( ! defined('BASEPATH')) exit('No direct script access allowed');
-
-class Someclass {
-
-    function Someclass($params)
-    {
-        // Do something with $params
-    }
-}

-?> - -

You can also pass parameters stored in a config file. Simply create a config file named identically to the class file name -and store it in your application/config/ folder. Note that if you dynamically pass parameters as described above, -the config file option will not be available.

- - - - - - - -

Utilizing CodeIgniter Resources within Your Library

- - -

To access CodeIgniter's native resources within your library use the get_instance() function. -This function returns the CodeIgniter super object.

- -

Normally from within your controller functions you will call any of the available CodeIgniter functions using the $this construct:

- - -$this->load->helper('url');
-$this->load->library('session');
-$this->config->item('base_url');
-etc. - - -

$this, however, only works directly within your controllers, your models, or your views. -If you would like to use CodeIgniter's classes from within your own custom classes you can do so as follows:

- - -

First, assign the CodeIgniter object to a variable:

- -$CI =& get_instance(); - -

Once you've assigned the object to a variable, you'll use that variable instead of $this:

- - -$CI =& get_instance();
-
-$CI->load->helper('url');
-$CI->load->library('session');
-$CI->config->item('base_url');
-etc. - - -

Note: You'll notice that the above get_instance() function is being passed by reference: -

-$CI =& get_instance(); -
-
-This is very important. Assigning by reference allows you to use the original CodeIgniter object rather than creating a copy of it. -

-Also, please note: If you are running PHP 4 it's usually best to avoid calling get_instance() -from within your class constructors. PHP 4 has trouble referencing the CI super object within application constructors -since objects do not exist until the class is fully instantiated.

- - -

Replacing Native Libraries with Your Versions

- -

Simply by naming your class files identically to a native library will cause CodeIgniter to use it instead of the native one. To use this -feature you must name the file and the class declaration exactly the same as the native library. For example, to replace the native Email library -you'll create a file named application/libraries/Email.php, and declare your class with:

- - -class CI_Email {

- -} - -

Note that most native classes are prefixed with CI_.

- -

To load your library you'll see the standard loading function:

- -$this->load->library('email'); - -

Note: At this time the Database classes can not be replaced with your own versions.

- - -

Extending Native Libraries

- -

If all you need to do is add some functionality to an existing library - perhaps add a function or two - then -it's overkill to replace the entire library with your version. In this case it's better to simply extend the class. -Extending a class is nearly identical to replacing a class with a couple exceptions:

- - - -

For example, to extend the native Email class you'll create a file named application/libraries/MY_Email.php, and declare your class with:

- - -class MY_Email extends CI_Email {

- -} - -

Note: If you need to use a constructor in your class make sure you extend the parent constructor:

- - - -class MY_Email extends CI_Email {
-
-    function My_Email()
-    {
-        parent::CI_Email();
-    }
-} - - -

Loading Your Sub-class

- -

To load your sub-class you'll use the standard syntax normally used. DO NOT include your prefix. For example, -to load the example above, which extends the Email class, you will use:

- -$this->load->library('email'); - -

Once loaded you will use the class variable as you normally would for the class you are extending. In the case of -the email class all calls will use:

- - -$this->email->some_function(); - - -

Setting Your Own Prefix

- -

To set your own sub-class prefix, open your application/config/config.php file and look for this item:

- -$config['subclass_prefix'] = 'MY_'; - -

Please note that all native CodeIgniter libraries are prefixed with CI_ so DO NOT use that as your prefix.

- - - -
- - - - - - + + + + + +Creating Libraries : CodeIgniter User Guide + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +

CodeIgniter User Guide Version 1.7

+
+ + + + + + + + + +
+ + +
+ + + +
+ +

Creating Libraries

+ +

When we use the term "Libraries" we are normally referring to the classes that are located in the libraries +directory and described in the Class Reference of this user guide. In this case, however, we will instead describe how you can create +your own libraries within your application/libraries directory in order to maintain separation between your local resources +and the global framework resources.

+ +

As an added bonus, CodeIgniter permits your libraries to extend native classes if you simply need to add some functionality +to an existing library. Or you can even replace native libraries just by placing identically named versions in your application/libraries folder.

+ +

In summary:

+ + + +

The page below explains these three concepts in detail.

+ +

Note: The Database classes can not be extended or replaced with your own classes, +nor can the Loader class in PHP 4. All other classes are able to be replaced/extended.

+ + +

Storage

+ +

Your library classes should be placed within your application/libraries folder, as this is where CodeIgniter will look for them when +they are initialized.

+ + +

Naming Conventions

+ + + + +

The Class File

+ +

Classes should have this basic prototype (Note: We are using the name Someclass purely as an example):

+ +<?php if ( ! defined('BASEPATH')) exit('No direct script access allowed'); +

+class Someclass {
+
+    function some_function()
+    {
+    }
+}

+?> + + +

Using Your Class

+ +

From within any of your Controller functions you can initialize your class using the standard:

+ +$this->load->library('someclass'); + +

Where someclass is the file name, without the ".php" file extension. You can submit the file name capitalized or lower case. +CodeIgniter doesn't care.

+ +

Once loaded you can access your class using the lower case version:

+ +$this->someclass->some_function();  // Object instances will always be lower case + + + + +

Passing Parameters When Initializing Your Class

+ +

In the library loading function you can dynamically pass data via the second parameter and it will be passed to your class +constructor:

+ + +$params = array('type' => 'large', 'color' => 'red');
+
+$this->load->library('Someclass', $params); + +

If you use this feature you must set up your class constructor to expect data:

+ +<?php if ( ! defined('BASEPATH')) exit('No direct script access allowed');
+
+class Someclass {
+
+    function Someclass($params)
+    {
+        // Do something with $params
+    }
+}

+?> + +

You can also pass parameters stored in a config file. Simply create a config file named identically to the class file name +and store it in your application/config/ folder. Note that if you dynamically pass parameters as described above, +the config file option will not be available.

+ + + + + + + +

Utilizing CodeIgniter Resources within Your Library

+ + +

To access CodeIgniter's native resources within your library use the get_instance() function. +This function returns the CodeIgniter super object.

+ +

Normally from within your controller functions you will call any of the available CodeIgniter functions using the $this construct:

+ + +$this->load->helper('url');
+$this->load->library('session');
+$this->config->item('base_url');
+etc. + + +

$this, however, only works directly within your controllers, your models, or your views. +If you would like to use CodeIgniter's classes from within your own custom classes you can do so as follows:

+ + +

First, assign the CodeIgniter object to a variable:

+ +$CI =& get_instance(); + +

Once you've assigned the object to a variable, you'll use that variable instead of $this:

+ + +$CI =& get_instance();
+
+$CI->load->helper('url');
+$CI->load->library('session');
+$CI->config->item('base_url');
+etc. + + +

Note: You'll notice that the above get_instance() function is being passed by reference: +

+$CI =& get_instance(); +
+
+This is very important. Assigning by reference allows you to use the original CodeIgniter object rather than creating a copy of it. +

+Also, please note: If you are running PHP 4 it's usually best to avoid calling get_instance() +from within your class constructors. PHP 4 has trouble referencing the CI super object within application constructors +since objects do not exist until the class is fully instantiated.

+ + +

Replacing Native Libraries with Your Versions

+ +

Simply by naming your class files identically to a native library will cause CodeIgniter to use it instead of the native one. To use this +feature you must name the file and the class declaration exactly the same as the native library. For example, to replace the native Email library +you'll create a file named application/libraries/Email.php, and declare your class with:

+ + +class CI_Email {

+ +} + +

Note that most native classes are prefixed with CI_.

+ +

To load your library you'll see the standard loading function:

+ +$this->load->library('email'); + +

Note: At this time the Database classes can not be replaced with your own versions.

+ + +

Extending Native Libraries

+ +

If all you need to do is add some functionality to an existing library - perhaps add a function or two - then +it's overkill to replace the entire library with your version. In this case it's better to simply extend the class. +Extending a class is nearly identical to replacing a class with a couple exceptions:

+ + + +

For example, to extend the native Email class you'll create a file named application/libraries/MY_Email.php, and declare your class with:

+ + +class MY_Email extends CI_Email {

+ +} + +

Note: If you need to use a constructor in your class make sure you extend the parent constructor:

+ + + +class MY_Email extends CI_Email {
+
+    function My_Email()
+    {
+        parent::CI_Email();
+    }
+} + + +

Loading Your Sub-class

+ +

To load your sub-class you'll use the standard syntax normally used. DO NOT include your prefix. For example, +to load the example above, which extends the Email class, you will use:

+ +$this->load->library('email'); + +

Once loaded you will use the class variable as you normally would for the class you are extending. In the case of +the email class all calls will use:

+ + +$this->email->some_function(); + + +

Setting Your Own Prefix

+ +

To set your own sub-class prefix, open your application/config/config.php file and look for this item:

+ +$config['subclass_prefix'] = 'MY_'; + +

Please note that all native CodeIgniter libraries are prefixed with CI_ so DO NOT use that as your prefix.

+ + + +
+ + + + + + \ No newline at end of file -- cgit v1.2.3-24-g4f1b