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    }