UIManager


1   package org.apache.turbine.tool;
2   
3   /* ====================================================================
4    * The Apache Software License, Version 1.1
5    *
6    * Copyright (c) 2001 The Apache Software Foundation.  All rights
7    * reserved.
8    *
9    * Redistribution and use in source and binary forms, with or without
10   * modification, are permitted provided that the following conditions
11   * are met:
12   *
13   * 1. Redistributions of source code must retain the above copyright
14   *    notice, this list of conditions and the following disclaimer.
15   *
16   * 2. Redistributions in binary form must reproduce the above copyright
17   *    notice, this list of conditions and the following disclaimer in
18   *    the documentation and/or other materials provided with the
19   *    distribution.
20   *
21   * 3. The end-user documentation included with the redistribution,
22   *    if any, must include the following acknowledgment:
23   *       "This product includes software developed by the
24   *        Apache Software Foundation (http://www.apache.org/)."
25   *    Alternately, this acknowledgment may appear in the software itself,
26   *    if and wherever such third-party acknowledgments normally appear.
27   *
28   * 4. The names "Apache" and "Apache Software Foundation" and
29   *    "Apache Turbine" must not be used to endorse or promote products
30   *    derived from this software without prior written permission. For
31   *    written permission, please contact apache@apache.org.
32   *
33   * 5. Products derived from this software may not be called "Apache",
34   *    "Apache Turbine", nor may "Apache" appear in their name, without
35   *    prior written permission of the Apache Software Foundation.
36   *
37   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
38   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
39   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
40   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
41   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
42   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
43   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
44   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
45   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
46   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
47   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
48   * SUCH DAMAGE.
49   * ====================================================================
50   *
51   * This software consists of voluntary contributions made by many
52   * individuals on behalf of the Apache Software Foundation.  For more
53   * information on the Apache Software Foundation, please see
54   * <http://www.apache.org/>.
55   */
56  
57  import java.io.FileInputStream  ;
58  import java.util.Properties  ;
59  
60  import org.apache.commons.logging.Log;
61  import org.apache.commons.logging.LogFactory;
62  import org.apache.fulcrum.TurbineServices;
63  import org.apache.fulcrum.security.entity.User;
64  import org.apache.turbine.RunData;
65  import org.apache.turbine.Turbine;
66  import org.apache.turbine.services.pull.ApplicationTool;
67  import org.apache.turbine.services.pull.PullService;
68  
69  /**
70   * UIManager.java
71   * <br>
72   * Manages all UI elements for a Turbine Application. Any
73   * UI element can be accessed in any template using the
74   * $ui handle (assuming you use the default PullService
75   * configuration). So, for example, you could access
76   * the background colour for your pages by using
77   * $ui.bgcolor
78   * <p>
79   * <h3>Questions:</h3>
80   * What is the best way to allow an application
81   * to be skinned. And how to allow the flexible
82   * altering of a particular UI element in certain
83   * parts of the template hierarchy. For example
84   * on one section of your site you might like
85   * a certain bgcolor, on another part of your
86   * site you might want another. How can be let
87   * the designer specify these properties and
88   * still use the single $app.ui.bgcolor in
89   * all the templates.
90   * <p>
91   * It would also be very cool to use some form
92   * of inheritence for UI elements. Say a $ui.bgcolor
93   * is used in a template where the bgcolor is not
94   * set for that part of hierarch, it would be cool
95   * if it could find the setting for the bgcolor
96   * in the parent directory. So you could override
97   * a UI element where you wanted and the system
98   * would fall back to the parent when necessary.
99   * <p>
100  * How to specify skins, how to deal with images,
101  * how could this be handled with a web app.
102  *
103  * @author <a HREF="mailto:jvanzyl@periapt.com">Jason van Zyl</a>
104  * @author <a HREF="mailto:james_coltman@majorband.co.uk">James Coltman</a>
105  * @version $Id: UIManager.java,v 1.2 2004/11/12 10:25:37 epugh Exp $
106  */
107 public class UIManager implements ApplicationTool
108 {
109     private static final Log log = LogFactory.getLog( UIManager.class );
110 
111     /**
112      * The location of the skins within the application
113      * resources directory.
114      */
115     private static final String   SKINS_DIRECTORY = "/ui/skins";
116 
117     /**
118      * The name of the directory where images are
119      * stored for this skin.
120      */
121     private static final String   IMAGES_DIRECTORY = "/images";
122 
123 
124     /**
125      * Property tag for the skin that is to be
126      * used for the web application.
127      */
128     private static final String   SKIN_PROPERTY = "tool.ui.skin";
129 
130     /**
131      * Default skin name. This name actually represents
132      * a directory in the WEBAPP/resources/ui/skins
133      * directory. There is a file called skin.props
134      * which actually contains the name/value pairs.
135      */
136     private static final String   SKIN_PROPERTY_DEFAULT = "default";
137 
138     /**
139      * Attribute name of skinName value in User's temp hashmap.
140      */
141     private static final String   SKIN_ATTRIBUTE =
142         "org.apache.fulcrum.pull.util.UIManager.skin";
143 
144     /**
145      * The actual skin being used for the webapp.
146      */
147     private String   skinName;
148 
149     /**
150      * The skins directory.
151      */
152     private static String   skinsDirectory;
153 
154     /**
155      * The file within the skin directory that actually
156      * contains the name/value pairs for the skin.
157      */
158     private static final String   SKIN_PROPS_FILE = "skin.props";
159 
160     /**
161      * The file name for the skin style sheet.
162      */
163     private static final String   SKIN_CSS_FILE = "skin.css";
164 
165     /**
166      * This the resources directory relative to the
167      * webapp context. Used for constructing correct
168      * URIs for retrieving images in image().
169      */
170     private static String   resourcesDirectory;
171 
172     /**
173      * Properties to hold the name/value pairs
174      * for the skin.
175      */
176     private static Properties   skinProperties;
177 
178     /**
179      * Initialize the UIManager object.
180      *
181      * @param data This is null, RunData or User depending upon specified tool scope.
182      */
183     public void init(Object   data)
184     {
185         /**
186          * Store the resources directory for use in image().
187          */
188         
189         resourcesDirectory = getPullService().getResourcesDirectory();
190 
191         if (data == null)
192         {
193             log.debug("UI Manager scope is global");
194             setSkin();
195         }
196         else if (data instanceof RunData)
197         {
198             log.debug("UI Manager scope is request");
199             setSkin((RunData) data);
200         }
201         else if (data instanceof User)
202         {
203             log.debug("UI Manager scope is session");
204             setSkin((User) data);
205         }
206 
207         skinsDirectory =
208             getPullService().getAbsolutePathToResourcesDirectory() + SKINS_DIRECTORY;
209 
210         loadSkin();
211     }
212 
213     /**
214      * This lets the tool know that it should be
215      * refreshed. The tool can perform whatever actions
216      * are necessary to refresh itself. This is necessary
217      * for sane development where you probably want the
218      * tools to refresh themselves on every request.
219      */
220     public void refresh()
221     {
222         log.debug("Refreshing UI manager");
223 
224         loadSkin();
225     }
226 
227     /**
228      * Retrieve a property from the properties held
229      * within the properties file for this skin.
230      */
231     public String   get(String   key)
232     {
233         return skinProperties.getProperty(key);
234     }
235 
236     /**
237      * Retrieve the skin name.
238      */
239     public String   getSkin()
240     {
241         return skinName;
242     }
243 
244     /**
245      * Retrieve the URL for an image that is part
246      * of a skin. The images are stored in the
247      * WEBAPP/resources/ui/skins/<SKIN>/images
248      * directory.
249      *
250      * Use this if for some reason your server name,
251      * server scheme, or server port change on a
252      * per request basis. I'm not sure if this
253      * would happend in a load balanced situation.
254      * I think in most cases the image(String image)
255      * method would probably be enough, but I'm not
256      * absolutely positive.
257      */
258     public String   image(String   imageId, RunData data)
259     {
260         ContentURI cu = new ContentURI(data);
261         StringBuffer   sb = new StringBuffer  ();
262 
263         sb.append(resourcesDirectory).
264            append(SKINS_DIRECTORY).
265            append("/").
266            append(getSkin()).
267            append(IMAGES_DIRECTORY).
268            append("/").
269            append(imageId);
270 
271         return cu.getURI(sb.toString());
272     }
273 
274     /**
275      * Retrieve the URL for an image that is part
276      * of a skin. The images are stored in the
277      * WEBAPP/resources/ui/skins/<SKIN>/images
278      * directory.
279      */
280     public String   image(String   imageId)
281     {
282         StringBuffer   sb = new StringBuffer  ();
283 
284         sb.append(Turbine.getServerScheme()).
285            append("://").
286            append(Turbine.getServerName()).
287            append(":").
288            append(Turbine.getServerPort()).
289            append(Turbine.getApplicationRoot()).
290            append("/").
291            append(resourcesDirectory).
292            append(SKINS_DIRECTORY).
293            append("/").
294            append(getSkin()).
295            append(IMAGES_DIRECTORY).
296            append("/").
297            append(imageId);
298 
299         return sb.toString();
300     }
301 
302     /**
303      * Retrieve the URL for the style sheet that is part
304      * of a skin. The style is stored in the
305      * WEBAPP/resources/ui/skins/<SKIN> directory with the
306      * filename skin.css
307      *
308      * Use this if for some reason your server name,
309      * server scheme, or server port change on a
310      * per request basis. I'm not sure if this
311      * would happend in a load balanced situation.
312      * I think in most cases the style()
313      * method would probably be enough, but I'm not
314      * absolutely positive.
315      */
316     public String   getStylecss(RunData data)
317     {
318         ContentURI cu = new ContentURI(data);
319         StringBuffer   sb = new StringBuffer  ();
320 
321         sb.append(resourcesDirectory).
322            append(SKINS_DIRECTORY).
323            append("/").
324            append(getSkin()).
325            append("/").
326            append(SKIN_CSS_FILE);
327 
328         return cu.getURI(sb.toString());
329     }
330 
331     /**
332      * Retrieve the URL for the style sheet that is part
333      * of a skin. The style is stored in the
334      * WEBAPP/resources/ui/skins/<SKIN> directory with the
335      * filename skin.css
336      */
337     public String   getStylecss()
338     {
339         StringBuffer   sb = new StringBuffer  ();
340 
341         sb.append(Turbine.getServerScheme()).
342            append("://").
343            append(Turbine.getServerName()).
344            append(":").
345            append(Turbine.getServerPort()).
346            append(Turbine.getApplicationRoot()).
347            append("/").
348            append(resourcesDirectory).
349            append(SKINS_DIRECTORY).
350            append("/").
351            append(getSkin()).
352            append("/").
353            append(SKIN_CSS_FILE);
354 
355         return sb.toString();
356     }
357 
358     /**
359      * Load the specified skin. In development mode
360      * this may occur frequently as the skin properties
361      * are being changed.
362      */
363     private void loadSkin()
364     {
365         skinProperties = new Properties  ();
366 
367         try
368         {
369             FileInputStream   is = new FileInputStream  (
370                 skinsDirectory + "/" + getSkin() + "/" + SKIN_PROPS_FILE);
371 
372             skinProperties.load(is);
373         }
374         catch (Exception   e)
375         {
376             log.error("Cannot load skin: " + skinName);
377         }
378     }
379 
380     /**
381      * Set the skin name to the skin from the TR.props
382      * file. If the property is not present use the
383      * default skin.
384      */
385     public void setSkin()
386     {
387         this.skinName = Turbine.getConfiguration().getString(SKIN_PROPERTY,
388                 SKIN_PROPERTY_DEFAULT);
389     }
390 
391     /**
392      * Set the skin name to the specified skin.
393      *
394      * @param skinName the skin name to use.
395      */
396     public void setSkin(String   skinName)
397     {
398         this.skinName = skinName;
399     }
400 
401     /**
402      * Set the skin name when the tool is configured to be
403      * loaded on a per-request basis. By default it calls getSkin
404      * to return the skin specified in TR.properties. Developers can
405      * write a subclass of UIManager that overrides this method to
406      * determine the skin to use based on information held in the request.
407      *
408      * @param data a RunData instance
409      */
410     protected void setSkin(RunData data)
411     {
412         setSkin();
413     }
414 
415     /**
416      * Set the skin name when the tool is configured to be
417      * loaded on a per-session basis. It the user's temp hashmap contains
418      * a value in the attribute specified by the String constant SKIN_ATTRIBUTE
419      * then that is returned. Otherwise it calls getSkin to return the skin
420      * specified in TR.properties.
421      *
422      * @param user a User instance
423      */
424     protected void setSkin(User user)
425     {
426         if (user.getTemp(SKIN_ATTRIBUTE) == null)
427         {
428             setSkin();
429         }
430         else
431         {
432             setSkin((String  ) user.getTemp(SKIN_ATTRIBUTE));
433         }
434     }
435 
436     /**
437      * Set the skin name user's temp hashmap for the current session.
438      *
439      * @param user a User instance
440      * @param skin the skin name for the session
441      */
442     public static void setSkin(User user, String   skin)
443     {
444         user.setTemp(SKIN_ATTRIBUTE, skin);
445     }
446     
447     /**
448      * Utility method for accessing the service
449      * implementation
450      *
451      * @return a PullService implementation instance
452      */
453     protected static PullService getPullService()
454     {
455         return (PullService)TurbineServices
456             .getInstance().getService(PullService.SERVICE_NAME);
457     }    
458 }
459
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags