jford 2005/04/05 18:15:55 Modified: xdocs portlet_config_GenericMVC.xml Log: Added more documentation on the Generic MVC Portlet Revision Changes Path 1.2 +85 -2 jakarta-jetspeed/xdocs/portlet_config_GenericMVC.xml Index: portlet_config_GenericMVC.xml =================================================================== RCS file: /home/cvs/jakarta-jetspeed/xdocs/portlet_config_GenericMVC.xml,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- portlet_config_GenericMVC.xml 3 Apr 2005 22:39:09 -0000 1.1 +++ portlet_config_GenericMVC.xml 6 Apr 2005 01:15:55 -0000 1.2 @@ -102,8 +102,91 @@ <p/> </section> --> - <section name="Explanation of the Generic MVC Portlet's render/action phase"> - + <section name="Explanation of the Generic MVC Portlet's action/render phase"> + <p> + It is important to understand the Generic MVC Portlet's render and action phasing to properly understand what is going on. + </p> + + <subsection name="History"> + <p> + In the past, portlets were required to use Turbine actions. + The action parameter on the url was required in order to execute an action on a portlet. + When Turbine processed the incoming URL, it would execute the action that was passed in on the URL. + This action occurred first, before any rendering had started. + Two side effects of the action firing first were: + 1) redirects could be used to forward the portal to another PSML and + 2) data could be placed into the session or user temp and other porltets would render updated content. + </p> + </subsection> + + <subsection name="Generic MVC Portlet anction/render phase"> + <p> + With the Genereic MVC Portlet, actions are fired directly before a portlet's content is rendered. + The action is not specified in the URL, but is instead specified in the registry. + To fire an action, simply specifying an eventSubmit_domyaction on the url will fire domyaction if that method exists in the action class. + However, this also allows multiple portlets domyaction method to fire. + To limit this to the actual portlet instance that was used to submit the action, one needs to specify the portlet id on the URL as well. + + </p> + <p> + <code> + $jslink.getPortletById($portlet.ID).addQueryData("eventSubmit_domyaction", "1") + </code> + </p> + <p> + + Since the action is now being fired during the render process, it is now too late for redirects. + This can somewhat complicate development of portlets/psmls that depend on each other. + Also, now that the action is not fired until directly before rendering, any dependant portlets may not see any data changes until a second browser refresh. + + </p> + </subsection> + + <subsection name="Development Guidelines"> + <p> + Here are some guidelines to developing your portlet when using the Generic MVC Portlet. + + <ul> + <li> + <p><span style="font-weight: bold;">Use multiple templates when necessary</span></p> + <p> + In your action, calling setTemplate allows you to change the currently displayed template. + This can cut down on messy Velocity/JSP code to handle different display states within the same file. + </p> + </li> + <li> + <p><span style="font-weight: bold;">Use PortletSessionState and PortletConfigState</span></p> + <p> + PortletSessionState provides methods for setting/getting/removing data for a specific portlet instance. + This allows you to keep session data without worrying about overwriting another portlet's data. + </p> + <p> + PortletConfigState provides access to helpful methods for retrieving and setting parameters for a portlet. + </p> + </li> + <li> + <p><span style="font-weight: bold;">Avoid Writing Your Own Portlet</span></p> + <p> + With the GenericMVCPortlet, there is usually not a need to write your own class. + Simply create a registry entry and use GenericMVCPortlet as the parent. + All you need to do is provide a template. + If you wish to provide dynamic content, provide an action parameter in the registry and write an action instead. + </p> + </li> + <li> + <p><span style="font-weight: bold;">Always derive from GenericMVCAction</span></p> + <p> + Continuing from the previous tip, if developing dynamic content, simply subclass the GenericMVCAction class. + There is no need to subclass either the VelocityPorltetAction of the JspPortletAction. + Both of these classes derive from GenericMVCAction themselves. + By subclassing directly from GenericMVCAction, you can switch between JSP and Velocity without having to worry about touching you action class. + </p> + </li> + </ul> + </p> + </subsection> + <p> + </p> </section> <section name='Example of Portlets'>
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]