    001package org.apache.turbine.services.ui;
    002
    003/*
    004 * Licensed to the Apache Software Foundation (ASF) under one
    005 * or more contributor license agreements.  See the NOTICE file
    006 * distributed with this work for additional information
    007 * regarding copyright ownership.  The ASF licenses this file
    008 * to you under the Apache License, Version 2.0 (the
    009 * "License"); you may not use this file except in compliance
    010 * with the License.  You may obtain a copy of the License at
    011 *
    012 *   http://www.apache.org/licenses/LICENSE-2.0
    013 *
    014 * Unless required by applicable law or agreed to in writing,
    015 * software distributed under the License is distributed on an
    016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    017 * KIND, either express or implied.  See the License for the
    018 * specific language governing permissions and limitations
    019 * under the License.
    020 */
    021
    022import org.apache.turbine.services.Service;
    023import org.apache.turbine.util.ServerData;
    024
    025/**
    026 * The UI service provides for shared access to User Interface (skin) files,
    027 * as well as the ability for non-default skin files to inherit properties from
    028 * a default skin.  Use {@link TurbineUI} to access skin properties from your screen
    029 * classes and action code. UITool is provided as a pull tool for accessing
    030 * skin properties from your templates.
    031 *
    032 * <p>Skins are lazy loaded in that they are not loaded until first used.
    033 *
    034 * @author <a href="mailto:seade@backstagetech.com.au">Scott Eade</a>
    035 * @version $Id$
    036 */
    037public interface UIService extends Service
    038{
    039    /**
    040     * The service identifier.
    041     */
    042    public String SERVICE_NAME = "UIService";
    043
    044    /**
    045     * Refresh all skins.
    046     */
    047    public void refresh();
    048
    049    /**
    050     * Refresh a particular skin.
    051     *
    052     * @param skinName the name of the skin to clear.
    053     */
    054    public void refresh(String skinName);
    055
    056    /**
    057     * Provide access to the list of available skin names.
    058     *
    059     * @return the available skin names.
    060     */
    061    public String[] getSkinNames();
    062
    063    /**
    064     * Get the name of the default skin name for the web application from the
    065     * TurbineResources.properties file. If the property is not present the
    066     * name of the default skin will be returned.  Note that the web application
    067     * skin name may be something other than default, in which case its
    068     * properties will default to the skin with the name "default".
    069     *
    070     * @return the name of the default skin for the web application.
    071     */
    072    public String getWebappSkinName();
    073
    074    /**
    075     * Retrieve a skin property from the named skin.  If the property is not
    076     * defined in the named skin the value for the default skin will be
    077     * provided.  If the named skin does not exist then the skin configured for
    078     * the webapp will be used.  If the webapp skin does not exist the default
    079     * skin will be used.  If the default skin does not exist then
    080     * <code>null</code> will be returned.
    081     *
    082     * @param skinName the name of the skin to retrieve the property from.
    083     * @param key the key to retrieve from the skin.
    084     * @return the value of the property for the named skin (defaulting to the
    085     * default skin), the webapp skin, the default skin or <code>null</code>,
    086     * depending on whether or not the property or skins exist.
    087     */
    088    public String get(String skinName, String key);
    089
    090    /**
    091     * Retrieve a skin property from the default skin for the webapp.  If the
    092     * property is not defined in the webapp skin the value for the default skin
    093     * will be provided.  If the webapp skin does not exist the default skin
    094     * will be used.  If the default skin does not exist then <code>null</code>
    095     * will be returned.
    096     *
    097     * @param key the key to retrieve.
    098     * @return the value of the property for the webapp skin (defaulting to the
    099     * 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}