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&reg; 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&reg; 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 &lt;)
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;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    }