Class DomElement

java.lang.Object
eu.webtoolkit.jwt.DomElement

public class DomElement
extends java.lang.Object
Class to represent a client-side DOM element (proxy).

The DOM element proxy object is used as an intermediate layer to render the creation of new DOM elements or updates to existing DOM elements. A DOM element can be serialized to HTML or to JavaScript manipulations, and therefore is the main abstraction layer to avoid hard-coding JavaScript-based rendering within the library while still allowing fine-grained Ajax updates or large-scale HTML changes.

This is an internal API, subject to change.

  • Nested Class Summary

    Nested Classes 
    Modifier and Type Class Description
    static class  DomElement.EventAction
    A data-structure for an aggregated event handler.
    static class  DomElement.Mode
    Enumeration for the access mode (creation or update)
    static class  DomElement.Priority
    Enumeration for an update rendering phase.
    static class  DomElement.TimeoutEvent
    Structure for keeping track of timers attached to this element.
  • Constructor Summary

    Constructors 
    Constructor Description
    DomElement​(DomElement.Mode mode, DomElementType type)
    Constructor.
  • Method Summary

    Modifier and Type Method Description
    void addChild​(DomElement child)
    Adds a child.
    void addEvent​(java.lang.String eventName, java.lang.String jsCode)
    This adds more JavaScript to an event handler.
    void addPropertyWord​(Property property, java.lang.String value)
    Adds a 'word' to a property.
    java.lang.String addToParent​(java.lang.StringBuilder out, java.lang.String parentVar, int pos, WApplication app)
    Adds an element to a parent, using suitable methods.
    void asHTML​(EscapeOStream out, EscapeOStream javaScript, java.util.List<DomElement.TimeoutEvent> timeouts)
    Renders the element as HTML.
    void asHTML​(EscapeOStream out, EscapeOStream javaScript, java.util.List<DomElement.TimeoutEvent> timeouts, boolean openingTagOnly)
    Renders the element as HTML.
    java.lang.String asJavaScript​(EscapeOStream out, DomElement.Priority priority)
    Renders the element as JavaScript, by phase.
    void asJavaScript​(java.lang.StringBuilder out)
    Renders the element as JavaScript.
    void callJavaScript​(java.lang.String jsCode)
    Calls JavaScript (related to the DOM element).
    void callJavaScript​(java.lang.String jsCode, boolean evenWhenDeleted)
    Calls JavaScript (related to the DOM element).
    void callMethod​(java.lang.String method)
    Calls a JavaScript method on the DOM element.
    void clearProperties()
    Clears all properties.
    void createElement​(java.lang.StringBuilder out, WApplication app, java.lang.String domInsertJS)
    Renders the element as JavaScript, and inserts it in the DOM.
    static DomElement createNew​(DomElementType type)
    Creates a reference to a new element.
    static void createTimeoutJs​(java.lang.StringBuilder out, java.util.List<DomElement.TimeoutEvent> timeouts, WApplication app)
    Creates the JavaScript statements for timer rendering.
    static java.lang.String cssName​(Property property)
    Returns the name for a CSS property, as a string.
    void declare​(EscapeOStream out)
    Declares the element.
    static void fastHtmlAttributeValue​(EscapeOStream outRaw, EscapeOStream outEscaped, java.lang.String s)
    Utility for rapid rendering of HTML attribute values.
    static void fastJsStringLiteral​(EscapeOStream outRaw, EscapeOStream outEscaped, java.lang.String s)
    Utility for rapid rendering of JavaScript strings.
    java.lang.String getAttribute​(java.lang.String attribute)
    Returns an attribute value set.
    java.lang.String getCreateVar()
    Allocates a JavaScript variable.
    java.lang.String getCssStyle()
    Renders properties and attributes into CSS.
    static DomElement getForUpdate​(WObject object, DomElementType type)
    Creates a reference to an existing element, deriving the ID from an object.
    static DomElement getForUpdate​(java.lang.String id, DomElementType type)
    Creates a reference to an existing element, using its ID.
    java.lang.String getId()
    Returns the id.
    java.lang.String getJavaScript()
    Returns all custom JavaScript collected in this element.
    DomElement.Mode getMode()
    Returns the mode.
    java.util.SortedMap<Property,​java.lang.String> getProperties()
    Returns all properties currently set.
    java.lang.String getProperty​(Property property)
    Returns a property value set.
    DomElementType getType()
    Returns the element type.
    java.lang.String getVar()
    Returns the JavaScript variable name.
    static void htmlAttributeValue​(java.lang.StringBuilder out, java.lang.String s)
    Utility that renders a string as HTML attribute.
    void insertBefore​(DomElement sibling)
    Inserts the element in the DOM as a new sibling.
    void insertChildAt​(DomElement child, int pos)
    Inserts a child.
    boolean isDefaultInline()
    Returns the default display property for this element.
    static boolean isDefaultInline​(DomElementType type)
    Returns whether a paritcular element is by default inline.
    static boolean isSelfClosingTag​(DomElementType element)
    Returns whether a tag is self-closing in HTML.
    static boolean isSelfClosingTag​(java.lang.String tag)
    Returns whether a tag is self-closing in HTML.
    static void jsStringLiteral​(EscapeOStream out, java.lang.String s, char delimiter)
    Utility that renders a string as JavaScript literal.
    static void jsStringLiteral​(java.lang.StringBuilder out, java.lang.String s, char delimiter)
    Utility that renders a string as JavaScript literal.
    static DomElementType parseTagName​(java.lang.String tag)
    Parses a tag name to a DOMElement type.
    void removeAllChildren()
    Removes all children.
    void removeAllChildren​(int firstChild)
    Removes all children.
    void removeAttribute​(java.lang.String attribute)
    Removes an attribute.
    void removeFromParent()
    Removes the element.
    void removeProperty​(Property property)
    Removes a property.
    void replaceWith​(DomElement newElement)
    Replaces the element by another element.
    void saveChild​(java.lang.String id)
    Saves an existing child.
    void setAttribute​(java.lang.String attribute, java.lang.String value)
    Sets an attribute value.
    void setDomElementTagName​(java.lang.String name)
    set dom element custom tag name
    void setEvent​(java.lang.String eventName, java.lang.String jsCode)
    Sets an event handler.
    void setEvent​(java.lang.String eventName, java.lang.String jsCode, java.lang.String signalName)
    Sets an event handler.
    void setEvent​(java.lang.String eventName, java.lang.String jsCode, java.lang.String signalName, boolean isExposed)
    Sets an event handler.
    void setEvent​(java.lang.String eventName, java.util.List<DomElement.EventAction> actions)
    Sets an aggregated event handler.
    void setEventSignal​(java.lang.String eventName, AbstractEventSignal signal)
    Sets an event handler based on a signal's connections.
    void setGlobalUnfocused​(boolean b)  
    void setId​(java.lang.String id)
    Sets the DOM element id.
    void setName​(java.lang.String name)
    Sets a DOM element name.
    void setProperties​(java.util.SortedMap<Property,​java.lang.String> properties)
    Sets a whole map of properties.
    void setProperty​(Property property, java.lang.String value)
    Sets a property.
    void setTimeout​(int msec, boolean jsRepeat)
    Configures the DOM element as a source for timed events.
    void setTimeout​(int delay, int interval)
    Configures the DOM element as a source for timed events, with given initial delay and interval, always repeating.
    void setType​(DomElementType type)
    Sets the element type.
    void setWasEmpty​(boolean how)
    Sets whether the element was initially empty.
    static java.lang.String tagName​(DomElementType type)
    Returns the tag name for a DOMElement type.
    void unstubWith​(DomElement newElement, boolean hideWithDisplay)
    Unstubs an element by another element.
    void unwrap()
    Unwraps an element to progress to Ajax support.
    static DomElement updateGiven​(java.lang.String var, DomElementType type)
    Creates a reference to an existing element, using an expression to access the element.
    void updateInnerHtmlOnly()
    Something to do with broken IE Mobile 5 browsers...
    static java.lang.String urlEncodeS​(java.lang.String url)
    Low-level URL encoding function.
    static java.lang.String urlEncodeS​(java.lang.String url, java.lang.String allowed)
    Low-level URL encoding function.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Constructor Details

    • DomElement

      public DomElement​(DomElement.Mode mode, DomElementType type)
      Constructor.

      This constructs a DomElement reference, with a given mode and element type. Note that even when updating an existing element, the type is taken into account for information on what kind of operations are allowed (workarounds for IE deficiencies for examples) or to infer some basic CSS defaults for it (whether it is inline or a block element).

      Typically, elements are created using one of the 'named' constructors: createNew(), getForUpdate() or updateGiven().

  • Method Details

    • setDomElementTagName

      public void setDomElementTagName​(java.lang.String name)
      set dom element custom tag name
    • urlEncodeS

      public static java.lang.String urlEncodeS​(java.lang.String url)
      Low-level URL encoding function.
    • urlEncodeS

      public static java.lang.String urlEncodeS​(java.lang.String url, java.lang.String allowed)
      Low-level URL encoding function.

      This variant allows the exclusion of certain characters from URL encoding.

    • getMode

      public DomElement.Mode getMode()
      Returns the mode.
    • setType

      public void setType​(DomElementType type)
      Sets the element type.
    • getType

      public DomElementType getType()
      Returns the element type.
    • createNew

      public static DomElement createNew​(DomElementType type)
      Creates a reference to a new element.
    • getForUpdate

      public static DomElement getForUpdate​(java.lang.String id, DomElementType type)
      Creates a reference to an existing element, using its ID.
    • getForUpdate

      public static DomElement getForUpdate​(WObject object, DomElementType type)
      Creates a reference to an existing element, deriving the ID from an object.

      This uses object.getId() as the id.

    • updateGiven

      public static DomElement updateGiven​(java.lang.String var, DomElementType type)
      Creates a reference to an existing element, using an expression to access the element.
    • getVar

      public java.lang.String getVar()
      Returns the JavaScript variable name.

      This variable name is only defined when the element is being rendered using JavaScript, after declare() has been called.

    • setWasEmpty

      public void setWasEmpty​(boolean how)
      Sets whether the element was initially empty.

      Knowing that an element was empty allows optimization of addChild()

    • addChild

      public void addChild​(DomElement child)
      Adds a child.

      Ownership of the child is transferred to this element, and the child should not be manipulated after the call, since it could be that it gets directly converted into HTML and deleted.

    • insertChildAt

      public void insertChildAt​(DomElement child, int pos)
      Inserts a child.

      Ownership of the child is transferred to this element, and the child should not be manipulated after the call.

    • saveChild

      public void saveChild​(java.lang.String id)
      Saves an existing child.

      This detaches the child from the parent, allowing the manipulation of the innerHTML without deleting the child. Stubs in the the new HTML that reference the same id will be replaced with the saved child.

    • setAttribute

      public void setAttribute​(java.lang.String attribute, java.lang.String value)
      Sets an attribute value.
    • getAttribute

      public java.lang.String getAttribute​(java.lang.String attribute)
      Returns an attribute value set.

      See Also:
      setAttribute(String attribute, String value)
    • removeAttribute

      public void removeAttribute​(java.lang.String attribute)
      Removes an attribute.
    • setProperty

      public void setProperty​(Property property, java.lang.String value)
      Sets a property.
    • addPropertyWord

      public void addPropertyWord​(Property property, java.lang.String value)
      Adds a 'word' to a property.

      This adds a word (delimited by a space) to an existing property value.

    • getProperty

      public java.lang.String getProperty​(Property property)
      Returns a property value set.

      See Also:
      setProperty(Property property, String value)
    • removeProperty

      public void removeProperty​(Property property)
      Removes a property.
    • setProperties

      public void setProperties​(java.util.SortedMap<Property,​java.lang.String> properties)
      Sets a whole map of properties.
    • getProperties

      public java.util.SortedMap<Property,​java.lang.String> getProperties()
      Returns all properties currently set.
    • clearProperties

      public void clearProperties()
      Clears all properties.
    • setEventSignal

      public void setEventSignal​(java.lang.String eventName, AbstractEventSignal signal)
      Sets an event handler based on a signal's connections.
    • setEvent

      public void setEvent​(java.lang.String eventName, java.lang.String jsCode, java.lang.String signalName, boolean isExposed)
      Sets an event handler.

      This sets an event handler by a combination of client-side JavaScript code and a server-side signal to emit.

    • setEvent

      public final void setEvent​(java.lang.String eventName, java.lang.String jsCode, java.lang.String signalName)
    • setEvent

      public void setEvent​(java.lang.String eventName, java.lang.String jsCode)
      Sets an event handler.

      This sets a JavaScript event handler.

    • addEvent

      public void addEvent​(java.lang.String eventName, java.lang.String jsCode)
      This adds more JavaScript to an event handler.
    • setEvent

      public void setEvent​(java.lang.String eventName, java.util.List<DomElement.EventAction> actions)
      Sets an aggregated event handler.
    • setId

      public void setId​(java.lang.String id)
      Sets the DOM element id.
    • setName

      public void setName​(java.lang.String name)
      Sets a DOM element name.
    • setTimeout

      public void setTimeout​(int msec, boolean jsRepeat)
      Configures the DOM element as a source for timed events.
    • setTimeout

      public void setTimeout​(int delay, int interval)
      Configures the DOM element as a source for timed events, with given initial delay and interval, always repeating.
    • callMethod

      public void callMethod​(java.lang.String method)
      Calls a JavaScript method on the DOM element.
    • callJavaScript

      public void callJavaScript​(java.lang.String jsCode, boolean evenWhenDeleted)
      Calls JavaScript (related to the DOM element).
    • callJavaScript

      public final void callJavaScript​(java.lang.String jsCode)
      Calls JavaScript (related to the DOM element).

      Calls callJavaScript(jsCode, false)

    • getId

      public java.lang.String getId()
      Returns the id.
    • removeAllChildren

      public void removeAllChildren​(int firstChild)
      Removes all children.

      If firstChild != 0, then only children starting from firstChild are removed.

    • removeAllChildren

      public final void removeAllChildren()
      Removes all children.

      Calls removeAllChildren(0)

    • removeFromParent

      public void removeFromParent()
      Removes the element.
    • replaceWith

      public void replaceWith​(DomElement newElement)
      Replaces the element by another element.
    • unstubWith

      public void unstubWith​(DomElement newElement, boolean hideWithDisplay)
      Unstubs an element by another element.

      Stubs are used to render hidden elements initially and update them in the background. This is almost the same as replaceWith() except that some style properties are copied over (most importantly its visibility).

    • insertBefore

      public void insertBefore​(DomElement sibling)
      Inserts the element in the DOM as a new sibling.
    • unwrap

      public void unwrap()
      Unwraps an element to progress to Ajax support.

      In plain HTML mode, some elements are rendered wrapped in or as another element, to provide more interactivity in the absense of JavaScript.

    • asJavaScript

      public void asJavaScript​(java.lang.StringBuilder out)
      Renders the element as JavaScript.
    • asJavaScript

      public java.lang.String asJavaScript​(EscapeOStream out, DomElement.Priority priority)
      Renders the element as JavaScript, by phase.

      To avoid temporarily having dupliate IDs as elements move around in the page, rendering is ordered in a number of phases : first deleting existing elements, then creating new elements, and finally updates to existing elements.

    • asHTML

      public void asHTML​(EscapeOStream out, EscapeOStream javaScript, java.util.List<DomElement.TimeoutEvent> timeouts, boolean openingTagOnly)
      Renders the element as HTML.

      Anything that cannot be rendered as HTML is rendered as javaScript as a by-product.

    • asHTML

      public final void asHTML​(EscapeOStream out, EscapeOStream javaScript, java.util.List<DomElement.TimeoutEvent> timeouts)
      Renders the element as HTML.

      Calls asHTML(out, javaScript, timeouts, false)

    • createTimeoutJs

      public static void createTimeoutJs​(java.lang.StringBuilder out, java.util.List<DomElement.TimeoutEvent> timeouts, WApplication app)
      Creates the JavaScript statements for timer rendering.
    • isDefaultInline

      public boolean isDefaultInline()
      Returns the default display property for this element.

      This returns whether the element is by default an inline or block element.

    • declare

      public void declare​(EscapeOStream out)
      Declares the element.

      Only after the element has been declared, getVar() returns a useful JavaScript reference.

    • getCssStyle

      public java.lang.String getCssStyle()
      Renders properties and attributes into CSS.
    • fastJsStringLiteral

      public static void fastJsStringLiteral​(EscapeOStream outRaw, EscapeOStream outEscaped, java.lang.String s)
      Utility for rapid rendering of JavaScript strings.

      It uses pre-computed mixing rules for escaping of the string.

    • jsStringLiteral

      public static void jsStringLiteral​(EscapeOStream out, java.lang.String s, char delimiter)
      Utility that renders a string as JavaScript literal.
    • jsStringLiteral

      public static void jsStringLiteral​(java.lang.StringBuilder out, java.lang.String s, char delimiter)
      Utility that renders a string as JavaScript literal.
    • fastHtmlAttributeValue

      public static void fastHtmlAttributeValue​(EscapeOStream outRaw, EscapeOStream outEscaped, java.lang.String s)
      Utility for rapid rendering of HTML attribute values.

      It uses pre-computed mixing rules for escaping of the attribute value.

    • htmlAttributeValue

      public static void htmlAttributeValue​(java.lang.StringBuilder out, java.lang.String s)
      Utility that renders a string as HTML attribute.
    • isSelfClosingTag

      public static boolean isSelfClosingTag​(java.lang.String tag)
      Returns whether a tag is self-closing in HTML.
    • isSelfClosingTag

      public static boolean isSelfClosingTag​(DomElementType element)
      Returns whether a tag is self-closing in HTML.
    • parseTagName

      public static DomElementType parseTagName​(java.lang.String tag)
      Parses a tag name to a DOMElement type.
    • tagName

      public static java.lang.String tagName​(DomElementType type)
      Returns the tag name for a DOMElement type.
    • cssName

      public static java.lang.String cssName​(Property property)
      Returns the name for a CSS property, as a string.
    • isDefaultInline

      public static boolean isDefaultInline​(DomElementType type)
      Returns whether a paritcular element is by default inline.
    • getJavaScript

      public java.lang.String getJavaScript()
      Returns all custom JavaScript collected in this element.
    • updateInnerHtmlOnly

      public void updateInnerHtmlOnly()
      Something to do with broken IE Mobile 5 browsers...
    • addToParent

      public java.lang.String addToParent​(java.lang.StringBuilder out, java.lang.String parentVar, int pos, WApplication app)
      Adds an element to a parent, using suitable methods.

      Depending on the type, different DOM methods are needed. In particular for table cells, some browsers require dedicated API instead of generic insertAt() or appendChild() functions.

    • createElement

      public void createElement​(java.lang.StringBuilder out, WApplication app, java.lang.String domInsertJS)
      Renders the element as JavaScript, and inserts it in the DOM.
    • getCreateVar

      public java.lang.String getCreateVar()
      Allocates a JavaScript variable.
    • setGlobalUnfocused

      public void setGlobalUnfocused​(boolean b)