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