Class DomElement
public class DomElement
extends java.lang.Object
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 namevoid
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
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()
orupdateGiven()
.
-
-
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
Returns the mode. -
setType
Sets the element type. -
getType
Returns the element type. -
createNew
Creates a reference to a new element. -
getForUpdate
Creates a reference to an existing element, using its ID. -
getForUpdate
Creates a reference to an existing element, deriving the ID from an object.This uses object.
getId()
as the id. -
updateGiven
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
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
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. -
removeAttribute
public void removeAttribute(java.lang.String attribute)Removes an attribute. -
setProperty
Sets a property. -
addPropertyWord
Adds a 'word' to a property.This adds a word (delimited by a space) to an existing property value.
-
getProperty
Returns a property value set. -
removeProperty
Removes a property. -
setProperties
Sets a whole map of properties. -
getProperties
Returns all properties currently set. -
clearProperties
public void clearProperties()Clears all properties. -
setEventSignal
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)Sets an event handler. -
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
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). -
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
Replaces the element by another element. -
unstubWith
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
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
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. -
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
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
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
Returns whether a tag is self-closing in HTML. -
parseTagName
Parses a tag name to a DOMElement type. -
tagName
Returns the tag name for a DOMElement type. -
cssName
Returns the name for a CSS property, as a string. -
isDefaultInline
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)
-