From 48d306ee5c6d919c6e53e49d8422526a60a6fb3d Mon Sep 17 00:00:00 2001 From: Manuel Rego Casasnovas Date: Tue, 8 Mar 2011 18:16:02 +0100 Subject: [PATCH] [doc] Added more sections to use case development guide. * Completed information in interface section. * Added a new section about conversation model and how to develop controllers and models. --- ...howto-develop-an-use-case-in-navalplan.rst | 852 +++++++++++++++++- 1 file changed, 846 insertions(+), 6 deletions(-) diff --git a/doc/src/technical/howto-develop-an-use-case-in-navalplan.rst b/doc/src/technical/howto-develop-an-use-case-in-navalplan.rst index d6d8842fa..905d3f262 100644 --- a/doc/src/technical/howto-develop-an-use-case-in-navalplan.rst +++ b/doc/src/technical/howto-develop-an-use-case-in-navalplan.rst @@ -510,8 +510,8 @@ applicaition users in order to manage ``StretchesFunctionTemplate`` entity. When you click the new entry, NavalPlan will the load ``.zul`` file (but the link is not going to work as ``.zul`` page does not exist yet). -``.zul`` page -------------- +Main ``.zul`` page +------------------ Then you will create the file ``stretchesFunctionTemplate.zul`` inside ``navalplanner-webapp/src/main/webapp/planner/`` folder with the following @@ -526,9 +526,7 @@ content: - - - + @@ -634,7 +632,7 @@ the same identifier in ``.zul`` and Java. For example: * * @author Manuel Rego Casasnovas */ - public class StretchesFunctionCRUDController extends GenericForwardComposer { + public class StretchesFunctionTemplateCRUDController extends GenericForwardComposer { private Window listWindow; private Window editWindow; @@ -679,16 +677,858 @@ controller. For example with the following lines:: As you can see in last example, when an event is launched is not needed to use data binding. +ZK macrocomponents +------------------ + +Your page ``stretchesFunctionTemplate.zul`` defines 2 macrocomponents: ``list`` +and ``edit``. These macrocomponents implement list view and edit/creation view +respectively. + +:: + + + +This line declares a macrocomponent called ``list`` associated to page +``_listStretchesFunctionTemplates.zul``. ``inline`` attribute indicates that the +macrocomponent is on the same scope as the component which contains it, i.e., +``window`` component could see ``list`` component and the other way around. +Inside the same scope or namespace there can not be repeated identifiers (``id`` +attributes). + +However, ``window`` component creates a new namespace. Inside different +namespaces identifiers could be repeated. List contains a ``Grid`` called +``listStretchesFunctionTemplates``. + +Another consequence is that from the main window, which is associated with +controller, you can not access components defined in ``list`` or ``edit``. For +example:: + + public class StretchesFunctionTemplateCRUDController extends GenericForwardComposer { + + ... + + private NewDataSortableGrid listStretchesFunctionTemplates; + + @Override + public void doAfterCompose(Component comp) throws Exception { + ... + listStretchesFunctionTemplates.getModel(); + } + + ... + +Access to ``listStretchesFunctionTemplates`` will cause a +``NullPointerException``, because of ``listStretchesFunctionTemplates`` is not +in main window namespace. But, you could access indirectly to component from +controller through ``list`` component, because this is accessible from +controller. For example:: + + public class StretchesFunctionTemplateCRUDController extends GenericForwardComposer { + + private Window listWindow; + + ... + + private NewDataSortableGrid listStretchesFunctionTemplates; + + @Override + public void doAfterCompose(Component comp) throws Exception { + ... + listStretchesFunctionTemplates = (NewDataSortableGrid) listWindow + .getFellowIfAny("listStretchesFunctionTemplates"); + listStretchesFunctionTemplates.getModel(); + } + + ... + +Another important issue when implementing CRUD use cases is that general view +contains both ``list`` and ``edit`` component. These components are renderized +and shown when page is loaded. Class ``OnlyOneVisible`` is used in controller to +manage which one will be visible at a given time. You can find the following +pieces of code in all CRUD controllers already working in NavalPlan:: + + private OnlyOneVisible visibility; + + ... + + private void showListWindow() { + showWindow(listWindow); + } + + private void showEditWindow(String title) { + editWindow.setTitle(title); + showWindow(editWindow); + } + + private void showWindow(Window window) { + getVisibility().showOnly(window); + } + + private OnlyOneVisible getVisibility() { + if (visibility == null) { + visibility = new OnlyOneVisible(listWindow, editWindow); + } + return visibility; + } + +And usually at the end of ``doAfterCompose`` method there will be a call to +``showListWindow``, that shows the list view and use ``OnlyOneVisible`` class to +hide edit/creation form. + + +Messages for users +------------------ + +:: + + + +Defines a container to show messages to users. These messages usually appear in +the top of current window inside a box. There is a default implementation in a +class called ``MessagesForUser`` which is used in all controllers to show +messages to users in a similar way in the whole application. + +Apart from previous line on ``.zul`` file you will see the following lines +inside ``doAfterCompose`` method in controller:: + + @Override + public void doAfterCompose(Component comp) throws Exception { + ... + messagesForUser = new MessagesForUser(messagesContainer); + comp.setVariable("controller", this, true); + ... + +These lines instantiate a new object of ``MessagesForUser`` class using the +container defined at ``.zul`` page. Then when you want to notify or show a +message to the users you will use some method defined at ``IMessagesForUser``. +For example:: + + messagesForUser.showMessage(Level.INFO, + _("Stretches function template saved")); + + +List view +--------- + +For the moment you just have the code needed for the main page +``stretchesFunctionTemplate.zul``. At this point you are going to create the +list view interface in a file called ``_listStretchesFunctionTemplates.zul`` +(in the same folder than main page file +``navalplanner-webapp/src/main/webapp/planner/``). This file will have the +following content: + +:: + + + + + + + + + + + +