Wt  3.3.8
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

typedef std::map< Wt::Property, std::string > PropertyMap
 A map for property values.
 
typedef std::vector< TimeoutEventTimeoutList
 A list of timeouts.
 

Public Member Functions

 DomElement (Mode mode, DomElementType type)
 Constructor. More...
 
 ~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. More...
 
void setWasEmpty (bool how)
 Sets whether the element was initially empty. More...
 
void addChild (DomElement *child)
 Adds a child. More...
 
void insertChildAt (DomElement *child, int pos)
 Inserts a child. More...
 
void saveChild (const std::string &id)
 Saves an existing child. More...
 
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. More...
 
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. More...
 
std::string getProperty (Wt::Property property) const
 Returns a property value set. More...
 
void removeProperty (Wt::Property property)
 Removes a property.
 
void setProperties (const PropertyMap &properties)
 Sets a whole map of properties.
 
const PropertyMapproperties () 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. More...
 
void setEvent (const char *eventName, const std::string &jsCode)
 Sets an event handler. More...
 
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 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. More...
 
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. More...
 
void insertBefore (DomElement *sibling)
 Inserts the element in the DOM as a new sibling.
 
void unwrap ()
 Unwraps an element to progress to Ajax support. More...
 
void asJavaScript (WStringStream &out)
 Renders the element as JavaScript.
 
std::string asJavaScript (EStream &out, Priority priority) const
 Renders the element as JavaScript, by phase. More...
 
void asHTML (EStream &out, EStream &javaScript, TimeoutList &timeouts, bool openingTagOnly=false) const
 Renders the element as HTML. More...
 
bool isDefaultInline () const
 Returns the default display property for this element. More...
 
void declare (EStream &out) const
 Declares the element. More...
 
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. More...
 
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. More...
 
static DomElementcreateNew (DomElementType type)
 Creates a reference to a new element.
 
static DomElementgetForUpdate (const std::string &id, DomElementType type)
 Creates a reference to an existing element, using its ID.
 
static DomElementgetForUpdate (const WObject *object, DomElementType type)
 Creates a reference to an existing element, deriving the ID from an object. More...
 
static DomElementupdateGiven (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. More...
 
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. More...
 
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 const std::string & cssName (Property property)
 Returns the name for a CSS 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

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

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.

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.

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.

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.

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.

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

Declares the element.

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

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.

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.

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

Returns an attribute value set.

See also
setAttribute()
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.

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

Returns a property value set.

See also
setProperty()
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.

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.

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

Removes all children.

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

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.

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.

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

Sets an event handler.

This sets a JavaScript event handler.

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

Sets whether the element was initially empty.

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

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).

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.

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.

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.


Generated on Mon Sep 4 2017 for the C++ Web Toolkit (Wt) by doxygen 1.8.11