001// Copyright 2012-2013 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.dom.Element; 018import org.apache.tapestry5.ioc.Resource; 019import org.apache.tapestry5.ioc.annotations.UsesMappedConfiguration; 020 021import java.util.List; 022 023/** 024 * Responsible for managing access to the JavaScript modules. 025 * <p/> 026 * The configuration of the service allows overrides of the default search path; the configuration keys 027 * are module names, and the configuration values are the {@link JavaScriptModuleConfiguration} definitions for those module names. 028 * This is primarily used to wrap non-AMD compliant libraries for use with RequireJS (via contributed {@link JavaScriptModuleConfiguration}s). 029 * 030 * @since 5.4 031 * @see ModuleConfigurationCallback 032 */ 033@UsesMappedConfiguration(JavaScriptModuleConfiguration.class) 034public interface ModuleManager 035{ 036 /** 037 * Invoked by the internal {@link org.apache.tapestry5.internal.services.DocumentLinker} service to write the configuration 038 * for the module system into the page. 039 * 040 * @param body 041 * {@code <body>} element of the page, to which new {@code <script>} element(s) will be added. 042 * @param moduleConfigurationCallbacks 043 * a list of {@link org.apache.tapestry5.services.javascript.ModuleConfigurationCallback}s, which 044 * is used to customize the configuration before it is written. 045 */ 046 void writeConfiguration(Element body, 047 List<ModuleConfigurationCallback> moduleConfigurationCallbacks); 048 049 /** 050 * Invoked by the internal {@link org.apache.tapestry5.internal.services.DocumentLinker} service to write the initializations 051 * (as per {@link JavaScriptSupport#require(String)} into the page; this occurs after the module infrastructure 052 * has been written into the page, along with the core libraries. 053 * 054 * @param body 055 * {@code <body>} element of the page, to which new {@code <script>} element(s) will be added. 056 * @param libraryURLs 057 * additional libraries that should be dynamically loaded before evaluating the inits 058 * @param inits 059 * specify initialization on the page, based on loading modules, extacting functions from modules, and invoking those functions 060 */ 061 void writeInitialization(Element body, List<String> libraryURLs, List<?> inits); 062 063 /** 064 * Given a module name (which may be a path of names separated by slashes), locates the corresponding {@link Resource}. 065 * First checks for {@linkplain JavaScriptModuleConfiguration contributed shim modules}, then searches for possible matches among the 066 * {@linkplain org.apache.tapestry5.services.ComponentClassResolver#getLibraryNames() defined library names}. As a special 067 * case, the folder name "app" is mapped to the application's package. 068 * 069 * @param moduleName 070 * name of module to locate 071 * @return corresponding resource, or null if not found 072 */ 073 Resource findResourceForModule(String moduleName); 074 075}