Wt: Wt::DomElement Class Reference

Wt 4.10.4

Loading...
Searching...
No Matches
Classes | Public Types | Public Member Functions | Static Public Member Functions | List of all members
Wt::DomElement Class Reference

Class to represent a client-side DOM element (proxy). More...

## Classes
struct | EventAction
| A data-structure for an aggregated event handler. More...
struct | TimeoutEvent
| Structure for keeping track of timers attached to this element. More...

## Public Types
enum class | Mode
| Enumeration for the access mode (creation or update)
enum class | Priority
| Enumeration for an update rendering phase.
typedef std::map< Wt::Property, std::string > | PropertyMap
| A map for property values.
typedef std::vector< TimeoutEvent > | TimeoutList
| A list of timeouts.

## Public Member Functions
| DomElement (Mode mode, DomElementType type)
| Constructor.
| ~DomElement ()
| Destructor.
void | setDomElementTagName (const std::string &name)
| set dom element custom tag name
Mode | mode () const
| Returns the mode.
void | setType (DomElementType type)
| Sets the element type.
DomElementType | type () const
| Returns the element type.
std::string | var ()
| Returns the JavaScript variable name.
void | setWasEmpty (bool how)
| Sets whether the element was initially empty.
void | addChild (DomElement *child)
| Adds a child.
void | insertChildAt (DomElement *child, int pos)
| Inserts a child.
void | saveChild (const std::string &id)
| Saves an existing child.
void | setAttribute (const std::string &attribute, const std::string &value)
| Sets an attribute value.
std::string | getAttribute (const std::string &attribute) const
| Returns an attribute value set.
void | removeAttribute (const std::string &attribute)
| Removes an attribute.
void | setProperty (Wt::Property property, const std::string &value)
| Sets a property.
void | addPropertyWord (Wt::Property property, const std::string &value)
| Adds a 'word' to a property.
std::string | getProperty (Wt::Property property) const
| Returns a property value set.
void | removeProperty (Wt::Property property)
| Removes a property.
void | setProperties (const PropertyMap &properties)
| Sets a whole map of properties.
const PropertyMap & | properties () const
| Returns all properties currently set.
void | clearProperties ()
| Clears all properties.
void | setEventSignal (const char *eventName, const EventSignalBase &signal)
| Sets an event handler based on a signal's connections.
void | setEvent (const char *eventName, const std::string &jsCode, const std::string &signalName, bool isExposed=false)
| Sets an event handler.
void | setEvent (const char *eventName, const std::string &jsCode)
| Sets an event handler.
void | addEvent (const char *eventName, const std::string &jsCode)
| This adds more JavaScript to an event handler.
void | setEvent (const char *eventName, const std::vector< EventAction > &actions)
| Sets an aggregated event handler.
void | setId (const std::string &id)
| Sets the DOM element id.
void | setName (const std::string &name)
| Sets a DOM element name.
void | setTimeout (int msec, bool 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 | callMethod (const std::string &method)
| Calls a JavaScript method on the DOM element.
void | callJavaScript (const std::string &javascript, bool evenWhenDeleted=false)
| Calls JavaScript (related to the DOM element).
const std::string & | id () const
| Returns the id.
void | removeAllChildren (int firstChild=0)
| Removes all children.
void | removeFromParent ()
| Removes the element.
void | replaceWith (DomElement *newElement)
| Replaces the element by another element.
void | unstubWith (DomElement *newElement, bool hideWithDisplay)
| Unstubs an element by another element.
void | insertBefore (DomElement *sibling)
| Inserts the element in the DOM as a new sibling.
void | unwrap ()
| Unwraps an element to progress to Ajax support.
void | asJavaScript (WStringStream &out)
| Renders the element as JavaScript.
std::string | asJavaScript (EStream &out, Priority priority) const
| Renders the element as JavaScript, by phase.
void | asHTML (EStream &out, EStream &javaScript, TimeoutList &timeouts, bool openingTagOnly=false) const
| Renders the element as HTML.
bool | isDefaultInline () const
| Returns the default display property for this element.
void | declare (EStream &out) const
| Declares the element.
std::string | cssStyle () const
| Renders properties and attributes into CSS.
std::string | javaScript () const
| Returns all custom JavaScript collected in this element.
void | updateInnerHtmlOnly ()
| Something to do with broken IE Mobile 5 browsers...
std::string | addToParent (WStringStream &out, const std::string &parentVar, int pos, WApplication *app)
| Adds an element to a parent, using suitable methods.
void | createElement (WStringStream &out, WApplication *app, const std::string &domInsertJS)
| Renders the element as JavaScript, and inserts it in the DOM.
std::string | createVar () const
| Allocates a JavaScript variable.

## Static Public Member Functions
static std::string | urlEncodeS (const std::string &url)
| Low-level URL encoding function.
static std::string | urlEncodeS (const std::string &url, const std::string &allowed)
| Low-level URL encoding function.
static DomElement * | createNew (DomElementType type)
| Creates a reference to a new element.
static DomElement * | getForUpdate (const std::string &id, DomElementType type)
| Creates a reference to an existing element, using its ID.
static DomElement * | getForUpdate (const WObject *object, DomElementType type)
| Creates a reference to an existing element, deriving the ID from an object.
static DomElement * | updateGiven (const std::string &el, DomElementType type)
| Creates a reference to an existing element, using an expression to access the element.
static void | createTimeoutJs (WStringStream &out, const TimeoutList &timeouts, WApplication *app)
| Creates the JavaScript statements for timer rendering.
static void | fastJsStringLiteral (EStream &outRaw, const EStream &outEscaped, const std::string &s)
| Utility for rapid rendering of JavaScript strings.
static void | jsStringLiteral (EStream &out, const std::string &s, char delimiter)
| Utility that renders a string as JavaScript literal.
static void | jsStringLiteral (WStringStream &out, const std::string &s, char delimiter)
| Utility that renders a string as JavaScript literal.
static void | fastHtmlAttributeValue (EStream &outRaw, const EStream &outEscaped, const std::string &s)
| Utility for rapid rendering of HTML attribute values.
static void | htmlAttributeValue (WStringStream &out, const std::string &s)
| Utility that renders a string as HTML attribute.
static bool | isSelfClosingTag (const std::string &tag)
| Returns whether a tag is self-closing in HTML.
static bool | isSelfClosingTag (DomElementType element)
| Returns whether a tag is self-closing in HTML.
static DomElementType | parseTagName (const std::string &tag)
| Parses a tag name to a DOMElement type.
static std::string | tagName (DomElementType type)
| Returns the tag name for a DOMElement type.
static std::string | cssName (Property property)
| Returns the name for a CSS property, as a string.
static std::string | cssJavaScriptName (Property property)
| Returns the name for a JavaScript DOM style property, as a string.
static bool | isDefaultInline (DomElementType type)
| Returns whether a paritcular element is by default inline.

## Detailed Description

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 & Destructor Documentation

## ◆ DomElement()

Wt::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().

## Member Function Documentation

## ◆ addChild()

void Wt::DomElement::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.

## ◆ addPropertyWord()

void Wt::DomElement::addPropertyWord | ( | Wt::Property | property,
|  | const std::string & | value )

Adds a 'word' to a property.

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

## ◆ addToParent()

std::string Wt::DomElement::addToParent | ( | WStringStream & | out,
|  | const std::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.

## ◆ asHTML()

void Wt::DomElement::asHTML | ( | EStream & | out,
|  | EStream & | javaScript,
|  | TimeoutList & | timeouts,
|  | bool | openingTagOnly = false ) const

Renders the element as HTML.

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

## ◆ asJavaScript()

std::string Wt::DomElement::asJavaScript | ( | EStream & | out,
|  | Priority | priority ) const

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.

## ◆ declare()

void Wt::DomElement::declare | ( | EStream & | out | ) | const

Declares the element.

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

## ◆ fastHtmlAttributeValue()

static void Wt::DomElement::fastHtmlAttributeValue | ( | EStream & | outRaw,
|  | const EStream & | outEscaped,
|  | const std::string & | s )
| static

Utility for rapid rendering of HTML attribute values.

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

## ◆ fastJsStringLiteral()

static void Wt::DomElement::fastJsStringLiteral | ( | EStream & | outRaw,
|  | const EStream & | outEscaped,
|  | const std::string & | s )
| static

Utility for rapid rendering of JavaScript strings.

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

## ◆ getAttribute()

std::string Wt::DomElement::getAttribute | ( | const std::string & | attribute | ) | const

Returns an attribute value set.

See also
  setAttribute()

## ◆ getForUpdate()

static DomElement * Wt::DomElement::getForUpdate | ( | const WObject * | object,
|  | DomElementType | type )
| static

Creates a reference to an existing element, deriving the ID from an object.

This uses object->id() as the id.

## ◆ getProperty()

std::string Wt::DomElement::getProperty | ( | Wt::Property | property | ) | const

Returns a property value set.

See also
  setProperty()

## ◆ insertChildAt()

void Wt::DomElement::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.

## ◆ isDefaultInline()

bool Wt::DomElement::isDefaultInline | ( |  | ) | const

Returns the default display property for this element.

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

## ◆ removeAllChildren()

void Wt::DomElement::removeAllChildren | ( | int | firstChild = 0 | ) |

Removes all children.

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

## ◆ saveChild()

void Wt::DomElement::saveChild | ( | const std::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.

## ◆ setEvent() [1/2]

void Wt::DomElement::setEvent | ( | const char * | eventName,
|  | const std::string & | jsCode )

Sets an event handler.

This sets a JavaScript event handler.

## ◆ setEvent() [2/2]

void Wt::DomElement::setEvent | ( | const char * | eventName,
|  | const std::string & | jsCode,
|  | const std::string & | signalName,
|  | bool | isExposed = false )

Sets an event handler.

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

## ◆ setWasEmpty()

void Wt::DomElement::setWasEmpty | ( | bool | how | ) |

Sets whether the element was initially empty.

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

## ◆ unstubWith()

void Wt::DomElement::unstubWith | ( | DomElement * | newElement,
|  | bool | 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).

## ◆ unwrap()

void Wt::DomElement::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.

## ◆ urlEncodeS()

static std::string Wt::DomElement::urlEncodeS | ( | const std::string & | url,
|  | const std::string & | allowed )
| static

Low-level URL encoding function.

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

## ◆ var()

std::string Wt::DomElement::var | ( |  | ) |

Returns the JavaScript variable name.

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