1 package org.apache.turbine.services.ui;
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
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 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 * @see UIService
37 * @see UITool
38 */
39 public interface UIService extends Service
40 {
41 /***
42 * The service identifier.
43 */
44 public String SERVICE_NAME = "UIService";
45
46 /***
47 * Refresh all skins.
48 */
49 public void refresh();
50
51 /***
52 * Refresh a particular skin.
53 *
54 * @param skinName the name of the skin to clear.
55 */
56 public void refresh(String skinName);
57
58 /***
59 * Provide access to the list of available skin names.
60 *
61 * @return the available skin names.
62 */
63 public String[] getSkinNames();
64
65 /***
66 * Get the name of the default skin name for the web application from the
67 * TurbineResources.properties file. If the property is not present the
68 * name of the default skin will be returned. Note that the web application
69 * skin name may be something other than default, in which case its
70 * properties will default to the skin with the name "default".
71 *
72 * @return the name of the default skin for the web application.
73 */
74 public String getWebappSkinName();
75
76 /***
77 * Retrieve a skin property from the named skin. If the property is not
78 * defined in the named skin the value for the default skin will be
79 * provided. If the named skin does not exist then the skin configured for
80 * the webapp will be used. If the webapp skin does not exist the default
81 * skin will be used. If the default skin does not exist then
82 * <code>null</code> will be returned.
83 *
84 * @param skinName the name of the skin to retrieve the property from.
85 * @param key the key to retrieve from the skin.
86 * @return the value of the property for the named skin (defaulting to the
87 * default skin), the webapp skin, the default skin or <code>null</code>,
88 * depending on whether or not the property or skins exist.
89 */
90 public String get(String skinName, String key);
91
92 /***
93 * Retrieve a skin property from the default skin for the webapp. If the
94 * property is not defined in the webapp skin the value for the default skin
95 * will be provided. If the webapp skin does not exist the default skin
96 * will be used. If the default skin does not exist then <code>null</code>
97 * will be returned.
98 *
99 * @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 }