001 /** 002 * Copyright (c) 2000-present Liferay, Inc. All rights reserved. 003 * 004 * This library is free software; you can redistribute it and/or modify it under 005 * the terms of the GNU Lesser General Public License as published by the Free 006 * Software Foundation; either version 2.1 of the License, or (at your option) 007 * any later version. 008 * 009 * This library is distributed in the hope that it will be useful, but WITHOUT 010 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 011 * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more 012 * details. 013 */ 014 015 package com.liferay.portal.kernel.util; 016 017 import com.liferay.portal.kernel.security.pacl.permission.PortalRuntimePermission; 018 019 /** 020 * Provides utility methods for escaping, rendering, replacing, and stripping 021 * HTML text. This class uses XSS recommendations from <a 022 * href="http://www.owasp.org/index.php/Cross_Site_Scripting#How_to_Protect_Yourself">http://www.owasp.org/index.php/Cross_Site_Scripting#How_to_Protect_Yourself</a> 023 * when escaping HTML text. 024 * 025 * @author Brian Wing Shun Chan 026 * @author Clarence Shen 027 * @author Harry Mark 028 * @author Samuel Kong 029 */ 030 public class HtmlUtil { 031 032 /** 033 * Escapes the text so that it is safe to use in an HTML context. 034 * 035 * @param text the text to escape 036 * @return the escaped HTML text, or <code>null</code> if the text is 037 * <code>null</code> 038 */ 039 public static String escape(String text) { 040 return getHtml().escape(text); 041 } 042 043 /** 044 * Escapes the input text as a hexadecimal value, based on the mode (type). 045 * 046 * @param text the text to escape 047 * @param mode the encoding type 048 * @return the escaped hexadecimal value of the input text, based on the 049 * mode, or <code>null</code> if the text is <code>null</code> 050 * @see com.liferay.portal.util.HtmlImpl#escape(String, int) 051 */ 052 public static String escape(String text, int mode) { 053 return getHtml().escape(text, mode); 054 } 055 056 /** 057 * Escapes the attribute value so that it is safe to use as an attribute 058 * value. 059 * 060 * @param attribute the attribute to escape 061 * @return the escaped attribute value, or <code>null</code> if the 062 * attribute value is <code>null</code> 063 */ 064 public static String escapeAttribute(String attribute) { 065 return getHtml().escapeAttribute(attribute); 066 } 067 068 /** 069 * Escapes the CSS value so that it is safe to use in a CSS context. 070 * 071 * @param css the CSS value to escape 072 * @return the escaped CSS value, or <code>null</code> if the CSS value is 073 * <code>null</code> 074 */ 075 public static String escapeCSS(String css) { 076 return getHtml().escapeCSS(css); 077 } 078 079 /** 080 * Escapes the HREF attribute so that it is safe to use as an HREF 081 * attribute. 082 * 083 * @param href the HREF attribute to escape 084 * @return the escaped HREF attribute, or <code>null</code> if the HREF 085 * attribute is <code>null</code> 086 */ 087 public static String escapeHREF(String href) { 088 return getHtml().escapeHREF(href); 089 } 090 091 /** 092 * Escapes the JavaScript value so that it is safe to use in a JavaScript 093 * context. 094 * 095 * @param js the JavaScript value to escape 096 * @return the escaped JavaScript value, or <code>null</code> if the 097 * JavaScript value is <code>null</code> 098 */ 099 public static String escapeJS(String js) { 100 return getHtml().escapeJS(js); 101 } 102 103 /** 104 * Escapes the URL value so that it is safe to use as a URL. 105 * 106 * @param url the URL value to escape 107 * @return the escaped URL value, or <code>null</code> if the URL value is 108 * <code>null</code> 109 */ 110 public static String escapeURL(String url) { 111 return getHtml().escapeURL(url); 112 } 113 114 public static String escapeXPath(String xPath) { 115 return getHtml().escapeXPath(xPath); 116 } 117 118 public static String escapeXPathAttribute(String xPathAttribute) { 119 return getHtml().escapeXPathAttribute(xPathAttribute); 120 } 121 122 /** 123 * Extracts the raw text from the HTML input, compressing its whitespace and 124 * removing all attributes, scripts, and styles. 125 * 126 * <p> 127 * For example, raw text returned by this method can be stored in a search 128 * index. 129 * </p> 130 * 131 * @param html the HTML text 132 * @return the raw text from the HTML input, or <code>null</code> if the 133 * HTML input is <code>null</code> 134 */ 135 public static String extractText(String html) { 136 return getHtml().extractText(html); 137 } 138 139 public static String fromInputSafe(String text) { 140 return getHtml().fromInputSafe(text); 141 } 142 143 public static String getAUICompatibleId(String html) { 144 return getHtml().getAUICompatibleId(html); 145 } 146 147 public static Html getHtml() { 148 PortalRuntimePermission.checkGetBeanProperty(HtmlUtil.class); 149 150 return _html; 151 } 152 153 /** 154 * Renders the HTML content into text. This provides a human readable 155 * version of the segment content that is modeled on the way Mozilla 156 * Thunderbird® and other email clients provide an automatic conversion 157 * of HTML content to text in their alternative MIME encoding of emails. 158 * 159 * <p> 160 * Using the default settings, the output complies with the 161 * <code>Text/Plain; Format=Flowed (DelSp=No)</code> protocol described in 162 * <a href="http://tools.ietf.org/html/rfc3676">RFC-3676</a>. 163 * </p> 164 * 165 * @param html the HTML text 166 * @return the rendered HTML text, or <code>null</code> if the HTML text is 167 * <code>null</code> 168 */ 169 public static String render(String html) { 170 return getHtml().render(html); 171 } 172 173 /** 174 * Replaces all Microsoft® Word Unicode characters with plain HTML 175 * entities or characters. 176 * 177 * @param text the text 178 * @return the converted text, or <code>null</code> if the text is 179 * <code>null</code> 180 * @deprecated As of 7.0.0, with no direct replacement 181 */ 182 @Deprecated 183 public static String replaceMsWordCharacters(String text) { 184 return getHtml().replaceMsWordCharacters(text); 185 } 186 187 /** 188 * Replaces all new lines or carriage returns with the <code><br /></code> 189 * HTML tag. 190 * 191 * @param html the text 192 * @return the converted text, or <code>null</code> if the HTML text is 193 * <code>null</code> 194 */ 195 public static String replaceNewLine(String html) { 196 return getHtml().replaceNewLine(html); 197 } 198 199 /** 200 * Strips all content delimited by the tag out of the text. 201 * 202 * <p> 203 * If the tag appears multiple times, all occurrences (including the tag) 204 * are stripped. The tag may have attributes. In order for this method to 205 * recognize the tag, it must consist of a separate opening and closing tag. 206 * Self-closing tags remain in the result. 207 * </p> 208 * 209 * @param text the text 210 * @param tag the tag used for delimiting, which should only be the tag's 211 * name (e.g. no <) 212 * @return the text, without the stripped tag and its contents, or 213 * <code>null</code> if the text is <code>null</code> 214 */ 215 public static String stripBetween(String text, String tag) { 216 return getHtml().stripBetween(text, tag); 217 } 218 219 /** 220 * Strips all XML comments out of the text. 221 * 222 * @param text the text 223 * @return the text, without the stripped XML comments, or <code>null</code> 224 * if the text is <code>null</code> 225 */ 226 public static String stripComments(String text) { 227 return getHtml().stripComments(text); 228 } 229 230 public static String stripHtml(String text) { 231 return getHtml().stripHtml(text); 232 } 233 234 /** 235 * Encodes the text so that it's safe to use as an HTML input field value. 236 * 237 * <p> 238 * For example, the <code>&</code> character is replaced by 239 * <code>&amp;</code>. 240 * </p> 241 * 242 * @param text the text 243 * @return the encoded text that is safe to use as an HTML input field 244 * value, or <code>null</code> if the text is <code>null</code> 245 */ 246 public static String toInputSafe(String text) { 247 return getHtml().toInputSafe(text); 248 } 249 250 public static String unescape(String text) { 251 return getHtml().unescape(text); 252 } 253 254 public static String unescapeCDATA(String text) { 255 return getHtml().unescapeCDATA(text); 256 } 257 258 public static String wordBreak(String text, int columns) { 259 return getHtml().wordBreak(text, columns); 260 } 261 262 public void setHtml(Html html) { 263 PortalRuntimePermission.checkSetBeanProperty(getClass()); 264 265 _html = html; 266 } 267 268 private static Html _html; 269 270 }