1 package org.apache.turbine.services.ui;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import org.apache.turbine.services.Service;
23 import org.apache.turbine.util.ServerData;
24
25 /**
26 * The UI service provides for shared access to User Interface (skin) files,
27 * as well as the ability for non-default skin files to inherit properties from
28 * a default skin. Use {@link TurbineUI} to access skin properties from your screen
29 * classes and action code. UITool is provided as a pull tool for accessing
30 * skin properties from your templates.
31 *
32 * <p>Skins are lazy loaded in that they are not loaded until first used.
33 *
34 * @author <a href="mailto:seade@backstagetech.com.au">Scott Eade</a>
35 * @version $Id$
36 */
37 public interface UIService extends Service
38 {
39 /**
40 * The service identifier.
41 */
42 public String SERVICE_NAME = "UIService";
43
44 /**
45 * Refresh all skins.
46 */
47 public void refresh();
48
49 /**
50 * Refresh a particular skin.
51 *
52 * @param skinName the name of the skin to clear.
53 */
54 public void refresh(String skinName);
55
56 /**
57 * Provide access to the list of available skin names.
58 *
59 * @return the available skin names.
60 */
61 public String[] getSkinNames();
62
63 /**
64 * Get the name of the default skin name for the web application from the
65 * TurbineResources.properties file. If the property is not present the
66 * name of the default skin will be returned. Note that the web application
67 * skin name may be something other than default, in which case its
68 * properties will default to the skin with the name "default".
69 *
70 * @return the name of the default skin for the web application.
71 */
72 public String getWebappSkinName();
73
74 /**
75 * Retrieve a skin property from the named skin. If the property is not
76 * defined in the named skin the value for the default skin will be
77 * provided. If the named skin does not exist then the skin configured for
78 * the webapp will be used. If the webapp skin does not exist the default
79 * skin will be used. If the default skin does not exist then
80 * <code>null</code> will be returned.
81 *
82 * @param skinName the name of the skin to retrieve the property from.
83 * @param key the key to retrieve from the skin.
84 * @return the value of the property for the named skin (defaulting to the
85 * default skin), the webapp skin, the default skin or <code>null</code>,
86 * depending on whether or not the property or skins exist.
87 */
88 public String get(String skinName, String key);
89
90 /**
91 * Retrieve a skin property from the default skin for the webapp. If the
92 * property is not defined in the webapp skin the value for the default skin
93 * will be provided. If the webapp skin does not exist the default skin
94 * will be used. If the default skin does not exist then <code>null</code>
95 * will be returned.
96 *
97 * @param key the key to retrieve.
98 * @return the value of the property for the webapp skin (defaulting to the
99 * 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 }