[pLog-svn] r1600 - in plog/trunk/class: . controller
oscar at devel.plogworld.net
oscar at devel.plogworld.net
Thu Mar 24 13:05:42 GMT 2005
Author: oscar
Date: 2005-03-24 13:05:41 +0000 (Thu, 24 Mar 2005)
New Revision: 1600
Modified:
plog/trunk/class/Doxyfile
plog/trunk/class/controller/admincontroller.class.php
plog/trunk/class/controller/admincontrollermap.properties.php
plog/trunk/class/controller/blogcontroller.class.php
plog/trunk/class/controller/controller.class.php
plog/trunk/class/controller/controllermap.properties.php
plog/trunk/class/controller/resourceclassloader.class.php
Log:
added documentation for the Controller module
Modified: plog/trunk/class/Doxyfile
===================================================================
--- plog/trunk/class/Doxyfile 2005-03-24 07:16:32 UTC (rev 1599)
+++ plog/trunk/class/Doxyfile 2005-03-24 13:05:41 UTC (rev 1600)
@@ -416,7 +416,7 @@
# directories like "/usr/src/myproject". Separate the files or directories
# with spaces.
-INPUT = object/ dao/ logger/ gallery/ locale/ config/ file/ database/ data/forms security/ xml/
+INPUT = object/ dao/ logger/ gallery/ locale/ config/ file/ database/ data/forms security/ xml/ controller/
# If the value of the INPUT tag contains directories, you can use the
# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
Modified: plog/trunk/class/controller/admincontroller.class.php
===================================================================
--- plog/trunk/class/controller/admincontroller.class.php 2005-03-24 07:16:32 UTC (rev 1599)
+++ plog/trunk/class/controller/admincontroller.class.php 2005-03-24 13:05:41 UTC (rev 1600)
@@ -1,10 +1,5 @@
<?php
- /**
- * @package controller
- */
-
-
include_once( PLOG_CLASS_PATH."class/controller/controller.class.php" );
include_once( PLOG_CLASS_PATH."class/dao/bloginfo.class.php" );
include_once( PLOG_CLASS_PATH."class/dao/userinfo.class.php" );
@@ -12,12 +7,17 @@
$_plogAdminController_running;
/**
+ * \ingroup Controller
+ *
* Extends the Controller class so that the operation of loading the
- * file with the mappings is done automatically.
+ * file with the mappings is done automatically. The default action parameter becomes
+ * "op" and the file class/controller/admincontrollermap.class.php will be used as the default
+ * action class map.
*
- * This is the controller used by the administrative interface.
+ * You will rarely need to use this class in real life.
*/
- class AdminController extends Controller {
+ class AdminController extends Controller
+ {
/**
* Constructor. Automatically loads the maps
@@ -36,19 +36,22 @@
}
/**
- * the reason for reimplementing this method is easy... if a plugin adds an actin
+ * If a plugin adds an action
* for the public side and an action for the admin side, the action will be accessible via
- * both index.php?op=theActionName and admin.php?op=theActionName, and that's not good. What I
- * have tried to do here is use a global variable that is initialized when the constructor of
+ * both index.php?op=theActionName and admin.php?op=theActionName. We will use
+ * use a global variable that is initialized when the constructor of
* this class is called. If that variable is set to 'true', then it means that our constructor
* was initialized and that we can go ahead and add the action. If not, then we skip the whole
* thing and the action is not added.
*
- * I know global variales is not such an elegant solution but the lack of static attributes
- * in PHP forced me to do so...
- *
+ * This method should therefore be called when adding new actions but <b>only for the public side</b>. In
+ * case of plugins, please use PluginBase::registerBlogAction() and PluginBase::registerAdminAction()
+ * which will nicely hide all these things from you.
+ *
+ * @param actionKey Action key to add
+ * @param actionClass Action class to which the class will map
* @see Controller
- */
+ */
function registerAction( $actionKey, $actionClass )
{
global $_plogAdminController_running;
@@ -61,6 +64,8 @@
/**
* Loads the maps
+ *
+ * @private
*/
function _loadActionMaps()
{
Modified: plog/trunk/class/controller/admincontrollermap.properties.php
===================================================================
--- plog/trunk/class/controller/admincontrollermap.properties.php 2005-03-24 07:16:32 UTC (rev 1599)
+++ plog/trunk/class/controller/admincontrollermap.properties.php 2005-03-24 13:05:41 UTC (rev 1600)
@@ -1,10 +1,5 @@
<?php
- /**
- * @package controller
- */
-
-
/*
* This is the array definition of the different mappings
* action parameter->action class used by the controller of the administrative
Modified: plog/trunk/class/controller/blogcontroller.class.php
===================================================================
--- plog/trunk/class/controller/blogcontroller.class.php 2005-03-24 07:16:32 UTC (rev 1599)
+++ plog/trunk/class/controller/blogcontroller.class.php 2005-03-24 13:05:41 UTC (rev 1600)
@@ -1,19 +1,21 @@
<?php
- /**
- * @package controller
- */
-
-
include_once( PLOG_CLASS_PATH."class/controller/controller.class.php" );
$_plogBlogController_running;
/**
+ * \ingroup Controller
+ *
* Extends the Controller class so that the operation of loading the
- * file with the mappings is done automatically.
+ * file with the mappings is done automatically. The default action parameter becomes
+ * "op" and the file class/controller/controllermap.class.php will be used as the default
+ * action class map.
+ *
+ * You will rarely need to use this class in real life.
*/
- class BlogController extends Controller {
+ class BlogController extends Controller
+ {
/**
* Constructor. Automatically loads the maps
@@ -31,17 +33,20 @@
}
/**
- * the reason for reimplementing this method is easy... if a plugin adds an actin
+ * If a plugin adds an action
* for the public side and an action for the admin side, the action will be accessible via
- * both index.php?op=theActionName and admin.php?op=theActionName, and that's not good. What I
- * have tried to do here is use a global variable that is initialized when the constructor of
+ * both index.php?op=theActionName and admin.php?op=theActionName. We will use
+ * use a global variable that is initialized when the constructor of
* this class is called. If that variable is set to 'true', then it means that our constructor
* was initialized and that we can go ahead and add the action. If not, then we skip the whole
* thing and the action is not added.
*
- * I know global variales is not such an elegant solution but the lack of static attributes
- * in PHP forced me to do so...
- *
+ * This method should therefore be called when adding new actions but <b>only for the public side</b>. In
+ * case of plugins, please use PluginBase::registerBlogAction() and PluginBase::registerAdminAction()
+ * which will nicely hide all these things from you.
+ *
+ * @param actionKey Action key to add
+ * @param actionClass Action class to which the class will map
* @see Controller
*/
function registerAction( $actionKey, $actionClass )
@@ -56,6 +61,8 @@
/**
* Loads the maps
+ *
+ * @private
*/
function _loadActionMaps()
{
Modified: plog/trunk/class/controller/controller.class.php
===================================================================
--- plog/trunk/class/controller/controller.class.php 2005-03-24 07:16:32 UTC (rev 1599)
+++ plog/trunk/class/controller/controller.class.php 2005-03-24 13:05:41 UTC (rev 1600)
@@ -1,7 +1,17 @@
<?php
/**
- * @package controller
+ * \defgroup Controller
+ *
+ * The controller is the central piece of the MVC pattern, and the object that takes care of
+ * transferrign the process flow to the right action class based on a certain value in the
+ * incoming request.
+ *
+ * This package includes the basic Controller class, as well as the BlogController and
+ * AdminController ones, which implement a bit of extra logic for loading the maps and so on.
+ *
+ * There is also a dynamic class loader (ResourceClassLoader) that takes care of loading action classes
+ * from a certain set of folders.
*/
@@ -30,6 +40,8 @@
$_plogController_forwardAction;
/**
+ * \ingroup Controller
+ *
* This is how MVC works, using the pattern of the 'Front Controller'. With this pattern, we have
* a single controller class that receives all the requests from the client, identifies the
* action to be taken and the relays the execution of the action to the most suitable Action class.
@@ -38,20 +50,76 @@
*
* (according to http://java.sun.com/blueprints/guidelines/designing_enterprise_applications_2e/web-tier/web-tier5.html)
*
- * 1. The controller receives a POST from the client.
- * 2. The controller creates an Action corresponding to the requested operation (as described in the previous section).
- * 3. The controller calls the Action's perform method.
+ * # The controller receives a POST from the client.
+ * # The controller creates an Action corresponding to the requested operation (as described in the previous section).
+ * # The controller calls the Action's perform method.
* perform calls a model business method.
- * 4. The controller calls the screen flow manager to select the next view to display.
- * 5. The screen flow manager determines the next view and returns its name to the controller.
- * 6. The controller forwards the request to the templating service, which assembles and delivers the selected view to the client.
+ * # The controller calls the screen flow manager to select the next view to display.
+ * # The screen flow manager determines the next view and returns its name to the controller.
+ * # The controller forwards the request to the templating service, which assembles and delivers the selected view to the client.
+ *
+ * The Controller uses an action map file that maps action parameters to action classes. This is file is
+ * nothing more than an associative PHP array where the key of the array is the value of the action
+ * parameter and the key is the name of an action class. The default action parameter is "op" and the default
+ * action is "Default" unless otherwise specified.
*
- * In our particular case, we have two kinds of Actions: Action and ActionForm. The first is the
- * one that should be normally used, while the second should be used when receiving data from
- * forms, since it provides an additional method, validate() that will allow the developer
- * to validate the data that came from the form. If the result of validate() is 'false',
- * the controller will <b>not</b> call the perform() method and stop execution. However, the
- * validate method should also generate a valid view containing probably the error message.
+ * This is an example of a map file:
+ *
+ * <pre>
+ * $actions["Default"] = "AdminDefaultAction";
+ * $actions["Login"] = "AdminLoginAction";
+ * $actions["blogSelect"] = "AdminMainAction";
+ * $actions["Dashboard"] = "AdminMainAction";
+ * $actions["Manage"] = "AdminManageAction";
+ * </pre>
+ *
+ * It is not necesary to specify the full extension of the file, and by default it is considered to be
+ * ".class.php". In case this is not the case, please the ResourceClassLoader::setClassFileSuffix()
+ * method.
+ *
+ * Classes can be dynamically loaded (meaning that we
+ * do not need to load all of them via include() or include_once() at the top of our code), via the
+ * ResourceClassLoader class. This class will scan a set of pre-defined folders looking for the action
+ * class and load it if it's the one we were looking for.
+ *
+ * In order to create a Controller object and process a request, we would use something like:
+ *
+ * <pre>
+ * $controller = new Controller( "myactionmap.properties.php" );
+ * $controller->process( $_REQUEST );
+ * </pre>
+ *
+ * It is also possible to register new actions dynamically at run time via the static method
+ * Controller::registerAction() which takes an action class name and an action id as parameters. This is the
+ * method used by plugins to register new actions (although via the wrapper PluginBase::registerAction())
+ *
+ * In our particular implementation, each action class should extend the Action class or a child of it
+ * such as BlogAction, AdminAction, etc. Each one of this action classes should at least implement
+ * the Action::perform() method and include there its business logic (which can be whatever) Action classes
+ * are expected to generate a valid View class that the Controller will use to render the contents that
+ * will be sent back to the client. The Controller will get the right view via the Action::getView() method, and
+ * views can be set via the Action::_view attribute or the Action::setView() method.
+ *
+ * Another method that the controller will call is the validate() method that can be used for basic
+ * data validation logic. The base Action class already provides some code in this method, which is tied to
+ * the FormValidator and Validator classes so in case of data validation, it is advisable to use those
+ * methods. However if required, feel free to reimplement Action::validate(), keeping in mind that if the controller
+ * receives a positive value, it will continue processing the Action::perform() and if not, it will stop
+ * processing and call Action::getView() right away.
+ *
+ * Actions can also forward the process flow to another action without generating a view by calling
+ * the static method Controller::setForwardAction(), which takes an action class identifier as a parameter. If
+ * after processing action the controller detects that there is a forwarding in place, it will <b>not</b>
+ * call Action::getView() but instead, start the process again and call validate() and process() in the next
+ * action in line.
+ *
+ * @see BlogController
+ * @see AdminController
+ * @see Action
+ * @see BlogAction
+ * @see AdminAction
+ * @see FormValidator
+ * @see Validator
*/
class Controller extends Object
{
Modified: plog/trunk/class/controller/controllermap.properties.php
===================================================================
--- plog/trunk/class/controller/controllermap.properties.php 2005-03-24 07:16:32 UTC (rev 1599)
+++ plog/trunk/class/controller/controllermap.properties.php 2005-03-24 13:05:41 UTC (rev 1600)
@@ -1,18 +1,12 @@
<?php
- /**
- * @package controller
- */
-
-
/*
* This is the array definition of the different mappings
* action parameter->action class used by the controller.
*
* This would be very nice if implemented in PHP, but hey... let's not
* make things too complicated yet :)
- */
-
+ **/
$actions["Default"] = "DefaultAction";
$actions["ViewArticle"] = "ViewArticleAction";
$actions["Comment"] = "CommentAction";
Modified: plog/trunk/class/controller/resourceclassloader.class.php
===================================================================
--- plog/trunk/class/controller/resourceclassloader.class.php 2005-03-24 07:16:32 UTC (rev 1599)
+++ plog/trunk/class/controller/resourceclassloader.class.php 2005-03-24 13:05:41 UTC (rev 1600)
@@ -3,7 +3,19 @@
include_once( PLOG_CLASS_PATH.'class/object/object.class.php' );
/**
- * takes care of dynamically loading classes for the controller
+ * \ingroup Controller
+ *
+ * This class takes care of dynamically loading classes for the controller.
+ *
+ * This is a very simple class that keeps a list of folders where action classes can be found. Whenever
+ * the controller requests to load an action class, this loader will go one by one through all the folders
+ * until the class is found, or it will fail if none can be found.
+ *
+ * New folders to be scanned can be added via the static method ResourceClassLoader::addSearchFolder(),
+ * and the loading of classes takes place in the ResourceClassLoader::load() method.
+ *
+ * This object should never be instantiated directly but instead, please use the
+ * ResourceClassLoader::getLoader() method which will return a reference to an already existing instance.
*/
class ResourceClassLoader extends Object
{
@@ -13,11 +25,11 @@
/**
* initializes the class loader. It is advisable to use the
- * static ResourceClassLoader::getClass method
+ * static ResourceClassLoader::getLoader() method
*
- * @param path The starting path where classes can be loaded
- * @param classFileSuffix default suffix that each class file will have
- * @static
+ * @param path The starting path where classes can be loaded. It defaults to "./"
+ * @param classFileSuffix default suffix that each class file will have. It defaults to
+ * ".class.php"
*/
function ResourceClassLoader( $path = "./", $classFileSuffix = '.class.php' )
{
@@ -28,10 +40,12 @@
}
/**
- * static method that returns a single instance of this class
+ * static method that returns a single instance of this class.
*
* @static
- * @param path
+ * @param path If the object is being created for the first time, this will be passed to the constructor
+ * of the class as the first parameter. If a class instance already exists, this path will be added to the
+ * list of already existing paths to scan.
* @return a ResourceClassLoader object
*/
function &getLoader( $path = null )
@@ -52,9 +66,9 @@
}
/**
- * adds a new folder to the list of folders to be searched
+ * Adds a new folder to the list of folders to be searched
*
- * @param folder
+ * @param folder The new folder that will be added
* @return always true
*/
function addSearchFolder( $folder )
@@ -65,9 +79,10 @@
}
/**
- * sets a new suffix for class files
+ * sets a new suffix for class files, in case our class files do not end with .class.php. Please
+ * note that only <b>one</b> suffix can be used at the same time.
*
- * @param suffix
+ * @param suffix the new suffix
* @return always true
*/
function setClassFileSuffix( $suffix )
@@ -78,11 +93,12 @@
}
/**
- * loads classes from disk using the list of folders that has been provided. The
- * class will loop through all the folders where classes can be located and if it
- * can be found, it will proceed to load it. If not, an exception will be thrown
+ * Loads classes from disk using the list of folders that has been provided
+ * via ResourceClassLoader::addSearchFolder() The class will go through all the folders where
+ * classes can be located and if it can be found, it will proceed to load it.
+ * If not, an exception will be thrown
*
- * @param actionClassName name of the class that we are going to load.
+ * @param actionClassName name of the class that we are going to load, <b>without the class suffix</b>
* @return True if successful
*/
function load( $actionClassName )
More information about the pLog-svn
mailing list