Package eu.webtoolkit.jwt

Class DomElement

java.lang.Object
eu.webtoolkit.jwt.DomElement
public class DomElement extends 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.

  • 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(String name)
      set dom element custom tag name

    • urlEncodeS

      public static String urlEncodeS(String url)
      Low-level URL encoding function.

    • urlEncodeS

      public static String urlEncodeS(String url, 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(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(String var, DomElementType type)
      Creates a reference to an existing element, using an expression to access the element.

    • getVar

      public 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(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(String attribute, String value)
      Sets an attribute value.

    • getAttribute

      public String getAttribute(String attribute)
      Returns an attribute value set.

      See Also:

    • removeAttribute

      public void removeAttribute(String attribute)
      Removes an attribute.

    • setProperty

      public void setProperty(Property property, String value)
      Sets a property.

    • addPropertyWord

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

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

      See Also:

    • addPropertyWords

      public void addPropertyWords(Property property, String value)
      Adds multiple 'words' to a property.

      This adds multiple words (separated by spaces) to an existing property value.

      See Also:

    • getProperty

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

      See Also:

    • removeProperty

      public void removeProperty(Property property)
      Removes a property.

    • setProperties

      public void setProperties(SortedMap<Property,String> properties)
      Sets a whole map of properties.

    • getProperties

      public SortedMap<Property,String> getProperties()
      Returns all properties currently set.

    • clearProperties

      public void clearProperties()
      Clears all properties.

    • setEventSignal

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

    • setEvent

      public void setEvent(String eventName, String jsCode, 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(String eventName, String jsCode, String signalName)
      Sets an event handler.

      Calls setEvent(eventName, jsCode, signalName, false)

    • setEvent

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

      This sets a JavaScript event handler.

    • addEvent

      public void addEvent(String eventName, String jsCode)
      This adds more JavaScript to an event handler.

    • setEvent

      public void setEvent(String eventName, List<DomElement.EventAction> actions)
      Sets an aggregated event handler.

    • setId

      public void setId(String id)
      Sets the DOM element id.

    • setName

      public void setName(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(String method)
      Calls a JavaScript method on the DOM element.

    • callJavaScript

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

    • callJavaScript

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

      Calls callJavaScript(jsCode, false)

    • getId

      public 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(StringBuilder out)
      Renders the element as JavaScript.

    • asJavaScript

      public 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, 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, List<DomElement.TimeoutEvent> timeouts)
      Renders the element as HTML.

      Calls asHTML(out, javaScript, timeouts, false)

    • createTimeoutJs

      public static void createTimeoutJs(StringBuilder out, 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 String getCssStyle()
      Renders properties and attributes into CSS.

    • fastJsStringLiteral

      public static void fastJsStringLiteral(EscapeOStream outRaw, EscapeOStream outEscaped, 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, String s, char delimiter)
      Utility that renders a string as JavaScript literal.

    • jsStringLiteral

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

    • fastHtmlAttributeValue

      public static void fastHtmlAttributeValue(EscapeOStream outRaw, EscapeOStream outEscaped, 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(StringBuilder out, String s)
      Utility that renders a string as HTML attribute.

    • isSelfClosingTag

      public static boolean isSelfClosingTag(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(String tag)
      Parses a tag name to a DOMElement type.

    • tagName

      public static String tagName(DomElementType type)
      Returns the tag name for a DOMElement type.

    • cssName

      public static String cssName(Property property)
      Returns the name for a CSS property, as a string.

    • cssJavaScriptName

      public static String cssJavaScriptName(Property property)
      Returns the name for a JavaScript DOM style property, as a string.

    • isDefaultInline

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

    • getJavaScript

      public 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 String addToParent(StringBuilder out, 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(StringBuilder out, WApplication app, String domInsertJS)
      Renders the element as JavaScript, and inserts it in the DOM.

    • getCreateVar

      public String getCreateVar()
      Allocates a JavaScript variable.

    • setGlobalUnfocused

      public void setGlobalUnfocused(boolean b)