View Javadoc

1   package org.apache.turbine.services.ui;
2   
3   /*
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *   http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
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 }