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}