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 public static String escapeJSLink(String link) { 104 return getHtml().escapeJSLink(link); 105 } 106 107 /** 108 * Escapes the URL value so that it is safe to use as a URL. 109 * 110 * @param url the URL value to escape 111 * @return the escaped URL value, or <code>null</code> if the URL value is 112 * <code>null</code> 113 */ 114 public static String escapeURL(String url) { 115 return getHtml().escapeURL(url); 116 } 117 118 public static String escapeXPath(String xPath) { 119 return getHtml().escapeXPath(xPath); 120 } 121 122 public static String escapeXPathAttribute(String xPathAttribute) { 123 return getHtml().escapeXPathAttribute(xPathAttribute); 124 } 125 126 /** 127 * Extracts the raw text from the HTML input, compressing its whitespace and 128 * removing all attributes, scripts, and styles. 129 * 130 * <p> 131 * For example, raw text returned by this method can be stored in a search 132 * index. 133 * </p> 134 * 135 * @param html the HTML text 136 * @return the raw text from the HTML input, or <code>null</code> if the 137 * HTML input is <code>null</code> 138 */ 139 public static String extractText(String html) { 140 return getHtml().extractText(html); 141 } 142 143 public static String fromInputSafe(String text) { 144 return getHtml().fromInputSafe(text); 145 } 146 147 public static String getAUICompatibleId(String html) { 148 return getHtml().getAUICompatibleId(html); 149 } 150 151 public static Html getHtml() { 152 PortalRuntimePermission.checkGetBeanProperty(HtmlUtil.class); 153 154 return _html; 155 } 156 157 /** 158 * Renders the HTML content into text. This provides a human readable 159 * version of the segment content that is modeled on the way Mozilla 160 * Thunderbird® and other email clients provide an automatic conversion 161 * of HTML content to text in their alternative MIME encoding of emails. 162 * 163 * <p> 164 * Using the default settings, the output complies with the 165 * <code>Text/Plain; Format=Flowed (DelSp=No)</code> protocol described in 166 * <a href="http://tools.ietf.org/html/rfc3676">RFC-3676</a>. 167 * </p> 168 * 169 * @param html the HTML text 170 * @return the rendered HTML text, or <code>null</code> if the HTML text is 171 * <code>null</code> 172 */ 173 public static String render(String html) { 174 return getHtml().render(html); 175 } 176 177 /** 178 * Replaces all Microsoft® Word Unicode characters with plain HTML 179 * entities or characters. 180 * 181 * @param text the text 182 * @return the converted text, or <code>null</code> if the text is 183 * <code>null</code> 184 * @deprecated As of 7.0.0, with no direct replacement 185 */ 186 @Deprecated 187 public static String replaceMsWordCharacters(String text) { 188 return getHtml().replaceMsWordCharacters(text); 189 } 190 191 /** 192 * Replaces all new lines or carriage returns with the <code><br /></code> 193 * HTML tag. 194 * 195 * @param html the text 196 * @return the converted text, or <code>null</code> if the HTML text is 197 * <code>null</code> 198 */ 199 public static String replaceNewLine(String html) { 200 return getHtml().replaceNewLine(html); 201 } 202 203 /** 204 * Strips all content delimited by the tag out of the text. 205 * 206 * <p> 207 * If the tag appears multiple times, all occurrences (including the tag) 208 * are stripped. The tag may have attributes. In order for this method to 209 * recognize the tag, it must consist of a separate opening and closing tag. 210 * Self-closing tags remain in the result. 211 * </p> 212 * 213 * @param text the text 214 * @param tag the tag used for delimiting, which should only be the tag's 215 * name (e.g. no <) 216 * @return the text, without the stripped tag and its contents, or 217 * <code>null</code> if the text is <code>null</code> 218 */ 219 public static String stripBetween(String text, String tag) { 220 return getHtml().stripBetween(text, tag); 221 } 222 223 /** 224 * Strips all XML comments out of the text. 225 * 226 * @param text the text 227 * @return the text, without the stripped XML comments, or <code>null</code> 228 * if the text is <code>null</code> 229 */ 230 public static String stripComments(String text) { 231 return getHtml().stripComments(text); 232 } 233 234 public static String stripHtml(String text) { 235 return getHtml().stripHtml(text); 236 } 237 238 /** 239 * Encodes the text so that it's safe to use as an HTML input field value. 240 * 241 * <p> 242 * For example, the <code>&</code> character is replaced by 243 * <code>&amp;</code>. 244 * </p> 245 * 246 * @param text the text 247 * @return the encoded text that is safe to use as an HTML input field 248 * value, or <code>null</code> if the text is <code>null</code> 249 */ 250 public static String toInputSafe(String text) { 251 return getHtml().toInputSafe(text); 252 } 253 254 public static String unescape(String text) { 255 return getHtml().unescape(text); 256 } 257 258 public static String unescapeCDATA(String text) { 259 return getHtml().unescapeCDATA(text); 260 } 261 262 public static String wordBreak(String text, int columns) { 263 return getHtml().wordBreak(text, columns); 264 } 265 266 public void setHtml(Html html) { 267 PortalRuntimePermission.checkSetBeanProperty(getClass()); 268 269 _html = html; 270 } 271 272 private static Html _html; 273 274 }