replacing the old HTML user guide with a Sphinx-managed user guide

1 files changed, 98 insertions, 0 deletions

diff --git a/user_guide_src/source/general/hooks.rst b/user_guide_src/source/general/hooks.rst
new file mode 100644
index 000000000..ab42d28a1
--- /dev/null
+++ b/user_guide_src/source/general/hooks.rst
@@ -0,0 +1,98 @@
+####################################
+Hooks - Extending the Framework Core
+####################################
+
+CodeIgniter's Hooks feature provides a means to tap into and modify the
+inner workings of the framework without hacking the core files. When
+CodeIgniter runs it follows a specific execution process, diagramed in
+the :doc:`Application Flow <../overview/appflow>` page. There may be
+instances, however, where you'd like to cause some action to take place
+at a particular stage in the execution process. For example, you might
+want to run a script right before your controllers get loaded, or right
+after, or you might want to trigger one of your own scripts in some
+other location.
+
+Enabling Hooks
+==============
+
+The hooks feature can be globally enabled/disabled by setting the
+following item in the application/config/config.php file::
+
+	$config['enable_hooks'] = TRUE;
+
+Defining a Hook
+===============
+
+Hooks are defined in application/config/hooks.php file. Each hook is
+specified as an array with this prototype::
+
+	 $hook['pre_controller'] = array(                                 'class'    => 'MyClass',                                 'function' => 'Myfunction',                                 'filename' => 'Myclass.php',                                 'filepath' => 'hooks',                                 'params'   => array('beer', 'wine', 'snacks')                                 );
+
+**Notes:**
+The array index correlates to the name of the particular hook point you
+want to use. In the above example the hook point is pre_controller. A
+list of hook points is found below. The following items should be
+defined in your associative hook array:
+
+-  **class** The name of the class you wish to invoke. If you prefer to
+   use a procedural function instead of a class, leave this item blank.
+-  **function** The function name you wish to call.
+-  **filename** The file name containing your class/function.
+-  **filepath** The name of the directory containing your script. Note:
+   Your script must be located in a directory INSIDE your application
+   folder, so the file path is relative to that folder. For example, if
+   your script is located in application/hooks, you will simply use
+   hooks as your filepath. If your script is located in
+   application/hooks/utilities you will use hooks/utilities as your
+   filepath. No trailing slash.
+-  **params** Any parameters you wish to pass to your script. This item
+   is optional.
+
+Multiple Calls to the Same Hook
+===============================
+
+If want to use the same hook point with more then one script, simply
+make your array declaration multi-dimensional, like this::
+
+	 $hook['pre_controller'][] = array(                                 'class'    => 'MyClass',                                 'function' => 'Myfunction',                                 'filename' => 'Myclass.php',                                 'filepath' => 'hooks',                                 'params'   => array('beer', 'wine', 'snacks')                                 );  $hook['pre_controller'][] = array(                                 'class'    => 'MyOtherClass',                                 'function' => 'MyOtherfunction',                                 'filename' => 'Myotherclass.php',                                 'filepath' => 'hooks',                                 'params'   => array('red', 'yellow', 'blue')                                 );
+
+Notice the brackets after each array index::
+
+	$hook['pre_controller'][]
+
+This permits you to have the same hook point with multiple scripts. The
+order you define your array will be the execution order.
+
+Hook Points
+===========
+
+The following is a list of available hook points.
+
+-  **pre_system**
+   Called very early during system execution. Only the benchmark and
+   hooks class have been loaded at this point. No routing or other
+   processes have happened.
+-  **pre_controller**
+   Called immediately prior to any of your controllers being called.
+   All base classes, routing, and security checks have been done.
+-  **post_controller_constructor**
+   Called immediately after your controller is instantiated, but prior
+   to any method calls happening.
+-  **post_controller**
+   Called immediately after your controller is fully executed.
+-  **display_override**
+   Overrides the _display() function, used to send the finalized page
+   to the web browser at the end of system execution. This permits you
+   to use your own display methodology. Note that you will need to
+   reference the CI superobject with $this->CI =& get_instance() and
+   then the finalized data will be available by calling
+   $this->CI->output->get_output()
+-  **cache_override**
+   Enables you to call your own function instead of the
+   _display_cache() function in the output class. This permits you to
+   use your own cache display mechanism.
+-  **post_system**
+   Called after the final rendered page is sent to the browser, at the
+   end of system execution after the finalized data is sent to the
+   browser.
+