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.om.security.User;
25  import org.apache.turbine.pipeline.PipelineData;
26  import org.apache.turbine.services.pull.ApplicationTool;
27  import org.apache.turbine.services.ui.TurbineUI;
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       * Refresh the tool.
81       */
82      @Override
83      public void refresh()
84      {
85          TurbineUI.refresh(getSkin());
86          log.debug("UITool refreshed for skin: " + getSkin());
87      }
88  
89      /**
90       * Provide access to the list of available skin names.
91       *
92       * @return the available skin names.
93       */
94      public String[] getSkinNames()
95      {
96          return TurbineUI.getSkinNames();
97      }
98  
99      /**
100      * Get the name of the default skin name for the web application from the
101      * TurbineResources.properties file. If the property is not present the
102      * name of the default skin will be returned.  Note that the web application
103      * skin name may be something other than default, in which case its
104      * properties will default to the skin with the name "default".
105      *
106      * @return the name of the default skin for the web application.
107      */
108     public String getWebappSkinName()
109     {
110         return TurbineUI.getWebappSkinName();
111     }
112 
113     /**
114      * Retrieve a skin property.  If the property is not defined in the current
115      * skin the value for the default skin will be provided.  If the current
116      * skin does not exist then the skin configured for the webapp will be used.
117      * If the webapp skin does not exist the default skin will be used.  If the
118      * default skin does not exist then <code>null</code> will be returned.
119      *
120      * @param key the key to retrieve from the skin.
121      * @return the value of the property for the named skin (defaulting to the
122      * default skin), the webapp skin, the default skin or <code>null</code>,
123      * depending on whether or not the property or skins exist.
124      */
125     public String get(String key)
126     {
127         return TurbineUI.get(getSkin(), key);
128     }
129 
130     /**
131      * Retrieve the skin name.
132      * @return the selected skin name
133      */
134     public String getSkin()
135     {
136         return skinName;
137     }
138 
139     /**
140      * Set the skin name to the skin from the TurbineResources.properties file.
141      * If the property is not present use the "default" skin.
142      */
143     public void setSkin()
144     {
145         skinName = TurbineUI.getWebappSkinName();
146     }
147 
148     /**
149      * Set the skin name to the specified skin.
150      *
151      * @param skinName the skin name to use.
152      */
153     public void setSkin(String skinName)
154     {
155         this.skinName = skinName;
156     }
157 
158     /**
159      * Set the skin name when the tool is configured to be loaded on a
160      * per-request basis. By default it calls getSkin to return the skin
161      * specified in TurbineResources.properties. Developers can write a subclass
162      * of UITool that overrides this method to determine the skin to use based
163      * on information held in the request.
164      *
165      * @param data a RunData instance
166      */
167     protected void setSkin(RunData data)
168     {
169         setSkin();
170     }
171 
172     /**
173      * Set the skin name when the tool is configured to be loaded on a
174      * per-session basis. If the user's temp hashmap contains a value in the
175      * attribute specified by the String constant SKIN_ATTRIBUTE then that is
176      * returned. Otherwise it calls getSkin to return the skin specified in
177      * TurbineResources.properties.
178      *
179      * @param user a User instance
180      */
181     protected void setSkin(User user)
182     {
183         if (user.getTemp(SKIN_ATTRIBUTE) == null)
184         {
185             setSkin();
186         }
187         else
188         {
189             setSkin((String) user.getTemp(SKIN_ATTRIBUTE));
190         }
191     }
192 
193     /**
194      * Set the skin name in the user's temp hashmap for the current session.
195      *
196      * @param user a User instance
197      * @param skin the skin name for the session
198      */
199     public static void setSkin(User user, String skin)
200     {
201         user.setTemp(SKIN_ATTRIBUTE, skin);
202     }
203 
204     /**
205      * Retrieve the URL for an image that is part of the skin. The images are
206      * stored in the WEBAPP/resources/ui/skins/[SKIN]/images directory.
207      *
208      * <p>Use this if for some reason your server name, server scheme, or server
209      * port change on a per request basis. I'm not sure if this would happen in
210      * a load balanced situation. I think in most cases the image(String image)
211      * method would probably be enough, but I'm not absolutely positive.
212      *
213      * @param imageId the id of the image whose URL will be generated.
214      * @param data the RunData to use as the source of the ServerData to use as
215      * the basis for the URL.
216      * @return the image URL
217      */
218     public String image(String imageId, RunData data)
219     {
220         return image(imageId, data.getServerData());
221     }
222 
223     /**
224      * Retrieve the URL for an image that is part of the skin. The images are
225      * stored in the WEBAPP/resources/ui/skins/[SKIN]/images directory.
226      *
227      * <p>Use this if for some reason your server name, server scheme, or server
228      * port change on a per request basis. I'm not sure if this would happen in
229      * a load balanced situation. I think in most cases the image(String image)
230      * method would probably be enough, but I'm not absolutely positive.
231      *
232      * @param imageId the id of the image whose URL will be generated.
233      * @param serverData the serverData to use as the basis for the URL.
234      * @return the image URL
235      */
236     public String image(String imageId, ServerData serverData)
237     {
238         return TurbineUI.image(getSkin(), imageId, serverData);
239     }
240 
241     /**
242      * Retrieve the URL for an image that is part of the skin. The images are
243      * stored in the WEBAPP/resources/ui/skins/[SKIN]/images directory.
244      *
245      * @param imageId the id of the image whose URL will be generated.
246      * @return the image URL
247      */
248     public String image(String imageId)
249     {
250         return TurbineUI.image(getSkin(), imageId);
251     }
252 
253     /**
254      * Retrieve the URL for the style sheet that is part of the skin. The style
255      * is stored in the WEBAPP/resources/ui/skins/[SKIN] directory with the
256      * filename skin.css
257      *
258      * <p>Use this if for some reason your server name, server scheme, or server
259      * port change on a per request basis. I'm not sure if this would happen in
260      * a load balanced situation. I think in most cases the style() method would
261      * probably be enough, but I'm not absolutely positive.
262      *
263      * @param data the RunData to use as the source of the ServerData to use as
264      * the basis for the URL.
265      * @return the CSS URL
266      */
267     public String getStylecss(RunData data)
268     {
269         return getStylecss(data.getServerData());
270     }
271 
272     /**
273      * Retrieve the URL for the style sheet that is part of the skin. The style
274      * is stored in the WEBAPP/resources/ui/skins/[SKIN] directory with the
275      * filename skin.css
276      *
277      * <p>Use this if for some reason your server name, server scheme, or server
278      * port change on a per request basis. I'm not sure if this would happen in
279      * a load balanced situation. I think in most cases the style() method would
280      * probably be enough, but I'm not absolutely positive.
281      *
282      * @param serverData the serverData to use as the basis for the URL.
283      * @return the CSS URL
284      */
285     public String getStylecss(ServerData serverData)
286     {
287         return TurbineUI.getStylecss(getSkin(), serverData);
288     }
289 
290     /**
291      * Retrieve the URL for the style sheet that is part of the skin. The style
292      * is stored in the WEBAPP/resources/ui/skins/[SKIN] directory with the
293      * filename skin.css
294      * @return the CSS URL
295      */
296     public String getStylecss()
297     {
298         return TurbineUI.getStylecss(getSkin());
299     }
300 
301     /**
302      * Retrieve the URL for a given script that is part of the skin. The script
303      * is stored in the WEBAPP/resources/ui/skins/[SKIN] directory.
304      *
305      * <p>Use this if for some reason your server name, server scheme, or server
306      * port change on a per request basis. I'm not sure if this would happen in
307      * a load balanced situation. I think in most cases the image(String image)
308      * method would probably be enough, but I'm not absolutely positive.
309      *
310      * @param filename the name of the script file whose URL will be generated.
311      * @param data the RunDate to use as the source of the ServerData to use as
312      * the basis for the URL.
313      * @return the script URL
314      */
315     public String getScript(String filename, RunData data)
316     {
317         return getScript(filename, data.getServerData());
318     }
319 
320     /**
321      * Retrieve the URL for a given script that is part of the skin. The script
322      * is stored in the WEBAPP/resources/ui/skins/[SKIN] directory.
323      *
324      * <p>Use this if for some reason your server name, server scheme, or server
325      * port change on a per request basis. I'm not sure if this would happen in
326      * a load balanced situation. I think in most cases the image(String image)
327      * method would probably be enough, but I'm not absolutely positive.
328      *
329      * @param filename the name of the script file whose URL will be generated.
330      * @param serverData the serverData to use as the basis for the URL.
331      * @return the script URL
332      */
333     public String getScript(String filename, ServerData serverData)
334     {
335         return TurbineUI.getScript(getSkin(), filename, serverData);
336     }
337 
338     /**
339      * Retrieve the URL for a given script that is part of the skin. The script
340      * is stored in the WEBAPP/resources/ui/skins/[SKIN] directory.
341      *
342      * @param filename the name of the script file whose URL will be generated.
343      * @return the script URL
344      */
345     public String getScript(String filename)
346     {
347         return TurbineUI.getScript(getSkin(), filename);
348     }
349 
350     /**
351      * Initialize the UITool object.
352      *
353      * @param data This is null, RunData or User depending upon specified tool
354      * scope.
355      */
356     @Override
357     public void init(Object data)
358     {
359         if (data == null)
360         {
361             log.debug("UITool scope is global");
362             setSkin();
363         }
364         else if (data instanceof RunData)
365         {
366             log.debug("UITool scope is request");
367             setSkin((RunData) data);
368         }
369         else if (data instanceof PipelineData)
370         {
371             PipelineData pipelineData = (PipelineData) data;
372             RunData runData = (RunData)pipelineData;
373             log.debug("UITool scope is request");
374             setSkin(runData);
375         }
376         else if (data instanceof User)
377         {
378             log.debug("UITool scope is session");
379             setSkin((User) data);
380         }
381     }
382 
383 }