Added some of the HMVC documentation

Signed-off-by: dchill42 <dchill42@gmail.com>

user_guide_src/source/general/controllers.rst

@@ -280,6 +280,47 @@ controller as specified in your application/config/routes.php file
 CodeIgniter also permits you to remap your URIs using its :doc:`URI
 Routing <routing>` feature.
 
+Loading Sub-Controllers
+=======================
+
+The Hierarchical aspect of CodeIgniter's HMVC pattern allows you to pass
+control to another Controller to handle part of a task. This is achieved
+by calling::
+
+	$this->load->controller('subhandler');
+
+The first parameter to the Controller loader function is a URI string,
+just like those explained above, except you don't specify a host or
+index.php. The previous example would run the same Controller function as::
+
+	example.com/index.php/subhandler/
+
+In fact, any Controller in your application may be run either from the
+request URL or through the Controller loader. The difference is that the
+Controller routed by the request has primary control over the whole
+application, whereas one loaded afterwards plays a secondary role. In
+order to identify which Controller was routed, it gets a special "handle"
+on the CodeIgniter root object::
+
+	$this->routed;
+
+Any time a part of your application needs to reference the top Controller,
+this is how to identify it. Likewise, if a Controller needs to determine
+whether it has been routed or called somewhere in the hierarchy, it can
+compare itself to the routed Controller object::
+
+	if ($this === $this->routed)
+	{
+		// We are the top Controller!
+	}
+	else
+	{
+		// Some other Controller called us to do a job
+	}
+
+More information about loading Controllers is available on the
+:ref:`Loader <load-controller>` page.
+
 Class Constructors
 ==================
 
@@ -321,4 +362,4 @@ list.
 That's it!
 ==========
 
-That, in a nutshell, is all there is to know about controllers.
+That, in a nutshell, is all there is to know about controllers.

user_guide_src/source/index.rst

@@ -40,7 +40,7 @@ Introduction
 - :doc:`overview/cheatsheets`
 - :doc:`overview/features`
 - :doc:`overview/appflow`
-- :doc:`overview/mvc`
+- :doc:`overview/hmvc`
 - :doc:`overview/goals`
 
 ********

user_guide_src/source/libraries/loader.rst

@@ -6,7 +6,9 @@ Loader, as the name suggests, is used to load elements. These elements
 can be libraries (classes) :doc:`View files <../general/views>`,
 :doc:`Drivers <../general/drivers>`,
 :doc:`Helpers <../general/helpers>`,
-:doc:`Models <../general/models>`, or your own files.
+:doc:`Models <../general/models>`,
+:doc:`Controllers <../general/controllers>`,
+or your own files.
 
 .. note:: This class is initialized automatically by the system so there
 	is no need to do it manually.
@@ -203,6 +205,31 @@ specify it via the second parameter of the loading function::
 
 	$this->fubar->function();
 
+.. _load-controller:
+
+$this->load->controller('controller_name', 'object_name', $call)
+================================================================
+
+This function loads a sub-Controller and calls the appropriate function::
+
+	$this->load->controller('subhandler/task');
+
+The call above would load the Subhandler Controller, make it accessible as
+$this->subhandler, and pass control to the task() function. You may also 
+assign an alternate object name::
+
+	$this->load->controller('weirdness', 'normal');
+
+This would make the Weirdness Controller accessible as $this->normal, and
+call its index() function.
+
+Sometimes, you may want to load the controller, but not call any of its
+functions yet::
+
+	$this->load->controller('later', '', FALSE);
+
+You could then call $this->later->*some_function*() when the time is right.
+
 $this->load->database('options', true/false)
 ============================================
 

user_guide_src/source/overview/appflow.rst

@@ -14,10 +14,60 @@ The following graphic illustrates how data flows throughout the system:
    the normal system execution.
 #. Security. Before the application controller is loaded, the HTTP
    request and any user submitted data is filtered for security.
-#. The Controller loads the model, core libraries, helpers, and any
-   other resources needed to process the specific request.
+#. The Controller loads the model, helpers, and any other resources
+   needed to process the specific request. It may also load and run
+   sub-Controllers to help handle the task at hand.
 #. The finalized View is rendered then sent to the web browser to be
    seen. If caching is enabled, the view is cached first so that on
    subsequent requests it can be served.
 
-.. |CodeIgniter application flow| image:: ../images/appflowchart.gif
+For those who want to fully understand the details of the CodeIgniter
+application lifecycle, and especially those who wish to modify CodeIgniter's
+behavior through :doc:`extensions <../general/core_classes>` and/or
+:doc:`hooks <../general/hooks>`, the entire sequence follows:
+
+#. Assess environment, paths, and overrides in index.php and set path constants
+#. Define CI version
+#. Read config.php and autoload.php files from the application path
+#. Apply $assign_to_config overrides if present
+#. Autoload package paths
+#. Load CodeIgniter extension class if present
+#. Instantiate the CodeIgniter object
+#. Register the exception handler
+#. Disable magic quotes for PHP < 5.4
+#. Load :doc:`Benchmark <../libraries/benchmark>` class
+#. *Mark total execution start time*
+#. *Mark base class loading start time*
+#. Load :doc:`Config <../libraries/config>` class and pass the core config items established during
+   bootloading (including $assign_to_config overrides)
+#. Read constants.php file(s) from all the application/package paths
+#. Autoload config files
+#. Load :doc:`Hooks <../general/hooks>` class
+#. *Call pre-system hook*
+#. Load :doc:`Loader <../libraries/loader>` class and pass the base and application path lists with
+   autoloaded package paths applied
+#. Load **Utf8** class
+#. Load :doc:`URI <../libraries/uri>` class
+#. Load :doc:`Output <../libraries/output>` class (to be prepared for 404 output)
+#. Load :doc:`Router <../general/routing>` class, set routing, and apply $routing overrides
+#. *Call cache-override hook*, and if not overridden, check for cache
+#. If a valid cache is found, send it to Output and jump to the
+   display-override hook below
+#. Load :doc:`Security <../libraries/security>` class
+#. Load :doc:`Input <../libraries/input>` class
+#. Load :doc:`Lang <../libraries/language>` class
+#. Autoload helpers, languages, libraries, drivers, controllers, and models
+   (in that order, and don't run controllers)
+#. *Mark base class loading end time*
+#. *Call pre-controller hook*
+#. *Mark controller execution start time*
+#. Load the routed controller (or 404 if not found)
+#. *Call post-controller-constructor hook*
+#. Call routed controller method (or _remap) (or 404 if not found)
+#. **THE** :doc:`CONTROLLER <../general/controllers>` **RUNS**
+#. *Mark controller execution end time*
+#. *Call post-controller hook*
+#. *Call display-override hook*, and if not overridden, display output
+#. *Call post-system hook*
+
+.. |CodeIgniter application flow| image:: ../images/appflowchart.gif

user_guide_src/source/overview/at_a_glance.rst

@@ -35,14 +35,16 @@ CodeIgniter is Fast
 Really fast. We challenge you to find a framework that has better
 performance than CodeIgniter.
 
-CodeIgniter Uses M-V-C
-======================
+CodeIgniter Uses HMVC
+=====================
 
-CodeIgniter uses the Model-View-Controller approach, which allows great
-separation between logic and presentation. This is particularly good for
+CodeIgniter uses the Hierarchical Model-View-Controller approach, which allows
+great separation between logic and presentation. This is particularly good for
 projects in which designers are working with your template files, as the
-code these files contain will be minimized. We describe MVC in more
-detail on its own page.
+code these files contain will be minimized. With the hierarchical capability,
+you can break your application down into modular components for better division
+of labor and code reusability. We describe :doc:`HMVC <hmvc>` in more detail
+on its own page.
 
 CodeIgniter Generates Clean URLs
 ================================
@@ -111,4 +113,4 @@ CodeIgniter has a Friendly Community of Users
 =============================================
 
 Our growing community of users can be seen actively participating in our
-`Community Forums <http://codeigniter.com/forums/>`_.
+`Community Forums <http://codeigniter.com/forums/>`_.

user_guide_src/source/overview/features.rst

@@ -12,7 +12,7 @@ an app is to try it and get to know the code.
 encourage you to do just that. In the mean time here's a list of
 CodeIgniter's main features.
 
--  Model-View-Controller Based System
+-  Hierarchical Model-View-Controller Based System
 -  Extremely Light Weight
 -  Full Featured database classes with support for several platforms.
 -  Query Builder Database Support
@@ -43,4 +43,3 @@ CodeIgniter's main features.
 -  Flexible URI Routing
 -  Support for Hooks and Class Extensions
 -  Large library of "helper" functions
-

user_guide_src/source/overview/mvc.rst → user_guide_src/source/overview/hmvc.rst

@@ -1,12 +1,17 @@
-#####################
-Model-View-Controller
-#####################
+##################################
+Hierarchical Model-View-Controller
+##################################
 
-CodeIgniter is based on the Model-View-Controller development pattern.
-MVC is a software approach that separates application logic from
-presentation. In practice, it permits your web pages to contain minimal
+CodeIgniter is based on the Hierarchical Model-View-Controller development
+pattern. HMVC is a software approach that separates application logic from
+presentation and supports modular subdivisions of application code.
+In practice, it permits your web pages to contain minimal
 scripting since the presentation is separate from the PHP scripting.
 
+-  The **Hierarchy** is a collection of one or more Controllers, each
+   potentially having its own Model(s) and/or View(s). Program flow may
+   be passed from the initial Controller down to other Controllers in
+   any kind of hierarchy or sequence you wish.
 -  The **Model** represents your data structures. Typically your model
    classes will contain functions that help you retrieve, insert, and
    update information in your database.
@@ -25,3 +30,10 @@ ignore them and build your application minimally using Controllers and
 Views. CodeIgniter also enables you to incorporate your own existing
 scripts, or even develop core libraries for the system, enabling you to
 work in a way that makes the most sense to you.
+
+The Hierarchical aspect of CodeIgniter is similarly loose. Your application
+may consist of a single Controller, as is seen in plain MVC, or any
+number of Controllers organized any way you see fit. Models and Views
+will likely be associated with specific Controllers, but each is accessible
+to all parts of your application, thanks to the central CodeIgniter object
+where every resource is registered.

user_guide_src/source/overview/index.rst

@@ -12,5 +12,5 @@ The following pages describe the broad concepts behind CodeIgniter:
 	CodeIgniter Cheatsheets <cheatsheets>
 	Supported Features <features>
 	Application Flow Chart <appflow>
-	Model-View-Controller <mvc>
+	Model-View-Controller <hmvc>
 	Architectural Goals <goals>