View Javadoc

    1   package org.apache.turbine.services.ui;
    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.turbine.services.Service;
    23  import org.apache.turbine.util.ServerData;
    24
    25  /**
    26   * The UI service provides for shared access to User Interface (skin) files,
    27   * as well as the ability for non-default skin files to inherit properties from
    28   * a default skin.  Use {@link TurbineUI} to access skin properties from your screen
    29   * classes and action code. UITool is provided as a pull tool for accessing
    30   * skin properties from your templates.
    31   *
    32   * <p>Skins are lazy loaded in that they are not loaded until first used.
    33   *
    34   * @author <a href="mailto:seade@backstagetech.com.au">Scott Eade</a>
    35   * @version $Id$
    36   */
    37  public interface UIService extends Service
    38  {
    39      /**
    40       * The service identifier.
    41       */
    42      public String SERVICE_NAME = "UIService";
    43
    44      /**
    45       * Refresh all skins.
    46       */
    47      public void refresh();
    48
    49      /**
    50       * Refresh a particular skin.
    51       *
    52       * @param skinName the name of the skin to clear.
    53       */
    54      public void refresh(String skinName);
    55
    56      /**
    57       * Provide access to the list of available skin names.
    58       *
    59       * @return the available skin names.
    60       */
    61      public String[] getSkinNames();
    62
    63      /**
    64       * Get the name of the default skin name for the web application from the
    65       * TurbineResources.properties file. If the property is not present the
    66       * name of the default skin will be returned.  Note that the web application
    67       * skin name may be something other than default, in which case its
    68       * properties will default to the skin with the name "default".
    69       *
    70       * @return the name of the default skin for the web application.
    71       */
    72      public String getWebappSkinName();
    73
    74      /**
    75       * Retrieve a skin property from the named skin.  If the property is not
    76       * defined in the named skin the value for the default skin will be
    77       * provided.  If the named skin does not exist then the skin configured for
    78       * the webapp will be used.  If the webapp skin does not exist the default
    79       * skin will be used.  If the default skin does not exist then
    80       * <code>null</code> will be returned.
    81       *
    82       * @param skinName the name of the skin to retrieve the property from.
    83       * @param key the key to retrieve from the skin.
    84       * @return the value of the property for the named skin (defaulting to the
    85       * default skin), the webapp skin, the default skin or <code>null</code>,
    86       * depending on whether or not the property or skins exist.
    87       */
    88      public String get(String skinName, String key);
    89
    90      /**
    91       * Retrieve a skin property from the default skin for the webapp.  If the
    92       * property is not defined in the webapp skin the value for the default skin
    93       * will be provided.  If the webapp skin does not exist the default skin
    94       * will be used.  If the default skin does not exist then <code>null</code>
    95       * will be returned.
    96       *
    97       * @param key the key to retrieve.
    98       * @return the value of the property for the webapp skin (defaulting to the
    99       * default skin), the default skin or <code>null</code>, depending on
    100      * whether or not the property or skins exist.
    101      */
    102     public String get(String key);
    103
    104     /**
    105      * Retrieve the URL for an image that is part of a skin. The images are
    106      * stored in the WEBAPP/resources/ui/skins/[SKIN]/images directory.
    107      *
    108      * <p>Use this if for some reason your server name, server scheme, or server
    109      * port change on a per request basis. I'm not sure if this would happen in
    110      * a load balanced situation. I think in most cases the image(String image)
    111      * method would probably be enough, but I'm not absolutely positive.
    112      *
    113      * @param skinName the name of the skin to retrieve the image from.
    114      * @param imageId the id of the image whose URL will be generated.
    115      * @param serverData the serverData to use as the basis for the URL.
    116      * @return the image URL
    117      */
    118     public String image(String skinName, String imageId, ServerData serverData);
    119
    120     /**
    121      * Retrieve the URL for an image that is part of a skin. The images are
    122      * stored in the WEBAPP/resources/ui/skins/[SKIN]/images directory.
    123      *
    124      * @param skinName the name of the skin to retrieve the image from.
    125      * @param imageId the id of the image whose URL will be generated.
    126      * @return the image URL
    127      */
    128     public String image(String skinName, String imageId);
    129
    130     /**
    131      * Retrieve the URL for the style sheet that is part of a skin. The style is
    132      * stored in the WEBAPP/resources/ui/skins/[SKIN] directory with the
    133      * filename skin.css
    134      *
    135      * <p>Use this if for some reason your server name, server scheme, or server
    136      * port change on a per request basis. I'm not sure if this would happen in
    137      * a load balanced situation. I think in most cases the style() method would
    138      * probably be enough, but I'm not absolutely positive.
    139      *
    140      * @param skinName the name of the skin to retrieve the style sheet from.
    141      * @param serverData the serverData to use as the basis for the URL.
    142      * @return the CSS URL
    143      */
    144     public String getStylecss(String skinName, ServerData serverData);
    145
    146     /**
    147      * Retrieve the URL for the style sheet that is part of a skin. The style is
    148      * stored in the WEBAPP/resources/ui/skins/[SKIN] directory with the
    149      * filename skin.css
    150      *
    151      * @param skinName the name of the skin to retrieve the style sheet from.
    152      * @return the CSS URL
    153      */
    154     public String getStylecss(String skinName);
    155
    156     /**
    157      * Retrieve the URL for a given script that is part of a skin. The script is
    158      * stored in the WEBAPP/resources/ui/skins/[SKIN] directory.
    159      *
    160      * <p>Use this if for some reason your server name, server scheme, or server
    161      * port change on a per request basis. I'm not sure if this would happen in
    162      * a load balanced situation. I think in most cases the style() method would
    163      * probably be enough, but I'm not absolutely positive.
    164      *
    165      * @param skinName the name of the skin to retrieve the image from.
    166      * @param filename the name of the script file.
    167      * @param serverData the serverData to use as the basis for the URL.
    168      * @return the script URL
    169      */
    170     public String getScript(String skinName, String filename,
    171             ServerData serverData);
    172
    173     /**
    174      * Retrieve the URL for a given script that is part of a skin. The script is
    175      * stored in the WEBAPP/resources/ui/skins/[SKIN] directory.
    176      *
    177      * @param skinName the name of the skin to retrieve the image from.
    178      * @param filename the name of the script file.
    179      * @return the script URL
    180      */
    181     public String getScript(String skinName, String filename);
    182
    183 }