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.data; 18 19 import com.google.clearsilver.jsilver.autoescape.EscapeMode; 20 21 /** 22 * Manages the global Data object and local variable mappings during rendering. 23 */ 24 public interface DataContext { 25 26 /** 27 * Returns the main Data object this RenderingContext was defined with. 28 */ getRootData()29 Data getRootData(); 30 31 /** 32 * Creates a new Data object to hold local references, pushes it onto the variable map stack. This 33 * is used to hold macro parameters after a call command, and local variables defined for 'each' 34 * and 'with'. 35 */ pushVariableScope()36 void pushVariableScope(); 37 38 /** 39 * Removes the most recent Data object added to the local variable map stack. 40 */ popVariableScope()41 void popVariableScope(); 42 43 /** 44 * Creates and sets a local variable in the current scope equal to the given value. 45 * 46 * @param name the name of the local variable to fetch or create. 47 * @param value The String value to store at the local variable. 48 */ createLocalVariableByValue(String name, String value)49 void createLocalVariableByValue(String name, String value); 50 51 /** 52 * Creates and sets a local variable in the current scope equal to the given value. Also set the 53 * EscapeMode that was applied to its value. This may be used by the template renderer to decide 54 * whether to autoescape the variable. 55 * 56 * @param name the name of the local variable to fetch or create. 57 * @param value The String value to store at the local variable. 58 * @param mode EscapeMode that describes the escaping this variable has. {@code 59 * EscapeMode.ESCAPE_NONE} if the variable was not escaped. {@code 60 * EscapeMode.ESCAPE_IS_CONSTANT} if the variable was populated with a string or numeric 61 * literal. 62 */ createLocalVariableByValue(String name, String value, EscapeMode mode)63 void createLocalVariableByValue(String name, String value, EscapeMode mode); 64 65 /** 66 * Creates and sets a local variable in the current scope equal to the given value. 67 * <p> 68 * This method is a helper method for supporting the first() and last() functions on loops without 69 * requiring loops create a full Data tree. 70 * 71 * @param name the name of the local variable to fetch or create. 72 * @param value The String value to store at the local variable. 73 * @param isFirst What the local variable should return for 74 * {@link com.google.clearsilver.jsilver.data.Data#isFirstSibling} 75 * @param isLast What the local variable should return for 76 * {@link com.google.clearsilver.jsilver.data.Data#isLastSibling} 77 */ createLocalVariableByValue(String name, String value, boolean isFirst, boolean isLast)78 void createLocalVariableByValue(String name, String value, boolean isFirst, boolean isLast); 79 80 /** 81 * Creates a local variable that references a (possibly non-existent) Data node. When the Data 82 * object for this variable is requested, it will return the Data object at the path location or 83 * {@code null}, if it does not exist. If {@link #findVariable} is called with {@code create == 84 * true}, then if no Data object exists at the path location, it will be created. 85 * 86 * @param name the name of the local variable to fetch or create. 87 * @param path The path to the Data object 88 */ createLocalVariableByPath(String name, String path)89 void createLocalVariableByPath(String name, String path); 90 91 /** 92 * Searches the variable map stack for the specified variable name. If not found, it then searches 93 * the root Data object. If not found then and create is {@code true}, then a new node is created 94 * with the given name in the root Data object and that node is returned. 95 * <p> 96 * Note: This only creates nodes in the root Data object, not in any local variable map. To do 97 * that, use the Data node returned by {@link #pushVariableScope()}. 98 * 99 * @param name the name of the variable to find and/or create. 100 * @param create if {@link true} then a new node will be created if an existing Data node with the 101 * given name does not exist. 102 * @return The first Data node in the variable map stack that matches the given name, or a Data 103 * node in the root Data object matching the given name, or {@code null} if no such node 104 * exists and {@code create} is {@code false}. 105 */ findVariable(String name, boolean create)106 Data findVariable(String name, boolean create); 107 108 /** 109 * Searches the variable map stack for the specified variable name, and returns its 110 * {@link EscapeMode}. 111 * 112 * @return If the variable is found, returns its {@link EscapeMode}, otherwise returns {@code 113 * EscapeMode.ESCAPE_NONE}. 114 */ findVariableEscapeMode(String name)115 EscapeMode findVariableEscapeMode(String name); 116 } 117