001// Copyright 2007, 2008, 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.internal.services;
016
017import org.apache.tapestry5.json.JSONObject;
018import org.apache.tapestry5.services.javascript.InitializationPriority;
019import org.apache.tapestry5.services.javascript.StylesheetLink;
020
021/**
022 * Responsible for injecting script and style links into the <head> and <body> element of the rendered HTML
023 * document.
024 */
025public interface DocumentLinker
026{
027    /**
028     * Adds a link to load a JavaScript library. . The <script> elements will be added inside
029     * the document's <head>.
030     */
031    void addScriptLink(String scriptURL);
032
033    /**
034     * Adds a link to load a CSS stylesheet.
035     */
036    void addStylesheetLink(StylesheetLink stylesheet);
037
038    /**
039     * Adds JavaScript code. The code is collected into a single block that is injected just before the close body tag
040     * of the page (in a full page render) and collected as the "script" property of the partial page render response.
041     * The JavaScript is executed after the page loads (or in an Ajax update, after external JavaScript libraries are
042     * loaded and the DOM is updated).
043     * <p>
044     * This method may be called multiple times for the same priority and the script will be accumulated.
045     * 
046     * @param priority
047     *            when to execute the provided script
048     * @param script
049     *            statement to add to the block (a newline will be appended as well)
050     */
051    void addScript(InitializationPriority priority, String script);
052
053    /**
054     * Adds a call to the Tapestry.init() function. This may be called multiple times and the init() calls will occur
055     * in order. In a normal page render, the init() calls will be added to the main JavaScript block, but in a partial
056     * page render Ajax response, the initialization will be property "init" of the partial page render response.
057     * <p>
058     * This method should only be invoked at most once per priority.
059     * 
060     * @since 5.2.0
061     */
062    void setInitialization(InitializationPriority priority, JSONObject initialization);
063}