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

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

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

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

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.