001 // Copyright 2004, 2005 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.hivemind.Resource;
018
019 /**
020 * Defines methods needed by a {@link org.apache.tapestry.IScript}to execute.
021 *
022 * @author Howard Lewis Ship
023 * @since 3.0
024 * @see org.apache.tapestry.html.Body
025 */
026
027 public interface IScriptProcessor
028 {
029 /**
030 * Adds scripting code to the main body. During the render, multiple scripts may render multiple
031 * bodies; all are concatinated together to form a single block. The
032 * {@link org.apache.tapestry.html.Body} component will write the body script contents
033 * just inside the <code><body></code> tag.
034 *
035 * @deprecated To be removed sometime after 4.1.
036 * @see {@link #addBodyScript(IComponent, String)}
037 */
038
039 void addBodyScript(String script);
040
041 /**
042 * Adds scripting code to the main body. During the render, multiple scripts may render multiple
043 * bodies; all are concatinated together to form a single block. The
044 * {@link org.apache.tapestry.html.Body} component will write the body script contents
045 * just inside the <code><body></code> tag.
046 *
047 * @param target
048 * The component this script is being added for.
049 * @param script
050 * The script to add to the body response.
051 */
052 void addBodyScript(IComponent target, String script);
053
054 /**
055 * Adds initialization script. Initialization script is executed once, when the containing page
056 * loads. Initialization script content is written only after all HTML content that could be
057 * referenced from the script (in effect, just before the <code></body></code> tag).
058 *
059 * @deprecated To be removed sometime after 4.1.
060 * @see {@link #addInitializationScript(IComponent, String)}
061 */
062 void addInitializationScript(String script);
063
064 /**
065 * Adds initialization script. Initialization script is executed once, when the containing page
066 * loads. Initialization script content is written only after all HTML content that could be
067 * referenced from the script (in effect, just before the <code></body></code> tag).
068 *
069 * @param target
070 * The component the script is being added for.
071 * @param script
072 * The script to add.
073 */
074 void addInitializationScript(IComponent target, String script);
075
076 /**
077 * Works in the same way as {@link #addInitializationScript(IComponent, String)} - except this
078 * method causes the script being added to appear <em>after</em> all of the script content written out
079 * from the normal initialization script processing happens. This is useful if you have some initialization
080 * script logic that absolutely must happen at the very end of the rest of things.
081 *
082 * @see {@link #addInitializationScript(IComponent, String)}.
083 *
084 * @param target
085 * The component the script is being added for.
086 * @param script
087 * The script to add.
088 */
089 void addScriptAfterInitialization(IComponent target, String script);
090
091 /**
092 * Adds an external script. The processor is expected to ensure that external scripts are only
093 * loaded a single time per page.
094 *
095 * @deprecated To be removed sometime after 4.1
096 * @see {@link #addExternalScript(IComponent, Resource)}
097 */
098
099 void addExternalScript(Resource resource);
100
101 /**
102 * Adds an external script. The processor is expected to ensure that external scripts are only
103 * loaded a single time per page. The target will be checked to filter the scripts
104 * added for those types of responses that require them.
105 *
106 * @param target
107 * The component the script is being added for.
108 * @param resource
109 * The external script to add.
110 */
111 void addExternalScript(IComponent target, Resource resource);
112
113 /**
114 * Determines if the specified component should have its javascript
115 * body added to the response.
116 *
117 * @param target
118 * The component to allow/disallow body script content from.
119 * @return True if the component script should be allowed.
120 */
121 boolean isBodyScriptAllowed(IComponent target);
122
123 /**
124 * Determines if the specified component should have its javascript
125 * initialization added to the response.
126 *
127 * @param target
128 * The component to allow/disallow initialization script content from.
129 * @return True if the component script should be allowed.
130 */
131 boolean isInitializationScriptAllowed(IComponent target);
132
133 /**
134 * Determines if the specified component should have its javascript
135 * external resource scripts added to the response.
136 *
137 * @param target
138 * The component to check for inclusion/exclusion.
139 * @return True if external scripts from this component should be added to
140 * the response.
141 */
142 boolean isExternalScriptAllowed(IComponent target);
143
144 /**
145 * Ensures that the given string is unique. The string is either returned unchanged, or a suffix
146 * is appended to ensure uniqueness.
147 */
148
149 String getUniqueString(String baseValue);
150 }