    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. UITool is provided as a pull tool for accessing
    029 * skin properties from your templates.
    030 *
    031 * <p>Skins are lazy loaded in that they are not loaded until first used.
    032 *
    033 * @author <a href="mailto:seade@backstagetech.com.au">Scott Eade</a>
    034 * @version $Id$
    035 */
    036public interface UIService extends Service
    037{
    038    /**
    039     * The service identifier.
    040     */
    041    public String SERVICE_NAME = "UIService";
    042
    043    /**
    044     * Refresh all skins.
    045     */
    046    public void refresh();
    047
    048    /**
    049     * Refresh a particular skin.
    050     *
    051     * @param skinName the name of the skin to clear.
    052     */
    053    public void refresh(String skinName);
    054
    055    /**
    056     * Provide access to the list of available skin names.
    057     *
    058     * @return the available skin names.
    059     */
    060    public String[] getSkinNames();
    061
    062    /**
    063     * Get the name of the default skin name for the web application from the
    064     * TurbineResources.properties file. If the property is not present the
    065     * name of the default skin will be returned.  Note that the web application
    066     * skin name may be something other than default, in which case its
    067     * properties will default to the skin with the name "default".
    068     *
    069     * @return the name of the default skin for the web application.
    070     */
    071    public String getWebappSkinName();
    072
    073    /**
    074     * Retrieve a skin property from the named skin.  If the property is not
    075     * defined in the named skin the value for the default skin will be
    076     * provided.  If the named skin does not exist then the skin configured for
    077     * the webapp will be used.  If the webapp skin does not exist the default
    078     * skin will be used.  If the default skin does not exist then
    079     * <code>null</code> will be returned.
    080     *
    081     * @param skinName the name of the skin to retrieve the property from.
    082     * @param key the key to retrieve from the skin.
    083     * @return the value of the property for the named skin (defaulting to the
    084     * default skin), the webapp skin, the default skin or <code>null</code>,
    085     * depending on whether or not the property or skins exist.
    086     */
    087    public String get(String skinName, String key);
    088
    089    /**
    090     * Retrieve a skin property from the default skin for the webapp.  If the
    091     * property is not defined in the webapp skin the value for the default skin
    092     * will be provided.  If the webapp skin does not exist the default skin
    093     * will be used.  If the default skin does not exist then <code>null</code>
    094     * will be returned.
    095     *
    096     * @param key the key to retrieve.
    097     * @return the value of the property for the webapp skin (defaulting to the
    098     * default skin), the default skin or <code>null</code>, depending on
    099     * 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}