From 8ede1a2ecbb62577afd32996956c5feaf7ddf9b6 Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Wed, 5 Oct 2011 13:34:52 -0500 Subject: replacing the old HTML user guide with a Sphinx-managed user guide --- user_guide_src/source/general/controllers.rst | 258 ++++++++++++++++++++++++++ 1 file changed, 258 insertions(+) create mode 100644 user_guide_src/source/general/controllers.rst (limited to 'user_guide_src/source/general/controllers.rst') diff --git a/user_guide_src/source/general/controllers.rst b/user_guide_src/source/general/controllers.rst new file mode 100644 index 000000000..8f02df21f --- /dev/null +++ b/user_guide_src/source/general/controllers.rst @@ -0,0 +1,258 @@ +########### +Controllers +########### + +Controllers are the heart of your application, as they determine how +HTTP requests should be handled. + +- `What is a Controller? <#what>`_ +- `Hello World <#hello>`_ +- `Functions <#functions>`_ +- `Passing URI Segments to Your Functions <#passinguri>`_ +- `Defining a Default Controller <#default>`_ +- `Remapping Function Calls <#remapping>`_ +- `Controlling Output Data <#output>`_ +- `Private Functions <#private>`_ +- `Organizing Controllers into Sub-folders <#subfolders>`_ +- `Class Constructors <#constructors>`_ +- `Reserved Function Names <#reserved>`_ + +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:: + + + +This is **not** valid:: + + + +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"):: + + + +.. important:: If you are using the :doc:`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:: + + public 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 to the _remap() function:: + + public function _remap($method) {     if ($method == 'some_method')     {         $this->$method();     }     else     {         $this->default_method();     } } + +Any extra segments after the method name are passed into _remap() as an +optional second parameter. This array can be used in combination with +PHP's `call_user_func_array `_ +to emulate CodeIgniter's default behavior. + +:: + + public function _remap($method, $params = array()) {     $method = 'process_'.$method;     if (method_exists($this, $method))     {         return call_user_func_array(array($this, $method), $params);     }     show_404(); } + +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 :doc::doc:`Views ` and `Output +class <../libraries/output>` 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:: + + public 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 :doc:`feature <../libraries/output>`) before it is +handed off to the _output() function. +To have your controller's output cached properly, its _output() method +can use:: + + if ($this->output->cache_expiration > 0) {     $this->output->_write_cache($output); } + +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 :doc:`Output Class <../libraries/output>`. + +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:: + + private 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 :doc:`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::__construct(); + +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. + +:: + + + +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 :doc:`Reserved Names ` for a full +list. + +That's it! +========== + +That, in a nutshell, is all there is to know about controllers. -- cgit v1.2.3-24-g4f1b From e69b45663f06e84b3257fcd56616e299708599d1 Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Wed, 5 Oct 2011 17:30:50 -0500 Subject: fixed code spacing in Controllers general docs --- user_guide_src/source/general/controllers.rst | 141 ++++++++++++++++++++------ 1 file changed, 109 insertions(+), 32 deletions(-) (limited to 'user_guide_src/source/general/controllers.rst') diff --git a/user_guide_src/source/general/controllers.rst b/user_guide_src/source/general/controllers.rst index 8f02df21f..4d6e8366c 100644 --- a/user_guide_src/source/general/controllers.rst +++ b/user_guide_src/source/general/controllers.rst @@ -38,10 +38,18 @@ 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: +in it:: + + - Then save the file to your application/controllers/ folder. Now visit the your site using a URL similar to this:: @@ -53,11 +61,20 @@ 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:: - + + This is **not** valid:: - + Also, always make sure your controller extends the parent controller class so that it can inherit all its functions. @@ -74,11 +91,23 @@ empty. Another way to show your "Hello World" message would be this:: **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: +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/ @@ -97,7 +126,16 @@ For example, lets say you have a URI like this:: Your function will be passed URI segments 3 and 4 ("sandals" and "123"):: - + .. important:: If you are using the :doc:`URI Routing ` feature, the segments passed to your function will be the re-routed @@ -124,7 +162,10 @@ 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:: - public function _remap() {     // Some code here... } + public 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 @@ -134,7 +175,17 @@ override this behavior through the use of the _remap() function:: The overridden function call (typically the second segment of the URI) will be passed as a parameter to the _remap() function:: - public function _remap($method) {     if ($method == 'some_method')     {         $this->$method();     }     else     {         $this->default_method();     } } + public function _remap($method) + { + if ($method == 'some_method') + { + $this->$method(); + } + else + { + $this->default_method(); + } + } Any extra segments after the method name are passed into _remap() as an optional second parameter. This array can be used in combination with @@ -143,7 +194,15 @@ to emulate CodeIgniter's default behavior. :: - public function _remap($method, $params = array()) {     $method = 'process_'.$method;     if (method_exists($this, $method))     {         return call_user_func_array(array($this, $method), $params);     }     show_404(); } + public function _remap($method, $params = array()) + { + $method = 'process_'.$method; + if (method_exists($this, $method)) + { + return call_user_func_array(array($this, $method), $params); + } + show_404(); + } Processing Output ================= @@ -164,23 +223,29 @@ data. Here is an example:: - public 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 :doc:`feature <../libraries/output>`) before it is -handed off to the _output() function. -To have your controller's output cached properly, its _output() method -can use:: - - if ($this->output->cache_expiration > 0) {     $this->output->_write_cache($output); } - -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 :doc:`Output Class <../libraries/output>`. + public function _output($output) + { + echo $output; + } + +.. note:: 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 :doc:`feature <../libraries/output>`) before it is + handed off to the _output() function. + To have your controller's output cached properly, its _output() method + can use:: + + if ($this->output->cache_expiration > 0) + { + $this->output->_write_cache($output); + } + + 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 :doc:`Output Class <../libraries/output>`. Private Functions ================= @@ -190,7 +255,10 @@ 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:: - private function _utility() {   // some code } + private function _utility() + { + // some code + } Trying to access it via the URL, like this, will not work:: @@ -237,7 +305,16 @@ manually call it. :: - + Constructors are useful if you need to set some default values, or run a default process when your class is instantiated. Constructors can't -- cgit v1.2.3-24-g4f1b From 5b3ea1ac070882c09eb6cb93f2ca6628ec42d64d Mon Sep 17 00:00:00 2001 From: Joseph Wensley Date: Thu, 6 Oct 2011 20:54:32 -0400 Subject: change hardcoded page docs to use generated ones escape "http://" that was getting linked formatting some tables --- user_guide_src/source/general/controllers.rst | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) (limited to 'user_guide_src/source/general/controllers.rst') diff --git a/user_guide_src/source/general/controllers.rst b/user_guide_src/source/general/controllers.rst index 4d6e8366c..c3c19cc62 100644 --- a/user_guide_src/source/general/controllers.rst +++ b/user_guide_src/source/general/controllers.rst @@ -5,17 +5,7 @@ Controllers Controllers are the heart of your application, as they determine how HTTP requests should be handled. -- `What is a Controller? <#what>`_ -- `Hello World <#hello>`_ -- `Functions <#functions>`_ -- `Passing URI Segments to Your Functions <#passinguri>`_ -- `Defining a Default Controller <#default>`_ -- `Remapping Function Calls <#remapping>`_ -- `Controlling Output Data <#output>`_ -- `Private Functions <#private>`_ -- `Organizing Controllers into Sub-folders <#subfolders>`_ -- `Class Constructors <#constructors>`_ -- `Reserved Function Names <#reserved>`_ +.. contents:: Page Contents What is a Controller? ===================== -- cgit v1.2.3-24-g4f1b From 02df61fd8bb71ee1a19b32db24d01017ddf65131 Mon Sep 17 00:00:00 2001 From: purwandi Date: Fri, 7 Oct 2011 15:33:40 +0700 Subject: Fix Controllers on User Guide --- user_guide_src/source/general/controllers.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) (limited to 'user_guide_src/source/general/controllers.rst') diff --git a/user_guide_src/source/general/controllers.rst b/user_guide_src/source/general/controllers.rst index c3c19cc62..6e5079419 100644 --- a/user_guide_src/source/general/controllers.rst +++ b/user_guide_src/source/general/controllers.rst @@ -10,8 +10,8 @@ HTTP requests should be handled. What is a Controller? ===================== -A Controller is simply a class file that is named in a way that can be -associated with a URI. +**A Controller is simply a class file that is named in a way that can be +associated with a URI.** Consider this URI:: @@ -136,7 +136,7 @@ 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 +To specify a default controller, open your **application/config/routes.php** file and set this variable:: $route['default_controller'] = 'Blog'; @@ -199,8 +199,7 @@ 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 :doc::doc:`Views ` and `Output -class <../libraries/output>` pages. In some cases, however, you +can be found in the :doc:`Views ` and :doc:`Output class <../libraries/output>` 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 -- cgit v1.2.3-24-g4f1b