Author: ts
Date: Tue Feb 19 11:41:34 2008
New Revision: 7407
Log:
- Rephrasing and spell check.
Modified:
experimental/MvcTools/design/design.txt
Modified: experimental/MvcTools/design/design.txt
==============================================================================
--- experimental/MvcTools/design/design.txt [iso-8859-1] (original)
+++ experimental/MvcTools/design/design.txt [iso-8859-1] Tue Feb 19 11:41:34
2008
@@ -1,5 +1,5 @@
-eZ component: MvcTools, Design Draft
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+eZ component: MvcTools, Design
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:Author: James Pic, Kore Nordmann, Thomas Nunninger
:Revision: $Rev$
@@ -20,34 +20,49 @@
===============
Because of the variaty of protocols and formats that a modern PHP application
-should handle, this MVC implementation will provide an abstraction to input
+should handle, this MVC implementation will provide an abstraction for input
and output of controllers. Besides that, a few tieins will be provided.
The main classes of this component are ezcMvcInput and ezcMvcOutput, which
-are respectively the abstract input object for the controller and the
-abstract output object that the controller should return.
-
-Additionally, a collection of interfaces will be provided for routing,
-request-parsing, view-managing and view-handling.
+represent the abstract input object for a controller and the abstract output
+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
+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.
Layers
======
-The component is basically devided into 4 layers: the request parsing layer
-is represented by an interface. An instance of such a class is responsible
-for parsing the request and making an abstract input object.
-
-The routing layer is in charge of selecting the controller(s) and the view
-manager, using the abstract input object.
-
-Controllers are the third layers, at this level : classes process the
-request and select the data to use for making the response : controllers
-accept the abstract input object and are responsible for returning an
-abstract output object.
-
-View management is the final layer, using on the output and input objects :
-the view-manager use the view-handler(s) to create the formatted final
-response to send to the client.
+The component is devided into 4 layers:
+
+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.
+
+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
+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.
Classes
=======
@@ -56,71 +71,77 @@
-------------------
The ezcMvcRequestParser interface has to be implemented by classes that will
-parse the request and create an ezcMvcInput object.
+parse a request and create an ezcMvcInput object.
ezcMvcInput
-----------
-This object encapsulates the client-request, abstracting the request
-protocol.
-
-It's important to separate the object's properties from the request variables
-in the class facade.
-This class implements Iterator, ArrayAccess and Countable for request-values,
-and public properties will be used for the object's variables.
+An instance of this class encapsulates a client-request, abstracting from the
+request protocol and format.
+
+To seperate the class properties of the input object, containing settings and
+the object state, from the request data it carries, the class will provide an
+array-like $data property that is exclusively reserved for request data.
ezcMvcOutput
------------
-This object encapsulates the controller result, abstracting the response
-protocol.
-
-It's important to separate the object's properties from the request variables
-in the class facade.
-This class implements Iterator, ArrayAccess and Countable for request-values,
-and public properties will be used for the object's variables.
+This object encapsulates the result of a controller, abstracting from the
+actual response protocol. The output object will be modelled similar to the
+input variant, described above.
+
ezcMvcRouter
------------
-This interface is in charge of using an instance of ezcMvcInput to select the
-controller(s) and the view-manager.
+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.
ezcMvcViewManager
-----------------
This interface has to be implemented by classes that are in charge of
-rendering the instance(s) of ezcMvcOutput into a format acceptable for the
-response protocol, using view-handlers.
+coordinating the rendering of ezcMvcOutput instances into a format acceptable
+for the response protocol. The rendering itself is done by instances of
+ezcViewHandler.
ezcMvcViewHandler
-----------------
This interface has to be implemented by classes that handle rendering one
-ezcMvcOutput object into one formated (part of the) response string.
+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.
ezcMvcController
----------------
-This interface should be implemented by user's controllers.
-Assuming that action-selection should be done within the controller itself :
-it should have one public method : run( $input, [ $output = null ] ).
+This interface must be implemented by every controller. This is the only
+interface that is only meant for user implementation and for that no basic
+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.
+creating a new one. Using an existing output-object might require that the
+output-object implement controller-level namespacing, this should not be
+supported.
Possible system conceptions
===========================
-Encapsulate view handler multiplicity into a view-manager ?
------------------------------------------------------------
+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.
+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.
The following snippet shows the API calls necessary in the user's public
script, in that case ::
@@ -163,8 +184,8 @@
replaced by menu.tpl and widget.tpl.
3.2) The view-manager can send HTTP-headers.
-Encapsulate controller multiplicity outside the router ?
---------------------------------------------------------
+Encapsulate controller multiplicity outside the router?
+-------------------------------------------------------
The following snippet shows the API calls necessary in the user's public
script, in that case ::
@@ -196,15 +217,15 @@
$router->run();
-Should the router be selected by a router manager ?
----------------------------------------------------
+Should the router be selected by a router manager?
+--------------------------------------------------
The router could be selected by a router-manager.
In that case, some routing mechanism should be in the router manager.
Router-manager shouldn't be implemented, routers should be factorized instead.
-Should the MVC implementation take care of actions/sub-controllers ?
---------------------------------------------------------------------
+Should the MVC implementation take care of actions/sub-controllers?
+-------------------------------------------------------------------
Controllers have a method looking like : run( ezcMvcInput $input )
It's up to the controller to figure it's action using $input.
--
svn-components mailing list
svn-components@lists.ez.no
http://lists.ez.no/mailman/listinfo/svn-components
