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