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    String SERVICE_NAME = "UIService";
042
043    /**
044     * Refresh all skins.
045     */
046    void refresh();
047
048    /**
049     * Refresh a particular skin.
050     *
051     * @param skinName the name of the skin to clear.
052     */
053    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    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    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    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    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    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    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    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    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    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    String getScript(String skinName, String filename);
181
182}