    001    package 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
    022    import org.apache.turbine.services.Service;
    023    import 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 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     * @see UIService
    037     * @see UITool
    038     */
    039    public interface UIService extends Service
    040    {
    041        /**
    042         * The service identifier.
    043         */
    044        public String SERVICE_NAME = "UIService";
    045
    046        /**
    047         * Refresh all skins.
    048         */
    049        public void refresh();
    050
    051        /**
    052         * Refresh a particular skin.
    053         *
    054         * @param skinName the name of the skin to clear.
    055         */
    056        public void refresh(String skinName);
    057
    058        /**
    059         * Provide access to the list of available skin names.
    060         *
    061         * @return the available skin names.
    062         */
    063        public String[] getSkinNames();
    064
    065        /**
    066         * Get the name of the default skin name for the web application from the
    067         * TurbineResources.properties file. If the property is not present the
    068         * name of the default skin will be returned.  Note that the web application
    069         * skin name may be something other than default, in which case its
    070         * properties will default to the skin with the name "default".
    071         *
    072         * @return the name of the default skin for the web application.
    073         */
    074        public String getWebappSkinName();
    075
    076        /**
    077         * Retrieve a skin property from the named skin.  If the property is not
    078         * defined in the named skin the value for the default skin will be
    079         * provided.  If the named skin does not exist then the skin configured for
    080         * the webapp will be used.  If the webapp skin does not exist the default
    081         * skin will be used.  If the default skin does not exist then
    082         * <code>null</code> will be returned.
    083         *
    084         * @param skinName the name of the skin to retrieve the property from.
    085         * @param key the key to retrieve from the skin.
    086         * @return the value of the property for the named skin (defaulting to the
    087         * default skin), the webapp skin, the default skin or <code>null</code>,
    088         * depending on whether or not the property or skins exist.
    089         */
    090        public String get(String skinName, String key);
    091
    092        /**
    093         * Retrieve a skin property from the default skin for the webapp.  If the
    094         * property is not defined in the webapp skin the value for the default skin
    095         * will be provided.  If the webapp skin does not exist the default skin
    096         * will be used.  If the default skin does not exist then <code>null</code>
    097         * will be returned.
    098         *
    099         * @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    }