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