1 package org.apache.turbine.services.pull.tools;
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.turbine.om.security.User;
26 import org.apache.turbine.services.pull.ApplicationTool;
27 import org.apache.turbine.services.ui.TurbineUI;
28 import org.apache.turbine.util.RunData;
29 import org.apache.turbine.util.ServerData;
30
31 /***
32 * Manages all UI elements for a Turbine Application. Any UI element can be
33 * accessed in any template using the $ui handle (assuming you use the default
34 * PullService configuration). So, for example, you could access the background
35 * color for your pages by using $ui.bgcolor
36 * <p>
37 * This implementation provides a single level of inheritance in that if a
38 * property does not exist in a non-default skin, the value from the default
39 * skin will be used. By only requiring values different to those stored in
40 * the default skin to appear in the non-default skins the amount of memory
41 * consumed in cases where the UserManager instance is used at a non-global
42 * scope will potentially be reduced due to the fact that a shared instance of
43 * the default skin properties can be used. Note that this inheritance only
44 * applies to property values - it does not apply to any images or stylesheets
45 * that may form part of your skins.
46 * <p>
47 * This is an application pull tool for the template system. You should not
48 * use it in a normal application! Within Java code you should use TurbineUI.
49 * <p>
50 *
51 * This is an application pull tool for the template system. You should
52 * <strong>only</strong> use it in a normal application to set the skin
53 * attribute for a user (setSkin(User user, String skin)) and to initialize it
54 * for the user, otherwise use TurbineUI is probably the way to go.
55 *
56 * @author <a href="mailto:jvanzyl@periapt.com">Jason van Zyl</a>
57 * @author <a href="mailto:james_coltman@majorband.co.uk">James Coltman</a>
58 * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
59 * @author <a href="mailto:seade@backstagetech.com.au">Scott Eade</a>
60 * @version $Id$
61 * @see UIService
62 */
63 public class UITool implements ApplicationTool
64 {
65 /*** Logging */
66 private static Log log = LogFactory.getLog(UITool.class);
67
68 /***
69 * Attribute name of skinName value in User's temp hashmap.
70 */
71 public static final String SKIN_ATTRIBUTE = UITool.class.getName()+ ".skin";
72
73 /***
74 * The actual skin being used for the webapp.
75 */
76 private String skinName;
77
78 /***
79 * Refresh the tool.
80 */
81 public void refresh()
82 {
83 TurbineUI.refresh(getSkin());
84 log.debug("UITool refreshed for skin: " + getSkin());
85 }
86
87 /***
88 * Provide access to the list of available skin names.
89 *
90 * @return the available skin names.
91 */
92 public String[] getSkinNames()
93 {
94 return TurbineUI.getSkinNames();
95 }
96
97 /***
98 * Get the name of the default skin name for the web application from the
99 * TurbineResources.properties file. If the property is not present the
100 * name of the default skin will be returned. Note that the web application
101 * skin name may be something other than default, in which case its
102 * properties will default to the skin with the name "default".
103 *
104 * @return the name of the default skin for the web application.
105 */
106 public String getWebappSkinName()
107 {
108 return TurbineUI.getWebappSkinName();
109 }
110
111 /***
112 * Retrieve a skin property. If the property is not defined in the current
113 * skin the value for the default skin will be provided. If the current
114 * skin does not exist then the skin configured for the webapp will be used.
115 * If the webapp skin does not exist the default skin will be used. If the
116 * default skin does not exist then <code>null</code> will be returned.
117 *
118 * @param key the key to retrieve from the skin.
119 * @return the value of the property for the named skin (defaulting to the
120 * default skin), the webapp skin, the default skin or <code>null</code>,
121 * depending on whether or not the property or skins exist.
122 */
123 public String get(String key)
124 {
125 return TurbineUI.get(getSkin(), key);
126 }
127
128 /***
129 * Retrieve the skin name.
130 */
131 public String getSkin()
132 {
133 return skinName;
134 }
135
136 /***
137 * Set the skin name to the skin from the TurbineResources.properties file.
138 * If the property is not present use the "default" skin.
139 */
140 public void setSkin()
141 {
142 skinName = TurbineUI.getWebappSkinName();
143 }
144
145 /***
146 * Set the skin name to the specified skin.
147 *
148 * @param skinName the skin name to use.
149 */
150 public void setSkin(String skinName)
151 {
152 this.skinName = skinName;
153 }
154
155 /***
156 * Set the skin name when the tool is configured to be loaded on a
157 * per-request basis. By default it calls getSkin to return the skin
158 * specified in TurbineResources.properties. Developers can write a subclass
159 * of UITool that overrides this method to determine the skin to use based
160 * on information held in the request.
161 *
162 * @param data a RunData instance
163 */
164 protected void setSkin(RunData data)
165 {
166 setSkin();
167 }
168
169 /***
170 * Set the skin name when the tool is configured to be loaded on a
171 * per-session basis. If the user's temp hashmap contains a value in the
172 * attribute specified by the String constant SKIN_ATTRIBUTE then that is
173 * returned. Otherwise it calls getSkin to return the skin specified in
174 * TurbineResources.properties.
175 *
176 * @param user a User instance
177 */
178 protected void setSkin(User user)
179 {
180 if (user.getTemp(SKIN_ATTRIBUTE) == null)
181 {
182 setSkin();
183 }
184 else
185 {
186 setSkin((String) user.getTemp(SKIN_ATTRIBUTE));
187 }
188 }
189
190 /***
191 * Set the skin name in the user's temp hashmap for the current session.
192 *
193 * @param user a User instance
194 * @param skin the skin name for the session
195 */
196 public static void setSkin(User user, String skin)
197 {
198 user.setTemp(SKIN_ATTRIBUTE, skin);
199 }
200
201 /***
202 * Retrieve the URL for an image that is part of the skin. The images are
203 * stored in the WEBAPP/resources/ui/skins/[SKIN]/images directory.
204 *
205 * <p>Use this if for some reason your server name, server scheme, or server
206 * port change on a per request basis. I'm not sure if this would happen in
207 * a load balanced situation. I think in most cases the image(String image)
208 * method would probably be enough, but I'm not absolutely positive.
209 *
210 * @param imageId the id of the image whose URL will be generated.
211 * @param data the RunDate to use as the source of the ServerData to use as
212 * the basis for the URL.
213 */
214 public String image(String imageId, RunData data)
215 {
216 return image(imageId, data.getServerData());
217 }
218
219 /***
220 * Retrieve the URL for an image that is part of the skin. The images are
221 * stored in the WEBAPP/resources/ui/skins/[SKIN]/images directory.
222 *
223 * <p>Use this if for some reason your server name, server scheme, or server
224 * port change on a per request basis. I'm not sure if this would happen in
225 * a load balanced situation. I think in most cases the image(String image)
226 * method would probably be enough, but I'm not absolutely positive.
227 *
228 * @param imageId the id of the image whose URL will be generated.
229 * @param serverData the serverData to use as the basis for the URL.
230 */
231 public String image(String imageId, ServerData serverData)
232 {
233 return TurbineUI.image(getSkin(), imageId, serverData);
234 }
235
236 /***
237 * Retrieve the URL for an image that is part of the skin. The images are
238 * stored in the WEBAPP/resources/ui/skins/[SKIN]/images directory.
239 *
240 * @param imageId the id of the image whose URL will be generated.
241 */
242 public String image(String imageId)
243 {
244 return TurbineUI.image(getSkin(), imageId);
245 }
246
247 /***
248 * Retrieve the URL for the style sheet that is part of the skin. The style
249 * is stored in the WEBAPP/resources/ui/skins/[SKIN] directory with the
250 * filename skin.css
251 *
252 * <p>Use this if for some reason your server name, server scheme, or server
253 * port change on a per request basis. I'm not sure if this would happen in
254 * a load balanced situation. I think in most cases the style() method would
255 * probably be enough, but I'm not absolutely positive.
256 *
257 * @param data the RunDate to use as the source of the ServerData to use as
258 * the basis for the URL.
259 */
260 public String getStylecss(RunData data)
261 {
262 return getStylecss(data.getServerData());
263 }
264
265 /***
266 * Retrieve the URL for the style sheet that is part of the skin. The style
267 * is stored in the WEBAPP/resources/ui/skins/[SKIN] directory with the
268 * filename skin.css
269 *
270 * <p>Use this if for some reason your server name, server scheme, or server
271 * port change on a per request basis. I'm not sure if this would happen in
272 * a load balanced situation. I think in most cases the style() method would
273 * probably be enough, but I'm not absolutely positive.
274 *
275 * @param serverData the serverData to use as the basis for the URL.
276 */
277 public String getStylecss(ServerData serverData)
278 {
279 return TurbineUI.getStylecss(getSkin(), serverData);
280 }
281
282 /***
283 * Retrieve the URL for the style sheet that is part of the skin. The style
284 * is stored in the WEBAPP/resources/ui/skins/[SKIN] directory with the
285 * filename skin.css
286 */
287 public String getStylecss()
288 {
289 return TurbineUI.getStylecss(getSkin());
290 }
291
292 /***
293 * Retrieve the URL for a given script that is part of the skin. The script
294 * is stored in the WEBAPP/resources/ui/skins/[SKIN] directory.
295 *
296 * <p>Use this if for some reason your server name, server scheme, or server
297 * port change on a per request basis. I'm not sure if this would happen in
298 * a load balanced situation. I think in most cases the image(String image)
299 * method would probably be enough, but I'm not absolutely positive.
300 *
301 * @param filename the name of the script file whose URL will be generated.
302 * @param data the RunDate to use as the source of the ServerData to use as
303 * the basis for the URL.
304 */
305 public String getScript(String filename, RunData data)
306 {
307 return getScript(filename, data.getServerData());
308 }
309
310 /***
311 * Retrieve the URL for a given script that is part of the skin. The script
312 * is stored in the WEBAPP/resources/ui/skins/[SKIN] directory.
313 *
314 * <p>Use this if for some reason your server name, server scheme, or server
315 * port change on a per request basis. I'm not sure if this would happen in
316 * a load balanced situation. I think in most cases the image(String image)
317 * method would probably be enough, but I'm not absolutely positive.
318 *
319 * @param filename the name of the script file whose URL will be generated.
320 * @param serverData the serverData to use as the basis for the URL.
321 */
322 public String getScript(String filename, ServerData serverData)
323 {
324 return TurbineUI.getScript(getSkin(), filename, serverData);
325 }
326
327 /***
328 * Retrieve the URL for a given script that is part of the skin. The script
329 * is stored in the WEBAPP/resources/ui/skins/[SKIN] directory.
330 *
331 * @param filename the name of the script file whose URL will be generated.
332 */
333 public String getScript(String filename)
334 {
335 return TurbineUI.getScript(getSkin(), filename);
336 }
337
338 /***
339 * Initialize the UITool object.
340 *
341 * @param data This is null, RunData or User depending upon specified tool
342 * scope.
343 */
344 public void init(Object data)
345 {
346 if (data == null)
347 {
348 log.debug("UITool scope is global");
349 setSkin();
350 }
351 else if (data instanceof RunData)
352 {
353 log.debug("UITool scope is request");
354 setSkin((RunData) data);
355 }
356 else if (data instanceof User)
357 {
358 log.debug("UITool scope is session");
359 setSkin((User) data);
360 }
361 }
362
363 }