1 /*
2  * Copyright (C) 2010 Google Inc.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package com.google.clearsilver.jsilver.template;
18 
19 import com.google.clearsilver.jsilver.autoescape.AutoEscapeOptions;
20 import com.google.clearsilver.jsilver.autoescape.EscapeMode;
21 import com.google.clearsilver.jsilver.data.DataContext;
22 import com.google.clearsilver.jsilver.exceptions.JSilverInterpreterException;
23 import com.google.clearsilver.jsilver.resourceloader.ResourceLoader;
24 import com.google.clearsilver.jsilver.values.Value;
25 
26 /**
27  * State that is shared across a template rendering.
28  */
29 public interface RenderingContext {
30 
31   /**
32    * Execute a named function. Will throw an exception if the function is not found, or the function
33    * does not return a value.
34    */
executeFunction(String name, Value... args)35   Value executeFunction(String name, Value... args) throws JSilverInterpreterException;
36 
37   /**
38    * Look up a function by name, and report whether it is an escaping function. Usually, the output
39    * of escaping functions will be written using writeUnescaped() instead of writeEscaped().
40    *
41    * @see com.google.clearsilver.jsilver.compiler.EscapingEvaluator
42    */
isEscapingFunction(String name)43   public boolean isEscapingFunction(String name);
44 
45   /**
46    * Write some text out, using the current escaping function.
47    *
48    * @see #pushEscapingFunction(String)
49    * @see #popEscapingFunction()
50    */
writeEscaped(String text)51   void writeEscaped(String text);
52 
53   /**
54    * Write some text out, without doing any escaping. Use this only for trusted content.
55    */
writeUnescaped(CharSequence text)56   void writeUnescaped(CharSequence text);
57 
58   /**
59    * Push a new escaping function onto the context. All calls to writeEscape() will use this new
60    * function. When done with this function, call popEscapingFunction() to return to the previous
61    * escaping function.
62    *
63    * If the escaping function is not found, an exception will be thrown. To use no escaping function
64    * pass null as the escaperName.
65    *
66    * @see #popEscapingFunction()
67    */
pushEscapingFunction(String escaperName)68   void pushEscapingFunction(String escaperName);
69 
70   /**
71    * @see #pushEscapingFunction(String)
72    */
popEscapingFunction()73   void popEscapingFunction();
74 
75   /**
76    * Push a new template onto the current execution context. This is to generate stack traces when
77    * things go wrong deep in templates, to allow users to figure out how they got there.
78    *
79    * @see #popExecutionContext()
80    */
pushExecutionContext(Template template)81   void pushExecutionContext(Template template);
82 
83   /**
84    * @see #pushExecutionContext(Template)
85    */
popExecutionContext()86   void popExecutionContext();
87 
88   /**
89    * Sets the current position in the template. Used to help generate error messages.
90    */
setCurrentPosition(int line, int column)91   void setCurrentPosition(int line, int column);
92 
93   /**
94    * Register a macro in the current rendering context. This macro will be available to all other
95    * templates, regardless of implementation.
96    */
registerMacro(String name, Macro macro)97   void registerMacro(String name, Macro macro);
98 
99   /**
100    * Lookup a macro that's already been registered. Throws JSilverInterpreterException if macro not
101    * found.
102    */
findMacro(String name)103   Macro findMacro(String name) throws JSilverInterpreterException;
104 
105   /**
106    * Return the DataContext object associated with this RenderingContext.
107    */
getDataContext()108   DataContext getDataContext();
109 
110   /**
111    * Returns the ResourceLoader object to use to fetch files needed to render the current template.
112    */
getResourceLoader()113   ResourceLoader getResourceLoader();
114 
115   /**
116    * Returns the configured AutoEscapeOptions to be used while rendering the current template.
117    */
getAutoEscapeOptions()118   AutoEscapeOptions getAutoEscapeOptions();
119 
120   /**
121    * Push a new auto escaping mode onto the context. Any template loads via include() or
122    * evaluateVariable() will use this auto escaping mode when loading the template.
123    *
124    * @see #popAutoEscapeMode
125    *
126    */
pushAutoEscapeMode(EscapeMode mode)127   void pushAutoEscapeMode(EscapeMode mode);
128 
129   /**
130    * @see #pushAutoEscapeMode
131    */
popAutoEscapeMode()132   void popAutoEscapeMode();
133 
134   /**
135    * Read the currently set auto escape mode.
136    *
137    * @return EscapeMode
138    */
getAutoEscapeMode()139   EscapeMode getAutoEscapeMode();
140 
141   /**
142    * Indicates whether runtime auto escaping is in progress.
143    *
144    * @return true if runtime auto escaping is enabled.
145    *
146    * @see #isRuntimeAutoEscaping
147    */
isRuntimeAutoEscaping()148   boolean isRuntimeAutoEscaping();
149 
150   /**
151    * Start an auto escaping context to parse and auto escape template contents as they are being
152    * rendered.
153    *
154    * @see #stopRuntimeAutoEscaping
155    */
startRuntimeAutoEscaping()156   void startRuntimeAutoEscaping();
157 
158   /**
159    * Stop runtime auto escaping.
160    *
161    * @see #startRuntimeAutoEscaping
162    */
stopRuntimeAutoEscaping()163   void stopRuntimeAutoEscaping();
164 
165   /**
166    * Adds an entry with a name of the template to the stack keeping all names of already included
167    * templates. The name is added only if it is not already on the stack.
168    *
169    * @param templateName name of the template to be added to the stack. If {@code null} a {@code
170    *        NullPointerException} will be thrown.
171    * @return true if the {@code templateName} was added.
172    */
pushIncludeStackEntry(String templateName)173   boolean pushIncludeStackEntry(String templateName);
174 
175   /**
176    * Removes an entry with a name of the template from the stack.
177    *
178    * @param templateName
179    * @return true if the {@code templateName} was on the stack.
180    */
popIncludeStackEntry(String templateName)181   boolean popIncludeStackEntry(String templateName);
182 
183   /**
184    * Returns the ordered, mutable stack of names of included templates.
185    */
getIncludedTemplateNames()186   Iterable<String> getIncludedTemplateNames();
187 }
188