001 // Copyright 2006, 2007, 2008 The Apache Software Foundation
002 //
003 // Licensed under the Apache License, Version 2.0 (the "License");
004 // you may not use this file except in compliance with the License.
005 // You may obtain a copy of the License at
006 //
007 // http://www.apache.org/licenses/LICENSE-2.0
008 //
009 // Unless required by applicable law or agreed to in writing, software
010 // distributed under the License is distributed on an "AS IS" BASIS,
011 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012 // See the License for the specific language governing permissions and
013 // limitations under the License.
014
015 package org.apache.tapestry;
016
017 import org.apache.tapestry.ioc.services.SymbolSource;
018 import org.apache.tapestry.services.AssetSource;
019
020 /**
021 * Provides support to all components that render. This is primarily about generating unique client-side ids (very
022 * important for JavaScript generation) as well as accumulating JavaScript to be sent to the client. PageRenderSupport
023 * also allows for the incremental addition of stylesheets.
024 */
025 public interface PageRenderSupport
026 {
027 /**
028 * Allocates a unique id based on the component's id. In some cases, the return value will not precisely match the
029 * input value (an underscore and a unique index value may be appended).
030 *
031 * @param id the component id from which a unique id will be generated
032 * @return a unique id for this rendering of the page
033 * @see org.apache.tapestry.ioc.internal.util.IdAllocator
034 */
035 String allocateClientId(String id);
036
037 /**
038 * As with {@link #allocateClientId(String)} but uses the id of the component extracted from the resources.
039 *
040 * @param resources of the component which requires an id
041 * @return a unique id for this rendering of the page
042 */
043 String allocateClientId(ComponentResources resources);
044
045 /**
046 * Adds one or more new script assets to the page. Assets are added uniquely, and appear as <script> elements
047 * just inside the <body> element of the rendered page. Duplicate requests to add the same script are quietly
048 * ignored.
049 *
050 * @param scriptAssets asset to the script to add
051 */
052 void addScriptLink(Asset... scriptAssets);
053
054 /**
055 * Used to add scripts that are stored on the classpath. Each element has {@linkplain SymbolSource symbols
056 * expanded}, then is {@linkplain AssetSource converted to an asset} and added as a script link.
057 *
058 * @param classpaths array of paths. Symbols in the paths are expanded, then the paths are each converted into an
059 * asset.
060 */
061 void addClasspathScriptLink(String... classpaths);
062
063 /**
064 * Adds a link to a CSS stylesheet. As with JavaScript libraries, each stylesheet is added at most once. Stylesheets
065 * added this way will be ordered before any other content in the <head> element of the document. The
066 * <head> element will be created, if necessary.
067 *
068 * @param stylesheet the asset referencing the stylesheet
069 * @param media the media value for the stylesheet, or null to not specify a specific media type
070 */
071
072 void addStylesheetLink(Asset stylesheet, String media);
073
074 /**
075 * Adds a script statement to the page's script block (which appears at the end of the page, just before the
076 * </body> tag).
077 *
078 * @param format base string format, to be passed through String.format
079 * @param arguments additional arguments formatted to form the final script
080 */
081 void addScript(String format, Object... arguments);
082 }