001// Copyright 2010-2014 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 org.apache.tapestry5.Asset; 018import org.apache.tapestry5.SymbolConstants; 019import org.apache.tapestry5.ioc.services.ThreadLocale; 020import org.apache.tapestry5.services.AssetSource; 021 022import java.util.List; 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 (though this has been largely replaced by 027 * JavaScript modules in Tapestry 5.4, 028 * and the may be no libraries in the core stack by Tapestry 5.5). Other component libraries may 029 * define additional stacks for related sets of resources, for example, to bundle together some portion 030 * of the ExtJS or YUI libraries. 031 * <p/> 032 * The JavaScript assets of a stack may (when {@linkplain SymbolConstants#COMBINE_SCRIPTS enabled}) be exposed to the 033 * client as a single URL (identifying the stack by name). The individual JavaScript assets are combined into a single virtual 034 * asset, which is then streamed to the client. The individual JavaScript libraries, or the combined virtual library, 035 * may be {@linkplain SymbolConstants#MINIFICATION_ENABLED minimized} and the content (both compressed and 036 * uncompressed) cached. 037 * <p/> 038 * Implementations may need to inject the {@link ThreadLocale} service in order to determine the current locale (if any 039 * of the JavaScript library or stylesheet assets are localized). They will generally need to inject the 040 * {@link AssetSource} service as well. 041 * <p/> 042 * The {@link ExtensibleJavaScriptStack} is the best way to create new stacks. 043 * 044 * @see ThreadLocale 045 * @see org.apache.tapestry5.services.javascript.ExtensibleJavaScriptStack 046 * @since 5.2.0 047 */ 048public interface JavaScriptStack 049{ 050 /** 051 * Returns a list of JavaScriptStack names that this stack depends on. Each stack will be processed before 052 * the current stack (thus a dependency stack's libraries, stylesheets and initialization is emitted before 053 * the dependent stack). 054 */ 055 List<String> getStacks(); 056 057 /** 058 * Returns a list of <em>localized</em> assets for JavaScript libraries that form the stack. 059 */ 060 List<Asset> getJavaScriptLibraries(); 061 062 /** 063 * Returns a list of <em>localized</em> links for stylesheets that form the stack. 064 */ 065 List<StylesheetLink> getStylesheets(); 066 067 /** 068 * Returns a list of modules to include with the stack, when aggregating the stack's JavaScript. 069 * It is still necessary to explicitly {@linkplain org.apache.tapestry5.services.javascript.JavaScriptSupport#require(String) require} 070 * such modules. 071 * 072 * @see ModuleManager 073 * @see org.apache.tapestry5.SymbolConstants#COMBINE_SCRIPTS 074 * @since 5.4 075 */ 076 List<String> getModules(); 077 078 /** 079 * Returns static JavaScript initialization for the stack. This block of JavaScript code will be added to the 080 * page that imports the stack. The code executes outside of any other function (i.e., the code is not deferred 081 * until the DOM is loaded). As with the other methods, if localization is a factor, the result of this method 082 * should be localized. 083 * 084 * @deprecated Deprecated in Tapestry 5.4; may be removed in a future release. Implementations 085 * may return null. 086 */ 087 String getInitialization(); 088}