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. Use {@link 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 */ 037public interface UIService extends Service 038{ 039 /** 040 * The service identifier. 041 */ 042 public String SERVICE_NAME = "UIService"; 043 044 /** 045 * Refresh all skins. 046 */ 047 public void refresh(); 048 049 /** 050 * Refresh a particular skin. 051 * 052 * @param skinName the name of the skin to clear. 053 */ 054 public void refresh(String skinName); 055 056 /** 057 * Provide access to the list of available skin names. 058 * 059 * @return the available skin names. 060 */ 061 public String[] getSkinNames(); 062 063 /** 064 * Get the name of the default skin name for the web application from the 065 * TurbineResources.properties file. If the property is not present the 066 * name of the default skin will be returned. Note that the web application 067 * skin name may be something other than default, in which case its 068 * properties will default to the skin with the name "default". 069 * 070 * @return the name of the default skin for the web application. 071 */ 072 public String getWebappSkinName(); 073 074 /** 075 * Retrieve a skin property from the named skin. If the property is not 076 * defined in the named skin the value for the default skin will be 077 * provided. If the named skin does not exist then the skin configured for 078 * the webapp will be used. If the webapp skin does not exist the default 079 * skin will be used. If the default skin does not exist then 080 * <code>null</code> will be returned. 081 * 082 * @param skinName the name of the skin to retrieve the property from. 083 * @param key the key to retrieve from the skin. 084 * @return the value of the property for the named skin (defaulting to the 085 * default skin), the webapp skin, the default skin or <code>null</code>, 086 * depending on whether or not the property or skins exist. 087 */ 088 public String get(String skinName, String key); 089 090 /** 091 * Retrieve a skin property from the default skin for the webapp. If the 092 * property is not defined in the webapp skin the value for the default skin 093 * will be provided. If the webapp skin does not exist the default skin 094 * will be used. If the default skin does not exist then <code>null</code> 095 * will be returned. 096 * 097 * @param key the key to retrieve. 098 * @return the value of the property for the webapp skin (defaulting to the 099 * 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}