Hello everybody, An update of the requirements documents, where i compiled our needs and answered the un-answered questions.
Note that we haven't discussed of output yet. Cheers, James.
eZ Component: MvcTools, Requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :Author: James Pic, Tobias Schlitt :Revision: $Revision$ :Date: $Date$ Target and scope ================ The scope of this document is to describe the initial design of a component providing tools for users to implement an extendable and unified MVC_ pattern. Note that if you don't understand a term, you should have a look at the end of this document, section : Clarification of terms`_. There have been questions about the implementation on the ML, let's restrict the discussion to the actual *requirements* for the moment, allowing to decide of the best implementations later. So, the question here: What does everyone need/expect here? Component integration ===================== eZ Components already provide some components that are useful when implementing an MVC. However, one basic goal of eZ Components is to keep each component as independent as possible and to realize dependencies through tie-ins. 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 allows users to implement their own mechanisms. I identified the following components to be related here: - Template_ (view), - UserInput_ (routing), - Url_ (routing), - PersistentObject_ (models), - EventLog_ (error-handling), - Mail_ (error-handling). .. _Template: http://ezcomponents.org/docs/tutorials/Template .. _UserInput: http://ezcomponents.org/docs/tutorials/UserInput .. _Url: http://ezcomponents.org/docs/tutorials/Url .. _PersistentObject: http://ezcomponents.org/docs/tutorials/PersistentObject .. _EventLog: http://ezcomponents.org/docs/tutorials/EventLog .. _Mail: http://ezcomponents.org/docs/tutorials/Mail Design requirements =================== General goals for I/O abstraction --------------------------------- Modern applications often require to deal with different protocols (SOAP, HTTP ...). Therefore, protocol inputs and outputs should be abstracted when programming actions, allowing those to be almost natively portable. A benefic side-effect relates to action-testing. Making input and output mocks and fixtures allows straight-forward test-programming. Summary ^^^^^^^ - controllers should (almost) natively support multiple protocols, - making input and output fixtures to unify controller testing. Error-handling -------------- Actions should be free to fail for any reason (input not viable, requested data doesn't exist ...). Failures should be reported to the user, so that the user can understand and either try again later or with different input. Some failures can have critical consequences or causes, which might interrest some actors; thus a report should be sent. The visitor requires a verbose error message to be displayed in an arbitary controller, wheras project-actors that will be notified (if any) require a technical report. Summary ^^^^^^^ Actions should be able to cast an error specifying, at once : - the verbose error message, - the non-verbose error message or id, - the target action to bundle the error with, - wheter actors should be notified or not. An EventLog_ + Mail_ tie-in should be supplied. .. _EventLog: http://ezcomponents.org/docs/tutorials/EventLog .. _Mail: http://ezcomponents.org/docs/tutorials/Mail Routing ------- It's the key to I/O abstraction. Requests are issued to a router object, which handles the input abstraction. Then, it should select an action and run it using the abstracted-input. Actions result in an abstracted-output, like a set of variables; the router use it to make the final response. Each protocol requires a different I/O abstraction process : each protocol require a router. Using a router layer between the action and the client can seem natural, routers abstract the local-network into one external address and set of ports. Being the first layer meeting user-input, it should handle filtering before producing the abstract-input. Being the router, it has the keys to any actions, thus it should allow action to re-route the user-input to another action. Summary ^^^^^^^ Routers should be able to : - filter input, - make an abstract-input object, - run the requested action using the abstract-input as argument, - which should result in an abstract-output object, - make the response using the abstract-output object, - directly send the response. - be asked by a controller to re-route the request to another action. - be accessible from any action. This allows one-router-per-protocol. A UserInput_ + Url_ tie-in should be supplied for HTTP : it should implement ezcTemplateCustomFunction and provide Template-functions to making viable-urls in templates. However, overloading it's response- generation method should be straight-forward (*one* public method). .. _UserInput: http://ezcomponents.org/docs/tutorials/UserInput .. _Url: http://ezcomponents.org/docs/tutorials/Url Controllers ----------- Controllers processes and responds to events, typically user actions, and may invoke changes on the model. I/O is abstract to the controller, meaning that it can use the abstract-input to generate an abstract-output : the protocol is abstract to the controller; thus, it should generate any HTML, XML or else, but just the output-object that the router will use to generate the actual HTML. Summary ^^^^^^^ - Controllers and actions should not be limited in number. - It should not generate any HTML or anything that is protocol-limited. - It should be straight forward to test any action. - It should not use input from anywhere-else than the abstract-input object. A PersistentObject_ tie-in should be supplied (Crud_). .. _PersistentObject: http://ezcomponents.org/docs/tutorials/PersistentObject .. _Crud: http://en.wikipedia.org/wiki/Create%2C_read%2C_update_and_delete Testing ------- Manually testing each controller after each change or bugfix is a very poor programming practice, can lead to critical downtimes, failures, or corrupted data. However, automating tests is a good programming practice, but can become quiet complex because of the elaborated controllers. I/O abstraction makes it simple, all the programmer has to do is making an output-fixture representing the expected controller result, an input-fixture corresponding to the abstract client-request, run it in the controller to test, and assert that the result equals the expected abstract-output. Summary ^^^^^^^ Requested processus to test a controller : - make an input-fixture, - make an output-fixture, - run the controller against the request fixture, - assert that the controller-result equals the output-fixture. Conventions ----------- What are the requirements for conventions ? Special Considerations ====================== We should keep testing capabilities for the extensions to this component and the applications build upon it in mind during the design phase. We cannot provide the testing environment itself : - does not fit into the component, and - our test "component" is not an official component can only be used to test eZ Components. However, we could provide detailed information and possibly some helper classes for the testing of applications build on this component. The later application configuration layer (meaning to read configuration from config files) and configuring the parts of the MVC accordingly should be part of a potential "Framework" component. But this should not be part of this thread. We should also wait until the Mvc stuff is fixed to start working in something in direction of a framwork bundle. In addition, this component should neither provide any automation facilities (e.g. code generation, deployment) nor integration with components that are not explicitly needed by it (e.g. Configuration, Authentication or Database). Integration with such components could : - be build using a tie-in, or - be part of whatever "Framework" stuff that might be created in future. Clarification of terms ====================== MVC_ Model-view-controller (MVC) is an architectural pattern to separate data (model) and user interface (view) concerns, so that changes to the user interface will not affect data handling. Model The domain-specific representation of the information that the application operates. Domain logic adds meaning to raw data (e.g., calculating whether today is the user's birthday, or the totals, taxes, and shipping charges for shopping cart items). PersistentObject component provides a persistent storage mechanism (such as a database) to store data. MVC does not specifically mention the data access layer because it is understood to be underneath or encapsulated by the Model. View Renders the action into a form suitable for interaction, typically a user interface element. Multiple views can exist for a single model for different purposes. The Template component provides a syntax-light language for non-programmers to design the views. Controller Processes and responds to events, typically user actions, and may invoke changes on the model. Action Controllers can provide one or several actions. Each action has a specific process that can be called by the router. InputOutput_ In computing, input/output, or I/O, refers to the communication between a program and the outside world – possibly a human. Inputs are the data received by the system, and outputs are the data sent from it. The term can also be used as part of an action; to "perform I/O" is to perform an input or output operation. For example, a browser such as firefox is able to send input to the website and to draw it's output (HTML). I/O Stands for Input/Output. Router Routers are the first layer met by input and the last layer met by the output. That's why it handles routing requests to the appropriate action and abstracts the request/response protocol. Fixture_ Fixtures are objects that are set to an arbitary state for testing purposes. Abstraction_ It is the process or result of generalization by reducing data, typically in order to retain only information which is usable by any router for any protocol. .. _MVC: http://en.wikipedia.org/wiki/Model-view-controller .. _InputOutput: http://en.wikipedia.org/wiki/Input/output .. _Fixture: http://en.wikipedia.org/wiki/Test_fixture .. _Abstraction: http://en.wikipedia.org/wiki/Abstraction Credits ======= Thanks to the persons who gived feedback on the previous document *in the ML*, i've made my best to compile our requirements in, UL : - Tobias Schlitt - Gaetano Giunta - Tobias Struckmeier - Derick Rethans - James Pic .. Local Variables: mode: rst fill-column: 79 End: vim: et syn=rst tw=79
pgppKXHijVTgK.pgp
Description: PGP signature
-- Components mailing list [email protected] http://lists.ez.no/mailman/listinfo/components
