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