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: * The service identifier.
042: */
043: public String SERVICE_NAME = "UIService";
044:
045: /**
046: * Refresh all skins.
047: */
048: public void refresh();
049:
050: /**
051: * Refresh a particular skin.
052: *
053: * @param skinName the name of the skin to clear.
054: */
055: public void refresh(String skinName);
056:
057: /**
058: * Provide access to the list of available skin names.
059: *
060: * @return the available skin names.
061: */
062: public String[] getSkinNames();
063:
064: /**
065: * Get the name of the default skin name for the web application from the
066: * TurbineResources.properties file. If the property is not present the
067: * name of the default skin will be returned. Note that the web application
068: * skin name may be something other than default, in which case its
069: * properties will default to the skin with the name "default".
070: *
071: * @return the name of the default skin for the web application.
072: */
073: public String getWebappSkinName();
074:
075: /**
076: * Retrieve a skin property from the named skin. If the property is not
077: * defined in the named skin the value for the default skin will be
078: * provided. If the named skin does not exist then the skin configured for
079: * the webapp will be used. If the webapp skin does not exist the default
080: * skin will be used. If the default skin does not exist then
081: * <code>null</code> will be returned.
082: *
083: * @param skinName the name of the skin to retrieve the property from.
084: * @param key the key to retrieve from the skin.
085: * @return the value of the property for the named skin (defaulting to the
086: * default skin), the webapp skin, the default skin or <code>null</code>,
087: * depending on whether or not the property or skins exist.
088: */
089: public String get(String skinName, String key);
090:
091: /**
092: * Retrieve a skin property from the default skin for the webapp. If the
093: * property is not defined in the webapp skin the value for the default skin
094: * will be provided. If the webapp skin does not exist the default skin
095: * will be used. If the default skin does not exist then <code>null</code>
096: * will be returned.
097: *
098: * @param key the key to retrieve.
099: * @return the value of the property for the webapp skin (defaulting to the
100: * default skin), the default skin or <code>null</code>, depending on
101: * whether or not the property or skins exist.
102: */
103: public String get(String key);
104:
105: /**
106: * Retrieve the URL for an image that is part of a skin. The images are
107: * stored in the WEBAPP/resources/ui/skins/[SKIN]/images directory.
108: *
109: * <p>Use this if for some reason your server name, server scheme, or server
110: * port change on a per request basis. I'm not sure if this would happen in
111: * a load balanced situation. I think in most cases the image(String image)
112: * method would probably be enough, but I'm not absolutely positive.
113: *
114: * @param skinName the name of the skin to retrieve the image from.
115: * @param imageId the id of the image whose URL will be generated.
116: * @param serverData the serverData to use as the basis for the URL.
117: */
118: public String image(String skinName, String imageId,
119: 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: }
|