Date: Thu, 13 Nov 2008 22:59:24 +0000 Subject: Changing EOL style to LF --- user_guide/general/controllers.html | 768 ++++++++++++++++++------------------ 1 file changed, 384 insertions(+), 384 deletions(-) (limited to 'user_guide/general/controllers.html') diff --git a/user_guide/general/controllers.html b/user_guide/general/controllers.html index cb7f80eac..f11d09215 100644 --- a/user_guide/general/controllers.html +++ b/user_guide/general/controllers.html @@ -1,385 +1,385 @@ - - - - - -Controllers : CodeIgniter User Guide - - - - - - - - - - - - - - - - - - - -

- - - - - - - - - - -

- - -
- - - -

- -

Controllers

- -

Controllers are the heart of your application, as they determine how HTTP requests should be handled.

- - -

What is a Controller?
Hello World
Functions
Passing URI Segments to Your Functions
Defining a Default Controller
Remapping Function Calls
Controlling Output Data
Private Functions
Organizing Controllers into Sub-folders
Class Constructors
Reserved Function Names

- - - -

What is a Controller?

- -

A Controller is simply a class file that is named in a way that can be associated with a URI.

- -

Consider this URI:

- -example.com/index.php/blog/ - -

In the above example, CodeIgniter would attempt to find a controller named blog.php and load it.

- -

When a controller's name matches the first segment of a URI, it will be loaded.

- - -

Let's try it: Hello World!

- -

Let's create a simple controller so you can see it in action. Using your text editor, create a file called blog.php, and put the following code in it:

- - - - - - -

Then save the file to your application/controllers/ folder.

- -

Now visit the your site using a URL similar to this:

- -example.com/index.php/blog/ - -

If you did it right, you should see Hello World!.

- -

Note: Class names must start with an uppercase letter. In other words, this is valid:

- -

<?php

-class Blog extends Controller {

-

-}

-?>

- -

This is not valid:

- -

<?php

-class blog extends Controller {

-

-}

-?>

- -

Also, always make sure your controller extends the parent controller class so that it can inherit all its functions.

- - - - -

Functions

- -

In the above example the function name is index(). The "index" function is always loaded by default if the -second segment of the URI is empty. Another way to show your "Hello World" message would be this:

- -example.com/index.php/blog/index/ - -

The second segment of the URI determines which function in the controller gets called.

- -

Let's try it. Add a new function to your controller:

- - - - -

Now load the following URL to see the comment function:

- -example.com/index.php/blog/comments/ - -

You should see your new message.

- - -

Passing URI Segments to your Functions

- -

If your URI contains more then two segments they will be passed to your function as parameters.

- -

For example, lets say you have a URI like this:

- -example.com/index.php/products/shoes/sandals/123 - -

Your function will be passed URI segments 3 and 4 ("sandals" and "123"):

- -


-<?php

-class Products extends Controller {

-

-    function shoes($sandals, $id)

-    {

-        echo $sandals;

-        echo $id;

-    }

-}

-?>
-

- -

Important: If you are using the URI Routing feature, the segments -passed to your function will be the re-routed ones.

- - - -

Defining a Default Controller

- -

CodeIgniter can be told to load a default controller when a URI is not present, -as will be the case when only your site root URL is requested. To specify a default controller, open -your application/config/routes.php file and set this variable:

- -$route['default_controller'] = 'Blog'; - -

Where Blog is the name of the controller class you want used. If you now load your main index.php file without -specifying any URI segments you'll see your Hello World message by default.

- - - - -

Remapping Function Calls

- -

As noted above, the second segment of the URI typically determines which function in the controller gets called. -CodeIgniter permits you to override this behavior through the use of the _remap() function:

- -

function _remap()

-{

-    // Some code here...

-}

- -

Important: If your controller contains a function named _remap(), it will always -get called regardless of what your URI contains. It overrides the normal behavior in which the URI determines which function is called, -allowing you to define your own function routing rules.

- -

The overridden function call (typically the second segment of the URI) will be passed as a parameter the _remap() function:

- -

function _remap($method)

-{

-    if ($method == 'some_method')

-    {

-        $this->$method();

-    }

-    else

-    {

-        $this->default_method();

-    }

-}

- - - - - - -

Processing Output

- -

CodeIgniter has an output class that takes care of sending your final rendered data to the web browser automatically. More information on this can be found in the -Views and Output class pages. In some cases, however, you might want to -post-process the finalized data in some way and send it to the browser yourself. CodeIgniter permits you to -add a function named _output() to your controller that will receive the finalized output data.

- -

Important: If your controller contains a function named _output(), it will always -be called by the output class instead of echoing the finalized data directly. The first parameter of the function will contain the finalized output.

- -

Here is an example:

- -


-function _output($output)

-{

-    echo $output;

-}

- -

Please note that your _output() function will receive the data in its finalized state. Benchmark and memory usage data will be rendered, -cache files written (if you have caching enabled), and headers will be sent (if you use that feature) -before it is handed off to the _output() function. If you are using this feature the page execution timer and memory usage stats might not be perfectly accurate -since they will not take into acccount any further processing you do. For an alternate way to control output before any of the final processing is done, please see -the available methods in the Output Class.

- - -

Private Functions

- - -

In some cases you may want certain functions hidden from public access. To make a function private, simply add an -underscore as the name prefix and it will not be served via a URL request. For example, if you were to have a function like this:

- -


-function _utility()

-{

-  // some code

-}

- -

Trying to access it via the URL, like this, will not work:

- -example.com/index.php/blog/_utility/ - - - - -

Organizing Your Controllers into Sub-folders

- -

If you are building a large application you might find it convenient to organize your controllers into sub-folders. CodeIgniter permits you to do this.

- -

Simply create folders within your application/controllers directory and place your controller classes within them.

- -

Note: When using this feature the first segment of your URI must specify the folder. For example, lets say you have a controller -located here:

- -application/controllers/products/shoes.php - -

To call the above controller your URI will look something like this:

- -example.com/index.php/products/shoes/show/123 - -

Each of your sub-folders may contain a default controller which will be -called if the URL contains only the sub-folder. Simply name your default controller as specified in your -application/config/routes.php file

- - -

CodeIgniter also permits you to remap your URIs using its URI Routing feature.

- - -

Class Constructors

- - -

If you intend to use a constructor in any of your Controllers, you MUST place the following line of code in it:

- -parent::Controller(); - -

The reason this line is necessary is because your local constructor will be overriding the one in the parent controller class so we need to manually call it.

- - -

If you are not familiar with constructors, in PHP 4, a constructor is simply a function that has the exact same name as the class:

- -


-<?php

-class Blog extends Controller {

-

-       function Blog()

-       {

-            parent::Controller();

-       }

-}

-?>

- -

In PHP 5, constructors use the following syntax:

- -


-<?php

-class Blog extends Controller {

-

-       function __construct()

-       {

-            parent::Controller();

-       }

-}

-?>

- -

Constructors are useful if you need to set some default values, or run a default process when your class is instantiated. -Constructors can't return a value, but they can do some default work.

- - -

Reserved Function Names

- -

Since your controller classes will extend the main application controller you -must be careful not to name your functions identically to the ones used by that class, otherwise your local functions -will override them. See Reserved Names for a full list.

- -

That's it!

- -

That, in a nutshell, is all there is to know about controllers.

- - - -

- - - - - - + + + + + +Controllers : CodeIgniter User Guide + + + + + + + + + + + + + + + + + + + +

+ + + + + + + + + + +

+ + +
+ + + +

+ +

Controllers

+ +

Controllers are the heart of your application, as they determine how HTTP requests should be handled.

+ + +

What is a Controller?
Hello World
Functions
Passing URI Segments to Your Functions
Defining a Default Controller
Remapping Function Calls
Controlling Output Data
Private Functions
Organizing Controllers into Sub-folders
Class Constructors
Reserved Function Names

+ + + +

What is a Controller?

+ +

A Controller is simply a class file that is named in a way that can be associated with a URI.

+ +

Consider this URI:

+ +example.com/index.php/blog/ + +

In the above example, CodeIgniter would attempt to find a controller named blog.php and load it.

+ +

When a controller's name matches the first segment of a URI, it will be loaded.

+ + +

Let's try it: Hello World!

+ +

Let's create a simple controller so you can see it in action. Using your text editor, create a file called blog.php, and put the following code in it:

+ + + + + + +

Then save the file to your application/controllers/ folder.

+ +

Now visit the your site using a URL similar to this:

+ +example.com/index.php/blog/ + +

If you did it right, you should see Hello World!.

+ +

Note: Class names must start with an uppercase letter. In other words, this is valid:

+ +

<?php

+class Blog extends Controller {

+

+}

+?>

+ +

This is not valid:

+ +

<?php

+class blog extends Controller {

+

+}

+?>

+ +

Also, always make sure your controller extends the parent controller class so that it can inherit all its functions.

+ + + + +

Functions

+ +

In the above example the function name is index(). The "index" function is always loaded by default if the +second segment of the URI is empty. Another way to show your "Hello World" message would be this:

+ +example.com/index.php/blog/index/ + +

The second segment of the URI determines which function in the controller gets called.

+ +

Let's try it. Add a new function to your controller:

+ + + + +

Now load the following URL to see the comment function:

+ +example.com/index.php/blog/comments/ + +

You should see your new message.

+ + +

Passing URI Segments to your Functions

+ +

If your URI contains more then two segments they will be passed to your function as parameters.

+ +

For example, lets say you have a URI like this:

+ +example.com/index.php/products/shoes/sandals/123 + +

Your function will be passed URI segments 3 and 4 ("sandals" and "123"):

+ +


+<?php

+class Products extends Controller {

+

+    function shoes($sandals, $id)

+    {

+        echo $sandals;

+        echo $id;

+    }

+}

+?>
+

+ +

Important: If you are using the URI Routing feature, the segments +passed to your function will be the re-routed ones.

+ + + +

Defining a Default Controller

+ +

CodeIgniter can be told to load a default controller when a URI is not present, +as will be the case when only your site root URL is requested. To specify a default controller, open +your application/config/routes.php file and set this variable:

+ +$route['default_controller'] = 'Blog'; + +

Where Blog is the name of the controller class you want used. If you now load your main index.php file without +specifying any URI segments you'll see your Hello World message by default.

+ + + + +

Remapping Function Calls

+ +

As noted above, the second segment of the URI typically determines which function in the controller gets called. +CodeIgniter permits you to override this behavior through the use of the _remap() function:

+ +

function _remap()

+{

+    // Some code here...

+}

+ +

Important: If your controller contains a function named _remap(), it will always +get called regardless of what your URI contains. It overrides the normal behavior in which the URI determines which function is called, +allowing you to define your own function routing rules.

+ +

The overridden function call (typically the second segment of the URI) will be passed as a parameter the _remap() function:

+ +

function _remap($method)

+{

+    if ($method == 'some_method')

+    {

+        $this->$method();

+    }

+    else

+    {

+        $this->default_method();

+    }

+}

+ + + + + + +

Processing Output

+ +

CodeIgniter has an output class that takes care of sending your final rendered data to the web browser automatically. More information on this can be found in the +Views and Output class pages. In some cases, however, you might want to +post-process the finalized data in some way and send it to the browser yourself. CodeIgniter permits you to +add a function named _output() to your controller that will receive the finalized output data.

+ +

Important: If your controller contains a function named _output(), it will always +be called by the output class instead of echoing the finalized data directly. The first parameter of the function will contain the finalized output.

+ +

Here is an example:

+ +


+function _output($output)

+{

+    echo $output;

+}

+ +

Please note that your _output() function will receive the data in its finalized state. Benchmark and memory usage data will be rendered, +cache files written (if you have caching enabled), and headers will be sent (if you use that feature) +before it is handed off to the _output() function. If you are using this feature the page execution timer and memory usage stats might not be perfectly accurate +since they will not take into acccount any further processing you do. For an alternate way to control output before any of the final processing is done, please see +the available methods in the Output Class.

+ + +

Private Functions

+ + +

In some cases you may want certain functions hidden from public access. To make a function private, simply add an +underscore as the name prefix and it will not be served via a URL request. For example, if you were to have a function like this:

+ +


+function _utility()

+{

+  // some code

+}

+ +

Trying to access it via the URL, like this, will not work:

+ +example.com/index.php/blog/_utility/ + + + + +

Organizing Your Controllers into Sub-folders

+ +

If you are building a large application you might find it convenient to organize your controllers into sub-folders. CodeIgniter permits you to do this.

+ +

Simply create folders within your application/controllers directory and place your controller classes within them.

+ +

Note: When using this feature the first segment of your URI must specify the folder. For example, lets say you have a controller +located here:

+ +application/controllers/products/shoes.php + +

To call the above controller your URI will look something like this:

+ +example.com/index.php/products/shoes/show/123 + +

Each of your sub-folders may contain a default controller which will be +called if the URL contains only the sub-folder. Simply name your default controller as specified in your +application/config/routes.php file

+ + +

CodeIgniter also permits you to remap your URIs using its URI Routing feature.

+ + +

Class Constructors

+ + +

If you intend to use a constructor in any of your Controllers, you MUST place the following line of code in it:

+ +parent::Controller(); + +

The reason this line is necessary is because your local constructor will be overriding the one in the parent controller class so we need to manually call it.

+ + +

If you are not familiar with constructors, in PHP 4, a constructor is simply a function that has the exact same name as the class:

+ +


+<?php

+class Blog extends Controller {

+

+       function Blog()

+       {

+            parent::Controller();

+       }

+}

+?>

+ +

In PHP 5, constructors use the following syntax:

+ +


+<?php

+class Blog extends Controller {

+

+       function __construct()

+       {

+            parent::Controller();

+       }

+}

+?>

+ +

Constructors are useful if you need to set some default values, or run a default process when your class is instantiated. +Constructors can't return a value, but they can do some default work.

+ + +

Reserved Function Names

+ +

Since your controller classes will extend the main application controller you +must be careful not to name your functions identically to the ones used by that class, otherwise your local functions +will override them. See Reserved Names for a full list.

+ +

That's it!

+ +

That, in a nutshell, is all there is to know about controllers.

+ + + +

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

CodeIgniter User Guide Version 1.7

Controllers

What is a Controller?

Let's try it: Hello World!

Functions

Passing URI Segments to your Functions

Defining a Default Controller

Remapping Function Calls

Processing Output

Private Functions

Organizing Your Controllers into Sub-folders

Class Constructors

Reserved Function Names

That's it!

CodeIgniter User Guide Version 1.7

Controllers

What is a Controller?

Let's try it: Hello World!

Functions

Passing URI Segments to your Functions

Defining a Default Controller

Remapping Function Calls

Processing Output

Private Functions

Organizing Your Controllers into Sub-folders

Class Constructors

Reserved Function Names

That's it!