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