Package eu.webtoolkit.jwt

Class WText

  • Direct Known Subclasses:
    IndexText
    public class WText
extends WInteractWidget
    A widget that renders (XHTML) text.

    The text is provided through a WString, which may either hold a literal text, or a key to localized text which is looked up in locale dependent XML files (see WString#tr()).

    Use setTextFormat() to configure the textFormat of the text. The default textFormat is TextFormat.XHTML, which allows XHMTL markup to be included in the text. Tags and attributes that indicate "active" content are not allowed and stripped out, to avoid security risks exposed by JavaScript such as the common web-based Cross-Site Scripting (XSS) malicious attack. XSS is the situation where one user of your web application is able to execute a script in another user's browser while your application only intended to display a message entered by the mailicious user to the other user. To defeat this attack, JWt assumes that content in a WText is intended to be passive, and not contain any scripting elements.

    The TextFormat.XHTML format will automatically change to TextFormat.Plain if the text is not valid XML. Properly formatted HTML, which is not valid XHTML (e.g. a <br> tag without closing tag) will thus be shown literally, since the HTML markup will be escaped. JWt does this as a safety measure, since it cannot reliably run the XSS filter without parsing the XML successfully.

    The TextFormat.Plain format will display the text literally (escaping any HTML special characters).

    In some situations, TextFormat.UnsafeXHTML may be useful to explicitly allow scripting content. Like TextFormat.XHTML, it allows XHTML markup, but it also allows potentially dangerous tags and attributes. Use this if you're sure that a user cannot interfere with the text set, and TextFormat.XHTML is too limiting.

    WText is by default inline, unless the XHTML contents starts with an element such as <div>, <h> or <p> that is displayed as a block, in which case the widget will also display as a block.

    CSS

    The widget corresponds to an HTML <span> tag or an HTML <div> depending on whether the widget is inline.

    This widget does not provide styling, and can be styled using inline or external CSS as appropriate.

    See Also:
    WApplication.setLocale(Locale locale, boolean doRefresh)

    • Method Detail

      • getText

        public WString getText()
        Returns the text.

        When a literal XHTMLFormatted text was set, this may differ from the text that was set since malicious tags/attributes may have been stripped.

        See Also:
        setText(CharSequence text)

      • setText

        public boolean setText​(java.lang.CharSequence text)
        Sets the text.

        When the current format is TextFormat.XHTML, and text is literal (not created using WString#tr()), it is parsed using an XML parser which discards malicious tags and attributes silently. When the parser encounters an XML parse error, the textFormat is changed to TextFormat.Plain. If text is not a literal, the same parser is applied only when the text is resolved.

        Returns whether the text could be set using the current textFormat. A return value of false indicates that the textFormat was changed in order to be able to accept the new text.

        See Also:
        getText(), setText(CharSequence text)

      • setTextFormat

        public boolean setTextFormat​(TextFormat textFormat)
        Sets the text format.

        The textFormat controls how the string should be interpreted: either as plain text, which is displayed literally, or as XHTML-markup.

        When changing the textFormat to TextFormat.XHTML, and the current text is literal (not created using WString#tr()), the current text is parsed using an XML parser which discards malicious tags and attributes silently. When the parser encounters an XML parse error, the textFormat is left unchanged, and this method returns false.

        Returns whether the textFormat could be set for the current text.

        The default format is TextFormat.XHTML.

      • setWordWrap

        public void setWordWrap​(boolean wordWrap)
        Configures word wrapping.

        When wordWrap is true, the widget may break lines, creating a multi-line text. When wordWrap is false, the text will displayed on a single line, unless the text contains end-of-lines (for TextFormat.Plain) or <br /> tags or other block-level tags (for TextFormat.XHTML).

        The default value is true.

        See Also:
        isWordWrap()

      • setTextAlignment

        public void setTextAlignment​(AlignmentFlag textAlignment)
        Specifies how text is aligned.

        Only the horizontal alignment can be specified. Note that there is no way to specify vertical alignment. You can put the text in a layout with vertical alignment options though, or (misuse) the line-height CSS property for single line texts.

      • setPadding

        public void setPadding​(WLength length,
                       java.util.EnumSet<Side> sides)
        Sets padding inside the widget.

        Setting padding has the effect of adding distance between the widget children and the border.

        Note: for an inline WText padding is only supported on the left and/or right. Setting padding on the top or bottom has no effect.

      • setInternalPathEncoding

        public void setInternalPathEncoding​(boolean enabled)
        Enables internal path encoding of anchors in the XHTML text.

        Anchors to internal paths are represented differently depending on the session implementation (plain HTML, Ajax or HTML5 history). By enabling this option, anchors which reference an internal path (by referring a URL of the form href="#/..." ), are re-encoded to link to the internal path.

        When using TextFormat.XHTML (or TextFormat.UnsafeXHTML) formatted text, the text is pasted verbatim in the browser (with the exception of XSS filtering if applicable). With this option, however, the XHTML text may be transformed at the cost of an additional XML parsing step.

        The default value is false.

      • refresh

        public void refresh()
        Description copied from class: WWidget
        Refresh the widget.

        The refresh method is invoked when the locale is changed using WApplication#setLocale() or when the user hit the refresh button.

        The widget must actualize its contents in response.

        Note: This does not rerender the widget! Calling refresh() usually does not have any effect (unless you've reimplemented refresh() to attach to it an effect).

        Overrides:
        refresh in class WWebWidget

      • render

        protected void render​(java.util.EnumSet<RenderFlag> flags)
        Description copied from class: WWidget
        Renders the widget.

        This function renders the widget (or an update for the widget), after this has been scheduled using scheduleRender().

        The default implementation will render the widget by serializing changes to JavaScript and HTML. You may want to reimplement this widget if you have been postponing some of the layout / rendering implementation until the latest moment possible. In that case you should make sure you call the base implementation however.

        Overrides:
        render in class WInteractWidget