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 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   * @see UIService
    37   * @see UITool
    38   */
    39  public interface UIService extends Service
    40  {
    41      /**
    42       * The service identifier.
    43       */
    44      public String SERVICE_NAME = "UIService";
    45
    46      /**
    47       * Refresh all skins.
    48       */
    49      public void refresh();
    50
    51      /**
    52       * Refresh a particular skin.
    53       *
    54       * @param skinName the name of the skin to clear.
    55       */
    56      public void refresh(String skinName);
    57
    58      /**
    59       * Provide access to the list of available skin names.
    60       *
    61       * @return the available skin names.
    62       */
    63      public String[] getSkinNames();
    64
    65      /**
    66       * Get the name of the default skin name for the web application from the
    67       * TurbineResources.properties file. If the property is not present the
    68       * name of the default skin will be returned.  Note that the web application
    69       * skin name may be something other than default, in which case its
    70       * properties will default to the skin with the name "default".
    71       *
    72       * @return the name of the default skin for the web application.
    73       */
    74      public String getWebappSkinName();
    75
    76      /**
    77       * Retrieve a skin property from the named skin.  If the property is not
    78       * defined in the named skin the value for the default skin will be
    79       * provided.  If the named skin does not exist then the skin configured for
    80       * the webapp will be used.  If the webapp skin does not exist the default
    81       * skin will be used.  If the default skin does not exist then
    82       * <code>null</code> will be returned.
    83       *
    84       * @param skinName the name of the skin to retrieve the property from.
    85       * @param key the key to retrieve from the skin.
    86       * @return the value of the property for the named skin (defaulting to the
    87       * default skin), the webapp skin, the default skin or <code>null</code>,
    88       * depending on whether or not the property or skins exist.
    89       */
    90      public String get(String skinName, String key);
    91
    92      /**
    93       * Retrieve a skin property from the default skin for the webapp.  If the
    94       * property is not defined in the webapp skin the value for the default skin
    95       * will be provided.  If the webapp skin does not exist the default skin
    96       * will be used.  If the default skin does not exist then <code>null</code>
    97       * will be returned.
    98       *
    99       * @param key the key to retrieve.
    100      * @return the value of the property for the webapp skin (defaulting to the
    101      * default skin), the default skin or <code>null</code>, depending on
    102      * whether or not the property or skins exist.
    103      */
    104     public String get(String key);
    105
    106     /**
    107      * Retrieve the URL for an image that is part of a skin. The images are
    108      * stored in the WEBAPP/resources/ui/skins/[SKIN]/images directory.
    109      *
    110      * <p>Use this if for some reason your server name, server scheme, or server
    111      * port change on a per request basis. I'm not sure if this would happen in
    112      * a load balanced situation. I think in most cases the image(String image)
    113      * method would probably be enough, but I'm not absolutely positive.
    114      *
    115      * @param skinName the name of the skin to retrieve the image from.
    116      * @param imageId the id of the image whose URL will be generated.
    117      * @param serverData the serverData to use as the basis for the URL.
    118      */
    119     public String image(String skinName, String imageId, ServerData serverData);
    120
    121     /**
    122      * Retrieve the URL for an image that is part of a skin. The images are
    123      * stored in the WEBAPP/resources/ui/skins/[SKIN]/images directory.
    124      *
    125      * @param skinName the name of the skin to retrieve the image from.
    126      * @param imageId the id of the image whose URL will be generated.
    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      */
    143     public String getStylecss(String skinName, ServerData serverData);
    144
    145     /**
    146      * Retrieve the URL for the style sheet that is part of a skin. The style is
    147      * stored in the WEBAPP/resources/ui/skins/[SKIN] directory with the
    148      * filename skin.css
    149      *
    150      * @param skinName the name of the skin to retrieve the style sheet from.
    151      */
    152     public String getStylecss(String skinName);
    153
    154     /**
    155      * Retrieve the URL for a given script that is part of a skin. The script is
    156      * stored in the WEBAPP/resources/ui/skins/[SKIN] directory.
    157      *
    158      * <p>Use this if for some reason your server name, server scheme, or server
    159      * port change on a per request basis. I'm not sure if this would happen in
    160      * a load balanced situation. I think in most cases the style() method would
    161      * probably be enough, but I'm not absolutely positive.
    162      *
    163      * @param skinName the name of the skin to retrieve the image from.
    164      * @param filename the name of the script file.
    165      * @param serverData the serverData to use as the basis for the URL.
    166      */
    167     public String getScript(String skinName, String filename,
    168             ServerData serverData);
    169
    170     /**
    171      * Retrieve the URL for a given script that is part of a skin. The script is
    172      * stored in the WEBAPP/resources/ui/skins/[SKIN] directory.
    173      *
    174      * @param skinName the name of the skin to retrieve the image from.
    175      * @param filename the name of the script file.
    176      */
    177     public String getScript(String skinName, String filename);
    178
    179 }