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