156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson/* 256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Copyright (C) 2010 Google Inc. 356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * 456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Licensed under the Apache License, Version 2.0 (the "License"); 556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * you may not use this file except in compliance with the License. 656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * You may obtain a copy of the License at 756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * 856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * http://www.apache.org/licenses/LICENSE-2.0 956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * 1056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Unless required by applicable law or agreed to in writing, software 1156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * distributed under the License is distributed on an "AS IS" BASIS, 1256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 1356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * See the License for the specific language governing permissions and 1456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * limitations under the License. 1556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 1656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 1756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodsonpackage com.google.clearsilver.jsilver.template; 1856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 1956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodsonimport com.google.clearsilver.jsilver.autoescape.AutoEscapeOptions; 2056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodsonimport com.google.clearsilver.jsilver.autoescape.EscapeMode; 2156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodsonimport com.google.clearsilver.jsilver.data.DataContext; 2256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodsonimport com.google.clearsilver.jsilver.exceptions.JSilverInterpreterException; 2356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodsonimport com.google.clearsilver.jsilver.resourceloader.ResourceLoader; 2456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodsonimport com.google.clearsilver.jsilver.values.Value; 2556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 2656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson/** 2756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * State that is shared across a template rendering. 2856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 2956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodsonpublic interface RenderingContext { 3056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 3156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 3256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Execute a named function. Will throw an exception if the function is not found, or the function 3356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * does not return a value. 3456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 3556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson Value executeFunction(String name, Value... args) throws JSilverInterpreterException; 3656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 3756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 3856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Look up a function by name, and report whether it is an escaping function. Usually, the output 3956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * of escaping functions will be written using writeUnescaped() instead of writeEscaped(). 4056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * 4156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * @see com.google.clearsilver.jsilver.compiler.EscapingEvaluator 4256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 4356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson public boolean isEscapingFunction(String name); 4456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 4556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 4656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Write some text out, using the current escaping function. 4756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * 4856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * @see #pushEscapingFunction(String) 4956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * @see #popEscapingFunction() 5056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 5156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson void writeEscaped(String text); 5256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 5356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 5456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Write some text out, without doing any escaping. Use this only for trusted content. 5556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 5656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson void writeUnescaped(CharSequence text); 5756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 5856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 5956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Push a new escaping function onto the context. All calls to writeEscape() will use this new 6056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * function. When done with this function, call popEscapingFunction() to return to the previous 6156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * escaping function. 6256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * 6356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * If the escaping function is not found, an exception will be thrown. To use no escaping function 6456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * pass null as the escaperName. 6556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * 6656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * @see #popEscapingFunction() 6756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 6856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson void pushEscapingFunction(String escaperName); 6956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 7056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 7156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * @see #pushEscapingFunction(String) 7256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 7356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson void popEscapingFunction(); 7456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 7556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 7656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Push a new template onto the current execution context. This is to generate stack traces when 7756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * things go wrong deep in templates, to allow users to figure out how they got there. 7856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * 7956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * @see #popExecutionContext() 8056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 8156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson void pushExecutionContext(Template template); 8256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 8356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 8456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * @see #pushExecutionContext(Template) 8556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 8656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson void popExecutionContext(); 8756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 8856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 8956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Sets the current position in the template. Used to help generate error messages. 9056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 9156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson void setCurrentPosition(int line, int column); 9256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 9356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 9456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Register a macro in the current rendering context. This macro will be available to all other 9556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * templates, regardless of implementation. 9656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 9756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson void registerMacro(String name, Macro macro); 9856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 9956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 10056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Lookup a macro that's already been registered. Throws JSilverInterpreterException if macro not 10156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * found. 10256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 10356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson Macro findMacro(String name) throws JSilverInterpreterException; 10456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 10556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 10656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Return the DataContext object associated with this RenderingContext. 10756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 10856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson DataContext getDataContext(); 10956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 11056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 11156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Returns the ResourceLoader object to use to fetch files needed to render the current template. 11256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 11356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson ResourceLoader getResourceLoader(); 11456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 11556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 11656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Returns the configured AutoEscapeOptions to be used while rendering the current template. 11756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 11856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson AutoEscapeOptions getAutoEscapeOptions(); 11956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 12056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 12156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Push a new auto escaping mode onto the context. Any template loads via include() or 12256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * evaluateVariable() will use this auto escaping mode when loading the template. 12356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * 12456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * @see #popAutoEscapeMode 12556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * 12656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 12756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson void pushAutoEscapeMode(EscapeMode mode); 12856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 12956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 13056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * @see #pushAutoEscapeMode 13156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 13256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson void popAutoEscapeMode(); 13356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 13456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 13556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Read the currently set auto escape mode. 13656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * 13756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * @return EscapeMode 13856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 13956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson EscapeMode getAutoEscapeMode(); 14056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 14156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 14256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Indicates whether runtime auto escaping is in progress. 14356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * 14456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * @return true if runtime auto escaping is enabled. 14556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * 14656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * @see #isRuntimeAutoEscaping 14756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 14856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson boolean isRuntimeAutoEscaping(); 14956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 15056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 15156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Start an auto escaping context to parse and auto escape template contents as they are being 15256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * rendered. 15356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * 15456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * @see #stopRuntimeAutoEscaping 15556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 15656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson void startRuntimeAutoEscaping(); 15756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 15856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 15956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Stop runtime auto escaping. 16056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * 16156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * @see #startRuntimeAutoEscaping 16256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 16356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson void stopRuntimeAutoEscaping(); 16456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 16556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 16656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Adds an entry with a name of the template to the stack keeping all names of already included 16756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * templates. The name is added only if it is not already on the stack. 16856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * 16956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * @param templateName name of the template to be added to the stack. If {@code null} a {@code 17056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * NullPointerException} will be thrown. 17156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * @return true if the {@code templateName} was added. 17256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 17356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson boolean pushIncludeStackEntry(String templateName); 17456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 17556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 17656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Removes an entry with a name of the template from the stack. 17756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * 17856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * @param templateName 17956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * @return true if the {@code templateName} was on the stack. 18056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 18156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson boolean popIncludeStackEntry(String templateName); 18256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 18356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 18456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Returns the ordered, mutable stack of names of included templates. 18556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 18656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson Iterable<String> getIncludedTemplateNames(); 18756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson} 188