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