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. UITool is provided as a pull tool for accessing 029 * skin properties from your templates. 030 * 031 * <p>Skins are lazy loaded in that they are not loaded until first used. 032 * 033 * @author <a href="mailto:seade@backstagetech.com.au">Scott Eade</a> 034 * @version $Id$ 035 */ 036public interface UIService extends Service 037{ 038 /** 039 * The service identifier. 040 */ 041 String SERVICE_NAME = "UIService"; 042 043 /** 044 * Refresh all skins. 045 */ 046 void refresh(); 047 048 /** 049 * Refresh a particular skin. 050 * 051 * @param skinName the name of the skin to clear. 052 */ 053 void refresh(String skinName); 054 055 /** 056 * Provide access to the list of available skin names. 057 * 058 * @return the available skin names. 059 */ 060 String[] getSkinNames(); 061 062 /** 063 * Get the name of the default skin name for the web application from the 064 * TurbineResources.properties file. If the property is not present the 065 * name of the default skin will be returned. Note that the web application 066 * skin name may be something other than default, in which case its 067 * properties will default to the skin with the name "default". 068 * 069 * @return the name of the default skin for the web application. 070 */ 071 String getWebappSkinName(); 072 073 /** 074 * Retrieve a skin property from the named skin. If the property is not 075 * defined in the named skin the value for the default skin will be 076 * provided. If the named skin does not exist then the skin configured for 077 * the webapp will be used. If the webapp skin does not exist the default 078 * skin will be used. If the default skin does not exist then 079 * <code>null</code> will be returned. 080 * 081 * @param skinName the name of the skin to retrieve the property from. 082 * @param key the key to retrieve from the skin. 083 * @return the value of the property for the named skin (defaulting to the 084 * default skin), the webapp skin, the default skin or <code>null</code>, 085 * depending on whether or not the property or skins exist. 086 */ 087 String get(String skinName, String key); 088 089 /** 090 * Retrieve a skin property from the default skin for the webapp. If the 091 * property is not defined in the webapp skin the value for the default skin 092 * will be provided. If the webapp skin does not exist the default skin 093 * will be used. If the default skin does not exist then <code>null</code> 094 * will be returned. 095 * 096 * @param key the key to retrieve. 097 * @return the value of the property for the webapp skin (defaulting to the 098 * default skin), the default skin or <code>null</code>, depending on 099 * whether or not the property or skins exist. 100 */ 101 String get(String key); 102 103 /** 104 * Retrieve the URL for an image that is part of a skin. The images are 105 * stored in the WEBAPP/resources/ui/skins/[SKIN]/images directory. 106 * 107 * <p>Use this if for some reason your server name, server scheme, or server 108 * port change on a per request basis. I'm not sure if this would happen in 109 * a load balanced situation. I think in most cases the image(String image) 110 * method would probably be enough, but I'm not absolutely positive. 111 * 112 * @param skinName the name of the skin to retrieve the image from. 113 * @param imageId the id of the image whose URL will be generated. 114 * @param serverData the serverData to use as the basis for the URL. 115 * @return the image URL 116 */ 117 String image(String skinName, String imageId, ServerData serverData); 118 119 /** 120 * Retrieve the URL for an image that is part of a skin. The images are 121 * stored in the WEBAPP/resources/ui/skins/[SKIN]/images directory. 122 * 123 * @param skinName the name of the skin to retrieve the image from. 124 * @param imageId the id of the image whose URL will be generated. 125 * @return the image URL 126 */ 127 String image(String skinName, String imageId); 128 129 /** 130 * Retrieve the URL for the style sheet that is part of a skin. The style is 131 * stored in the WEBAPP/resources/ui/skins/[SKIN] directory with the 132 * filename skin.css 133 * 134 * <p>Use this if for some reason your server name, server scheme, or server 135 * port change on a per request basis. I'm not sure if this would happen in 136 * a load balanced situation. I think in most cases the style() method would 137 * probably be enough, but I'm not absolutely positive. 138 * 139 * @param skinName the name of the skin to retrieve the style sheet from. 140 * @param serverData the serverData to use as the basis for the URL. 141 * @return the CSS URL 142 */ 143 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 * @return the CSS URL 152 */ 153 String getStylecss(String skinName); 154 155 /** 156 * Retrieve the URL for a given script that is part of a skin. The script is 157 * stored in the WEBAPP/resources/ui/skins/[SKIN] directory. 158 * 159 * <p>Use this if for some reason your server name, server scheme, or server 160 * port change on a per request basis. I'm not sure if this would happen in 161 * a load balanced situation. I think in most cases the style() method would 162 * probably be enough, but I'm not absolutely positive. 163 * 164 * @param skinName the name of the skin to retrieve the image from. 165 * @param filename the name of the script file. 166 * @param serverData the serverData to use as the basis for the URL. 167 * @return the script URL 168 */ 169 String getScript(String skinName, String filename, 170 ServerData serverData); 171 172 /** 173 * Retrieve the URL for a given script that is part of a skin. The script is 174 * stored in the WEBAPP/resources/ui/skins/[SKIN] directory. 175 * 176 * @param skinName the name of the skin to retrieve the image from. 177 * @param filename the name of the script file. 178 * @return the script URL 179 */ 180 String getScript(String skinName, String filename); 181 182}