1 package org.apache.turbine.modules.screens;
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19 import org.apache.commons.logging.Log;
20 import org.apache.commons.logging.LogFactory;
21
22 import org.apache.ecs.ConcreteElement;
23
24 import org.apache.turbine.modules.Screen;
25 import org.apache.turbine.modules.ScreenLoader;
26
27 import org.apache.turbine.services.template.TurbineTemplate;
28
29 import org.apache.turbine.util.RunData;
30
31 /***
32 * Template Screen.
33 *
34 * Base Template Screens should extend this class and override the
35 * buildTemplate() method. Users of the particular service can then
36 * override the doBuildTemplate() for any specific pre-processing.
37 * You can also override the doBuild() method in order to add extra
38 * functionality to your system, but you need to make sure to at least
39 * duplicate the existing functionality in order for things to work.
40 * Look at the code for the doBuild() method to get an idea of what is
41 * going on there (it is quite simple really).
42 *
43 * @author <a href="mailto:mbryson@mont.mindspring.com">Dave Bryson</a>
44 * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
45 * @version $Id: TemplateScreen.java 264148 2005-08-29 14:21:04Z henning $
46 */
47 public abstract class TemplateScreen
48 extends Screen
49 {
50 /*** Logging */
51 protected Log log = LogFactory.getLog(this.getClass());
52
53 /***
54 * This method should be overidden by subclasses that wish to add
55 * specific business logic.
56 *
57 * @param data Turbine information.
58 * @exception Exception A generic exception.
59 */
60 protected abstract void doBuildTemplate(RunData data)
61 throws Exception;
62
63 /***
64 * This method should be implemented by Base template classes. It
65 * should contain the specific template service code to generate
66 * the template.
67 *
68 * @param data Turbine information.
69 * @return A ConcreteElement.
70 * @exception Exception A generic exception.
71 */
72 public abstract ConcreteElement buildTemplate(RunData data)
73 throws Exception;
74
75 /***
76 * This method can be overridden to write code that executes when
77 * the template has been built (called from a finally clause, so
78 * executes regardless of whether an exception is thrown or not)
79 */
80 protected void doPostBuildTemplate(RunData data)
81 {
82
83 }
84
85 /***
86 * This method is called by the Screenloader to construct the
87 * Screen.
88 *
89 * @param data Turbine information.
90 * @return A ConcreteElement.
91 * @exception Exception A generic exception.
92 */
93 protected ConcreteElement doBuild(RunData data)
94 throws Exception
95 {
96 ConcreteElement out = null;
97
98 try
99 {
100 doBuildTemplate(data);
101 out = buildTemplate(data);
102 }
103 finally
104 {
105 doPostBuildTemplate(data);
106 }
107
108 return out;
109 }
110
111 /***
112 * This method is used when you want to short circuit a Screen and
113 * change the template that will be executed next. <b>Note that the current
114 * context will be applied to the next template that is executed.
115 * If you want to have the context executed for the next screen,
116 * to be the same one as the next screen, then you should use the
117 * TemplateScreen.doRedirect() method.</b>
118 *
119 * @param data Turbine information.
120 * @param template The name of the next template.
121 */
122 public static void setTemplate(RunData data, String template)
123 {
124 data.getTemplateInfo().setScreenTemplate(template);
125 try
126 {
127
128
129 data.getTemplateInfo().setLayoutTemplate(
130 TurbineTemplate.getLayoutTemplateName(
131 data.getTemplateInfo().getScreenTemplate()));
132 }
133 catch (Exception e)
134 {
135
136 }
137 }
138
139 /***
140 * You can call this within a Screen to cause an internal redirect
141 * to happen. It essentially allows you to stop execution in one
142 * Screen and instantly execute another Screen. Don't worry, this
143 * does not do a HTTP redirect and also if you have anything added
144 * in the Context, it will get carried over.
145 *
146 * <p>
147 *
148 * This class is useful if you have a Screen that submits to
149 * another Screen and you want it to do error validation before
150 * executing the other Screen. If there is an error, you can
151 * doRedirect() back to the original Screen.
152 *
153 * @param data Turbine information.
154 * @param screen Name of screen to redirect to.
155 * @param template Name of template.
156 * @exception Exception A generic exception.
157 */
158 public void doRedirect(RunData data, String screen, String template)
159 throws Exception
160 {
161 log.debug("doRedirect(data, " + screen + ", " + template + ")");
162 setTemplate(data, template);
163 ScreenLoader.getInstance().exec(data, screen);
164 }
165
166 /***
167 * You can call this within a Screen to cause an internal redirect
168 * to happen. It essentially allows you to stop execution in one
169 * Screen and instantly execute another Screen. Don't worry, this
170 * does not do a HTTP redirect and also if you have anything added
171 * in the Context, it will get carried over.
172 *
173 * <p>
174 *
175 * This class is useful if you have a Screen that submits to
176 * another Screen and you want it to do error validation before
177 * executing the other Screen. If there is an error, you can
178 * doRedirect() back to the original Screen.
179 *
180 * @param data Turbine information.
181 * @param template Name of template.
182 * @exception Exception A generic exception.
183 */
184 public void doRedirect(RunData data, String template)
185 throws Exception
186 {
187 doRedirect(data, TurbineTemplate.getScreenName(template), template);
188 }
189 }