001: package org.apache.turbine.services.pull.tools;
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.commons.logging.Log;
023: import org.apache.commons.logging.LogFactory;
024:
025: import org.apache.turbine.om.security.User;
026: import org.apache.turbine.services.pull.ApplicationTool;
027: import org.apache.turbine.services.ui.TurbineUI;
028: import org.apache.turbine.util.RunData;
029: import org.apache.turbine.util.ServerData;
030:
031: /**
032: * Manages all UI elements for a Turbine Application. Any UI element can be
033: * accessed in any template using the $ui handle (assuming you use the default
034: * PullService configuration). So, for example, you could access the background
035: * color for your pages by using $ui.bgcolor
036: * <p>
037: * This implementation provides a single level of inheritance in that if a
038: * property does not exist in a non-default skin, the value from the default
039: * skin will be used. By only requiring values different to those stored in
040: * the default skin to appear in the non-default skins the amount of memory
041: * consumed in cases where the UserManager instance is used at a non-global
042: * scope will potentially be reduced due to the fact that a shared instance of
043: * the default skin properties can be used. Note that this inheritance only
044: * applies to property values - it does not apply to any images or stylesheets
045: * that may form part of your skins.
046: * <p>
047: * This is an application pull tool for the template system. You should not
048: * use it in a normal application! Within Java code you should use TurbineUI.
049: * <p>
050: *
051: * This is an application pull tool for the template system. You should
052: * <strong>only</strong> use it in a normal application to set the skin
053: * attribute for a user (setSkin(User user, String skin)) and to initialize it
054: * for the user, otherwise use TurbineUI is probably the way to go.
055: *
056: * @author <a href="mailto:jvanzyl@periapt.com">Jason van Zyl</a>
057: * @author <a href="mailto:james_coltman@majorband.co.uk">James Coltman</a>
058: * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
059: * @author <a href="mailto:seade@backstagetech.com.au">Scott Eade</a>
060: * @version $Id$
061: * @see UIService
062: */
063: public class UITool implements ApplicationTool {
064: /** Logging */
065: private static Log log = LogFactory.getLog(UITool.class);
066:
067: /**
068: * Attribute name of skinName value in User's temp hashmap.
069: */
070: public static final String SKIN_ATTRIBUTE = UITool.class.getName()
071: + ".skin";
072:
073: /**
074: * The actual skin being used for the webapp.
075: */
076: private String skinName;
077:
078: /**
079: * Refresh the tool.
080: */
081: public void refresh() {
082: TurbineUI.refresh(getSkin());
083: log.debug("UITool refreshed for skin: " + getSkin());
084: }
085:
086: /**
087: * Provide access to the list of available skin names.
088: *
089: * @return the available skin names.
090: */
091: public String[] getSkinNames() {
092: return TurbineUI.getSkinNames();
093: }
094:
095: /**
096: * Get the name of the default skin name for the web application from the
097: * TurbineResources.properties file. If the property is not present the
098: * name of the default skin will be returned. Note that the web application
099: * skin name may be something other than default, in which case its
100: * properties will default to the skin with the name "default".
101: *
102: * @return the name of the default skin for the web application.
103: */
104: public String getWebappSkinName() {
105: return TurbineUI.getWebappSkinName();
106: }
107:
108: /**
109: * Retrieve a skin property. If the property is not defined in the current
110: * skin the value for the default skin will be provided. If the current
111: * skin does not exist then the skin configured for the webapp will be used.
112: * If the webapp skin does not exist the default skin will be used. If the
113: * default skin does not exist then <code>null</code> will be returned.
114: *
115: * @param key the key to retrieve from the skin.
116: * @return the value of the property for the named skin (defaulting to the
117: * default skin), the webapp skin, the default skin or <code>null</code>,
118: * depending on whether or not the property or skins exist.
119: */
120: public String get(String key) {
121: return TurbineUI.get(getSkin(), key);
122: }
123:
124: /**
125: * Retrieve the skin name.
126: */
127: public String getSkin() {
128: return skinName;
129: }
130:
131: /**
132: * Set the skin name to the skin from the TurbineResources.properties file.
133: * If the property is not present use the "default" skin.
134: */
135: public void setSkin() {
136: skinName = TurbineUI.getWebappSkinName();
137: }
138:
139: /**
140: * Set the skin name to the specified skin.
141: *
142: * @param skinName the skin name to use.
143: */
144: public void setSkin(String skinName) {
145: this .skinName = skinName;
146: }
147:
148: /**
149: * Set the skin name when the tool is configured to be loaded on a
150: * per-request basis. By default it calls getSkin to return the skin
151: * specified in TurbineResources.properties. Developers can write a subclass
152: * of UITool that overrides this method to determine the skin to use based
153: * on information held in the request.
154: *
155: * @param data a RunData instance
156: */
157: protected void setSkin(RunData data) {
158: setSkin();
159: }
160:
161: /**
162: * Set the skin name when the tool is configured to be loaded on a
163: * per-session basis. If the user's temp hashmap contains a value in the
164: * attribute specified by the String constant SKIN_ATTRIBUTE then that is
165: * returned. Otherwise it calls getSkin to return the skin specified in
166: * TurbineResources.properties.
167: *
168: * @param user a User instance
169: */
170: protected void setSkin(User user) {
171: if (user.getTemp(SKIN_ATTRIBUTE) == null) {
172: setSkin();
173: } else {
174: setSkin((String) user.getTemp(SKIN_ATTRIBUTE));
175: }
176: }
177:
178: /**
179: * Set the skin name in the user's temp hashmap for the current session.
180: *
181: * @param user a User instance
182: * @param skin the skin name for the session
183: */
184: public static void setSkin(User user, String skin) {
185: user.setTemp(SKIN_ATTRIBUTE, skin);
186: }
187:
188: /**
189: * Retrieve the URL for an image that is part of the skin. The images are
190: * stored in the WEBAPP/resources/ui/skins/[SKIN]/images directory.
191: *
192: * <p>Use this if for some reason your server name, server scheme, or server
193: * port change on a per request basis. I'm not sure if this would happen in
194: * a load balanced situation. I think in most cases the image(String image)
195: * method would probably be enough, but I'm not absolutely positive.
196: *
197: * @param imageId the id of the image whose URL will be generated.
198: * @param data the RunDate to use as the source of the ServerData to use as
199: * the basis for the URL.
200: */
201: public String image(String imageId, RunData data) {
202: return image(imageId, data.getServerData());
203: }
204:
205: /**
206: * Retrieve the URL for an image that is part of the skin. The images are
207: * stored in the WEBAPP/resources/ui/skins/[SKIN]/images directory.
208: *
209: * <p>Use this if for some reason your server name, server scheme, or server
210: * port change on a per request basis. I'm not sure if this would happen in
211: * a load balanced situation. I think in most cases the image(String image)
212: * method would probably be enough, but I'm not absolutely positive.
213: *
214: * @param imageId the id of the image whose URL will be generated.
215: * @param serverData the serverData to use as the basis for the URL.
216: */
217: public String image(String imageId, ServerData serverData) {
218: return TurbineUI.image(getSkin(), imageId, serverData);
219: }
220:
221: /**
222: * Retrieve the URL for an image that is part of the skin. The images are
223: * stored in the WEBAPP/resources/ui/skins/[SKIN]/images directory.
224: *
225: * @param imageId the id of the image whose URL will be generated.
226: */
227: public String image(String imageId) {
228: return TurbineUI.image(getSkin(), imageId);
229: }
230:
231: /**
232: * Retrieve the URL for the style sheet that is part of the skin. The style
233: * is stored in the WEBAPP/resources/ui/skins/[SKIN] directory with the
234: * filename skin.css
235: *
236: * <p>Use this if for some reason your server name, server scheme, or server
237: * port change on a per request basis. I'm not sure if this would happen in
238: * a load balanced situation. I think in most cases the style() method would
239: * probably be enough, but I'm not absolutely positive.
240: *
241: * @param data the RunDate to use as the source of the ServerData to use as
242: * the basis for the URL.
243: */
244: public String getStylecss(RunData data) {
245: return getStylecss(data.getServerData());
246: }
247:
248: /**
249: * Retrieve the URL for the style sheet that is part of the skin. The style
250: * is stored in the WEBAPP/resources/ui/skins/[SKIN] directory with the
251: * filename skin.css
252: *
253: * <p>Use this if for some reason your server name, server scheme, or server
254: * port change on a per request basis. I'm not sure if this would happen in
255: * a load balanced situation. I think in most cases the style() method would
256: * probably be enough, but I'm not absolutely positive.
257: *
258: * @param serverData the serverData to use as the basis for the URL.
259: */
260: public String getStylecss(ServerData serverData) {
261: return TurbineUI.getStylecss(getSkin(), serverData);
262: }
263:
264: /**
265: * Retrieve the URL for the style sheet that is part of the skin. The style
266: * is stored in the WEBAPP/resources/ui/skins/[SKIN] directory with the
267: * filename skin.css
268: */
269: public String getStylecss() {
270: return TurbineUI.getStylecss(getSkin());
271: }
272:
273: /**
274: * Retrieve the URL for a given script that is part of the skin. The script
275: * is stored in the WEBAPP/resources/ui/skins/[SKIN] directory.
276: *
277: * <p>Use this if for some reason your server name, server scheme, or server
278: * port change on a per request basis. I'm not sure if this would happen in
279: * a load balanced situation. I think in most cases the image(String image)
280: * method would probably be enough, but I'm not absolutely positive.
281: *
282: * @param filename the name of the script file whose URL will be generated.
283: * @param data the RunDate to use as the source of the ServerData to use as
284: * the basis for the URL.
285: */
286: public String getScript(String filename, RunData data) {
287: return getScript(filename, data.getServerData());
288: }
289:
290: /**
291: * Retrieve the URL for a given script that is part of the skin. The script
292: * is stored in the WEBAPP/resources/ui/skins/[SKIN] directory.
293: *
294: * <p>Use this if for some reason your server name, server scheme, or server
295: * port change on a per request basis. I'm not sure if this would happen in
296: * a load balanced situation. I think in most cases the image(String image)
297: * method would probably be enough, but I'm not absolutely positive.
298: *
299: * @param filename the name of the script file whose URL will be generated.
300: * @param serverData the serverData to use as the basis for the URL.
301: */
302: public String getScript(String filename, ServerData serverData) {
303: return TurbineUI.getScript(getSkin(), filename, serverData);
304: }
305:
306: /**
307: * Retrieve the URL for a given script that is part of the skin. The script
308: * is stored in the WEBAPP/resources/ui/skins/[SKIN] directory.
309: *
310: * @param filename the name of the script file whose URL will be generated.
311: */
312: public String getScript(String filename) {
313: return TurbineUI.getScript(getSkin(), filename);
314: }
315:
316: /**
317: * Initialize the UITool object.
318: *
319: * @param data This is null, RunData or User depending upon specified tool
320: * scope.
321: */
322: public void init(Object data) {
323: if (data == null) {
324: log.debug("UITool scope is global");
325: setSkin();
326: } else if (data instanceof RunData) {
327: log.debug("UITool scope is request");
328: setSkin((RunData) data);
329: } else if (data instanceof User) {
330: log.debug("UITool scope is session");
331: setSkin((User) data);
332: }
333: }
334:
335: }
|