001// Copyright 2010 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
015package org.apache.tapestry5.services.javascript;
016
017import java.util.List;
018
019import org.apache.tapestry5.Asset;
020import org.apache.tapestry5.SymbolConstants;
021import org.apache.tapestry5.ioc.services.ThreadLocale;
022import org.apache.tapestry5.services.AssetSource;
023
024/**
025 * A high level description of a group of related JavaScript libraries and stylesheets. The built-in "core"
026 * stack is used to define the core JavaScript libraries needed by Tapestry (currently, this includes
027 * Prototype and Scriptaculous, as well as Tapestry-specific libraries). Other component libraries may
028 * define additional stacks for related sets of resources, for example, to bundle together some portion
029 * of the ExtJS or YUI libraries.
030 * <p>
031 * A JavaScript assets of a stack may (when {@linkplain SymbolConstants#COMBINE_SCRIPTS enabled}) be exposed to the
032 * client as a single URL (identifying the stack by name). The individual assets are combined into a single virtual
033 * asset, which is then streamed to the client.
034 * <p>
035 * Implementations may need to inject the {@link ThreadLocale} service in order to determine the current locale (if any
036 * of the JavaScript library or stylesheet assets are localized). They will generally need to inject the
037 * {@link AssetSource} service as well.
038 * 
039 * @since 5.2.0
040 * @see ThreadLocale
041 */
042public interface JavaScriptStack
043{
044    /**
045     * Returns a list of JavaScriptStack names that this stack depends on. Each stack will be processed before
046     * the current stack (thus a dependency stack's libraries, stylesheets and initialization is emitted before
047     * the dependent stack).
048     */
049    List<String> getStacks();
050
051    /**
052     * Returns a list of <em>localized</em> assets for JavaScript libraries that form the stack.
053     */
054    List<Asset> getJavaScriptLibraries();
055
056    /**
057     * Returns a list of <em>localized</em> links for stylesheets that form the stack.
058     */
059    List<StylesheetLink> getStylesheets();
060
061    /**
062     * Returns static JavaScript initialization for the stack. This block of JavaScript code will be added to the
063     * page that imports the stack. The code executes outside of any other function (i.e., the code is not deferred
064     * until the DOM is loaded). As with the other methods, if localization is a factor, the result of this method
065     * should be localized.
066     */
067    String getInitialization();
068}