Author: jpic
Date: Wed Feb 27 16:30:37 2008
New Revision: 7460
Log:
- Fixed inconsistencies between requirements and design docs,
- Removed controller multiplicity,
- Added the new use-case.
Modified:
experimental/MvcTools/design/design.txt
experimental/MvcTools/design/requirements.txt
Modified: experimental/MvcTools/design/design.txt
==============================================================================
--- experimental/MvcTools/design/design.txt [iso-8859-1] (original)
+++ experimental/MvcTools/design/design.txt [iso-8859-1] Wed Feb 27 16:30:37
2008
@@ -1,7 +1,7 @@
eZ component: MvcTools, Design
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-:Author: James Pic, Kore Nordmann, Thomas Nunninger
+:Author: James Pic, Thomas Nunninger, Tobias Schlitt
:Revision: $Rev$
:Date: $Date$
:Status: Draft
@@ -28,41 +28,42 @@
object that the controller returns.
Beside these concrete classes a collection of interfaces will be provided for
-routing, request-parsing, view-managing and view-handling. This will allow the
-user of this component to build his own MVC_ on basis of the components
+routing, request-parsing, view-managing and view-handling. This will allow
+the user of this component to build his own MVC_ on basis of the components
buildingblocks and to adjust it to his needs.
Very basic implementations of these interfaces will be shipped with the
component, that can be used for very basic applications and are mainly meant
-as reference implementations. In future tie-ins with other eZ Components might
-be provided, that ship with more advanced impelementations.
+as reference implementations. In future tie-ins with other eZ Components
+might be provided, that ship with more advanced impelementations.
Layers
======
The component is devided into 4 layers:
-The request parsing layer is represented by the ezcMvcRequestParser interface.
+The request parsing layer is represented by the ezcMvcRequestParser
+interface.
An instance of a implementing this interface is responsible for parsing an
incoming request and creating an instance of ezcMvcInput from it. This object
will encapsulate the complete request data, independent from the protocol and
format used for the request.
The routing layer, represented by the ezcMvcRouter interface, is in charge of
-selecting the correct controller(s) and the view manager to handle the
-request, based on the ezcMvcInput object it received.
+selecting the correct controller to handle the request, based on the
+ezcMvcInput object it received.
Controllers represent the third layer. At this level: Classes process the
-request, based on the ezcMvcInput object they received, and select the data to
-be used to create a response. Controllers only accept an instance of
+request, based on the ezcMvcInput object they received, and select the data
+to be used to create a response. Controllers only accept an instance of
ezcMvcInput as input and and are responsible for returning an instance of
ezcMvcOutput, encapsulating all data necessary to render the response.
-View management is the final layer, which is based on the incoming ezcMvcInput
-object and the ezcMvcOutput object created by the controllers. An instance of
-a class implementing the ezcMvcViewManager interface uses one or more
-instances of ezcMvcViewHandler to create the actual response and to send it to
-the client.
+View management is the final layer, which is based on the incoming
+ezcMvcInput object and the ezcMvcOutput object created by the controllers.
+An instance of a class implementing the ezcMvcViewManager interface uses one
+or more instances of ezcMvcViewHandler to create the actual response and to
+send it to the client.
Classes
=======
@@ -102,24 +103,16 @@
A class implementing this interface is in charge of using an instance of
ezcMvcInput to select one or more controllers to run them and collect their
-output (in form of ezcMvcOutput objects). In addition, it will select an
-implementation of ezcMvcViewManager, instantiate it and submit the collected
-responses to be handled by it.
+output (in form of ezcMvcOutput objects).
Methods::
/**
- * Instanciate a router, parses input and selects the controllers and
- * view-manager.
- */
- ezcMvcRouter public function __construct( $input )
-
- /**
- * Returns the list of controllers.
- *
- * @see Encapsulate controller multiplicity ?
- */
- ? public function getControllers()
+ * Returns the controller for this request.
+ *
+ * @return ezcMvcController
+ */
+ public function createController( $input )
ezcMvcViewManager
-----------------
@@ -132,37 +125,45 @@
Methods::
/**
- * This method should use the list of controllers, run it, select the view
- * handlers and send the response to the client.
- *
- * @param $controllers array|object Array of controllers or an object
- * wrapping them ?
- * @see Encapsulate controller multiplicity ?
- */
- void public function handle( $input, ? $controllers )
-
- /**
- * Create and return the response string.
- *
- * Returns a string or an ezcMvcResponseBody ?
- */
- ? public function createResponseBody( $input, ? $controllers )
+ * Handles creating and sending the response.
+ *
+ * This method should use the controller that was created by the
+ * router, and the input object created by the request parser.
+ * It should then create the response header and body, and send this
+ * response to the client.
+ *
+ * @param $input ezcMvcInput
+ * @param $controller ezcMvcController
+ * @uses createResponseBody()
+ * @uses createResponseHeader()
+ */
+ public function handle( ezcMvcInput $input, ezcMvcOutput $output )
+
+ /**
+ * Creates and returns the response body.
+ *
+ * Returns a string or an object encapsulating it (ezcMvcResponseBody) ?
+ */
+ public function createResponseBody( ezcMvcInput $input,
+ ezcMvcOutput $output )
/**
* Create and return the response header variables.
*
- * Return an array of key=>values or an ezcMvcResponseHeaders ?
- */
- ? public function createResponseHeader( $input, ? $controllers )
+ * Return a string, an array of key=>values or an object encapsulating it
+ * (ezcMvcResponseHeader) ?
+ */
+ public function createResponseHeader( ezcMvcInput $input,
+ ezcMvcOutput $output )
ezcMvcViewHandler
-----------------
This interface has to be implemented by classes that handle rendering one
ezcMvcOutput object into one specific format, that will be part of the
-response string. An instance of ezcMvcViewManager is responsible to coordinate
-different view handlers and to merge their output to a consistent response
-string.
+response string. An instance of ezcMvcViewManager is responsible to
+coordinate different view handlers and to merge their output to a
+consistent response string.
Methods::
@@ -171,14 +172,16 @@
*
* Returns a string or an ezcMvcResponseBody ?
*/
- ? public function createResponseBody( ? $controllers )
+ public function createResponseBody( ezcMvcInput $input,
+ ezcMvcOutput $output )
/**
* Create and return the response header variables.
*
* Return an array of key=>values or an ezcMvcResponseHeaders ?
*/
- ? public function createResponseHeader( ? $controllers )
+ public function createResponseHeader( ezcMvcInput $input,
+ ezcMvcOutput $output )
ezcMvcController
----------------
@@ -188,91 +191,106 @@
implementation will be shipped with the component.
Assuming that action-selection should be done within the controller itself,
-it should have a public method: run( $input, [ $output = null ] ).
-
-The controller should be able to use the passed output-object instead of
-creating a new one. Using an existing output-object might require that the
-output-object implement controller-level namespacing, this should not be
-supported.
+it should have a public method: run( $input ).
Possible system conceptions
===========================
-Encapsulate view handler multiplicity into a view-manager?
-----------------------------------------------------------
-
-This will free the router and user-space from rendering tasks, particularely
-useful when using several controllers at once. I think that the component
-should provide such a class, letting to concentrate on working on view
-handlers.
+Delegate most high-level calls to the user?
+-------------------------------------------
+
+::
+
+ #0 Invocation of a request-parser
+ $parser = new ezcMvcExampleRequestParser();
+
+ #1 Creation of the abstract input
+ $input = $parser->createInput();
+
+ #2 Invocation of a router
+ $router = new ezcMvcExampleRouter();
+
+ #3 Creation of the controller
+ $controller = $router->createController( $input );
+
+ #4 Creation of the abstract output
+ $output = $controller->createOutput();
+
+ #5 Invocation of a view-manager
+ $viewManager = new ezcMvcExampleViewManager();
+
+ #6 Creation and send of the response
+ $viewManager->handle( $input, $output );
+
+For testing/debugging purposes, it's possible to get the generated response
+body and header individually::
+
+ #6.1 Create the response body
+ $viewManager->createResponseBody( $input, $output );
+
+ #6.2 Create the response header
+ $viewManager->createResponseHeader( $input, $output );
+
+Of course, it's possible to implement MvcTools in an OOP way instead of a
+procedural way, like for every component::
+
+ class myMvcRunner
+ {
+ public function run()
+ {
+ $parser = $this->createParser();
+ $input = $parser->createInput();
+ $router = $this->createRouter();
+ $controller = $router->createController();
+ $output = $controller->run( $input );
+ $viewManager = $this->createViewManager();
+ $viewManager->handle( $input, $output );
+ }
+ protected function createParser()
+ {
+ // mechanisms ...
+ return $parser;
+ }
+ protected function createRouter()
+ {
+ // mechanisms ...
+ return $router;
+ }
+ protected function createViewManager()
+ {
+ // mechanisms ...
+ return $viewManager;
+ }
+ }
+
+Delegate most of the high-level mechanisms to the router?
+---------------------------------------------------------
The following snippet shows the API calls necessary in the user's public
script, in that case ::
<?php
- // ezcMvcUrlUserInputRequestParser implements ezcMvcRequestParser
- $parser = new ezcMvcUrlUserInputRequestParser();
-
- // The parser returns an instance of ezcMvcInput.
+ $parser = new ezcMvcExampleRequestParser();
+
$input = $parser->createInput();
- // ezcMvcUrlUserInputRouter implements ezcMvcRouter
- $router = new ezcMvcUrlUserInputRouter( $input );
-
- // An array or list-class with controllers
- $controllers = $router->getControllers();
-
- // For example, an instance of ezcMvcTemplateHtmlViewManager
- $viewManager = new ezcMvcTemplateHtmlViewManager();
-
- // Takes care of running the controllers and rendering their results
- $viewManager->handle( $input, $controllers );
-
-Attempt of representing a common use case, assuming classic HTML over HTTP :
-
-0) $parser can be used to fetch an instance of ezcMvcInput, wrapping all the
- client request variables :
- widget[action]=add&widget[id]=3&menu[selected]=widget
-1) $router can be used to fetch a set of controllers : myMvcWidgetController
- and myDynamicMenuController.
-2) Instanciate an ezcMvcTemplateHtmlViewManager.
-3) The view manager runs both controllers, and processes two templates using
- the controllers resulting output object along with
- ezcMvcTemplateHtmlViewHandler : menu.tpl, widget.tpl
-3.0) The widget template has a $menu variable that is replaced by the
- processed menu.tpl and the response is ready.
-3.1) Alternative way : the view manager processes main_layout.tpl, which
- contains $menu and $widget (or $main instead of $widget) that are
- replaced by menu.tpl and widget.tpl.
-3.2) The view-manager can send HTTP-headers.
-
-Delegate most of the high-level mechanisms to the router?
----------------------------------------------------------
-
-The following snippet shows the API calls necessary in the user's public
-script, in that case ::
-
- <?php
- $parser = new ezcMvcUrlUserInputRequestParser();
-
- $input = $parser->getInput();
-
- $router = new ezcMvcUrlUserInputRouter();
+ $router = new ezcMvcExampleRouter();
$output = $router->run( $input );
- $viewManager = $router->getViewManager( $output );
+ //$viewManager = $router->getViewManager( $output );
+ $viewManager = new ezcMvcExampleViewManager();
// Creates the response and sends it to the client.
- $viewManager->handle();
+ $viewManager->handle( $input, $output );
Or even ::
<?php
- $parser = new ezcMvcUrlUserInputRequestParser();
-
- $viewManager = new ezcMvcTemplateHtmlViewManager()
-
- $router = new ezcMvcUrlUserInputRouter(
+ $parser = new ezcMvcExampleRequestParser();
+
+ $viewManager = new ezcMvcExampleViewManager()
+
+ $router = new ezcMvcExampleRouter(
$parser,
$viewManager
);
@@ -323,10 +341,21 @@
There is no need to use anything better than a simple associative array for
the list of selected controllers returned by the router at the moment.
+Credits
+=======
+
+- Tobias Schlitt
+- Gaetano Giunta
+- Tobias Struckmeier
+- Derick Rethans
+- Kore Nordmann
+- James Pic
+- Thomas Nunninger
+
..
Local Variables:
mode: rst
- fill-column: 78
+ fill-column: 79
End:
- vim: et syn=rst tw=78
+ vim: et syn=rst tw=79
Modified: experimental/MvcTools/design/requirements.txt
==============================================================================
--- experimental/MvcTools/design/requirements.txt [iso-8859-1] (original)
+++ experimental/MvcTools/design/requirements.txt [iso-8859-1] Wed Feb 27
16:30:37 2008
@@ -8,9 +8,10 @@
================
The scope of this document is to describe the requirements for a component
-providing classes to implement a MVC_ architecture for a web application.
+providing classes to implement a MVC_ architecture for a web application.
This document does not describe the design of the named component, but only
-summarizes the requirements for it as discussed on the developer mailing list.
+summarizes the requirements for it as discussed on the developer mailing
+list.
Where suitable, design related topics will be touched, but a dedicated design
document will follow later, defining APIs, classes and the architectural
structure of the component.
@@ -39,7 +40,7 @@
each component as independent as possible and to realize dependencies
through so-called tie-in components. Therefore the mechanisms realized in an
MVC component should be that far abstracted, that other components can be
-tied in and provide only very basic implementations on its own. This also
+tied in and provide only very basic implementations on its own. This also
allows users to implement their own mechanisms. The following components
have been identified as possible tie-ins:
@@ -102,11 +103,11 @@
Another different layer is responsible to select the controller to run and
the action to call on it. To create the input-object it requires the
-so-called input-router. After the controller has been run, the output object
-is send to the view-manager, which is responsible to select the correct
-rendering mode for the output protocol/format.
-
-Those two layers should be able to use any number of controllers per-request.
+so-called request parser. After the controller has been run, the output
+object is send to the view-manager, which is responsible to select the
+correct rendering mode for the output protocol/format.
+
+Those two layers use one controller per request.
They handle the client-protocol, so that the controller doesn't have work on
raw input data (e.g. GET/POST/...) and does not have to generate any specific
output format (e.g. HTML, XML, plain text,...) or anything that is
@@ -116,7 +117,7 @@
Summary
^^^^^^^
-- Any number of controllers and actions can be run in 1 request.
+- 1 controllers and actions can be run in 1 request.
- Controllers may neither work on raw input directly, nor create a specific
kind of output, but may only work on abstracted I/O objects.
- It should be straight forward to test any action.
@@ -130,18 +131,32 @@
.. _PersistentObject: http://ezcomponents.org/docs/tutorials/PersistentObject
.. _Crud: http://en.wikipedia.org/wiki/Create%2C_read%2C_update_and_delete
+Request parser
+--------------
+
+Requests, also know as input, should be parsed by the request parser.
+The request parsers are protocol dependent, but return an abstract input
+object after being run.
+
+The request parser is the first layer in action, it's possible to run any
+controller with it's resulting input object.
+It handles input parsing and filtering, but delegates input validation to the
+controller.
+
+Summary
+^^^^^^^
+
+- The request parser is responsible to filter the incoming request and to
+extract all relevant data into the input abstraction object.
+
Routing
-------
-Several controllers can be run to serve a single request. Those controllers
-should be runnable within different requests in different mixtures. A
-controller returns an abstract value that should be usable with any output
+Each request runs a controller.
+A controller returns an abstract value that should be usable with any output
formats and protocols.
-The input-router is responsible to filter the incoming request and to extract
-all relevant data into the input abstraction object. The router also selects
-the controller(s) to run. After running the controllers the router selects
-the view-manager to use with the controller's return values (output-objects).
+The router selects the controller to run.
Controllers can call the routers re-routing method with redefined input data
to redirect processing to a different controller.
@@ -155,10 +170,8 @@
Routers are responsible for:
-- Filtering and abstracting input data
-- Creating an abstract input object
- Selecting controllers based on the input
-- Running the controllers and collecting abstract response objects
+- Running the controller and collecting the abstract response object
Routers may be asked by a controller to re-route the request to another
controller and must therefore be accessible from any action.
@@ -185,8 +198,7 @@
Only 1 view-handler can be used to generate a certain output. It can receive
any number of abstract output objects. A view-handler is responsible to
render a certain output format for a certain protocol. The view-handler to
-use is determined by the used view-manager, and the view-manager to use is
-determined by the router.
+use is determined by the used view-manager.
For example, the view-handler that generate HTML/HTTP-responses is separated
from the view-handler that generates XML/HTTP-response.
@@ -400,6 +412,7 @@
- Derick Rethans
- Kore Nordmann
- James Pic
+- Thomas Nunninger
..
Local Variables:
--
svn-components mailing list
svn-components@lists.ez.no
http://lists.ez.no/mailman/listinfo/svn-components
