EVML Dom
Creating an XML/HTML Dom Element from a string and manipulating it within EV Script.
Evance never actually provides you with any view properties/objects pre-packaged as Dom elements, but you can very easily create Dom Elements within your EV Scripts. The EVML Dom is designed to help manipulate HTML elements sometimes in a more graceful manner than by butchering string concatenations.
Start with a String
With all Dom Elements we start with a String containing a valid XML/HTML element. This element may contain any number of child nodes, but should have only one single root node.
// start with a String and convert to DOM
var str = '<a/>';
var link = str.toDom();
// the shorthand version
var link = '<a/>'.toDom();
// INCORRECT and will thow an error
var html = '<strong>title</strong><p>description</p>'.toDom();
// CORRECT intialisation of an Element with child nodes
var html = '<div><h1>title</h1><p>description</p></div>'.toDom();
Outputting Dom Elements as HTML
There are two methods of outputting the HTML of a Dom element.
// example 1: use the html method
print(element.html());
// example 2: the html method is the default toString method
// therefore its use is optional and you can just print an element
print(element);
Methods |
---|
addClass(String:name)
Dom
Add a CSS class name to the Dom node. The class name must be represented as a String and not as a CSS selector.
|
after(Mixed:element)
Dom
Insert a new Dom element supplied as either a String or an existing Dom element after the Dom subject. Returns the imported Dom element.
|
append(Mixed:element)
Dom
Insert new content, supplied either as a valid HTML/XML String or an existing Dom element, to the end of the current Dom element. This may be more than one element when used in a conjunction with a query.
|
attr(String:name [, String:value])
Dom
| String
When both name and value aguments are supplied the this method adds or updates an attribute of the Dom element with the value supplied. If only the name argument is supplied the current value of the attribute will be returned as a String or null if the attribute is not set.
|
before(Mixed:element)
Dom
Insert a new Dom element supplied as either a String or an existing Dom element before the Dom subject.
|
children()
DomQueryResult
Get all child node elements for the current Dom element.
|
clear()
Dom
Remove all child nodes for the current Dom element and returns itself.
|
css(String:property [, String:value])
Dom
| String
When both the property and value arguments are supplied a style attribute is added/updated on the current Dom containing the CSS property: value pair. If the value is provided as an empty string then the CSS property will be removed. If only the property argument is supplied the property value or null will be returned.
|
find(String:selector)
DomQueryResult
Returns all Dom elements within the current Dom element matching the selector search. We currently support the following selector formats:
|
hasClass(String:name)
Boolean
Returns true of the element has a class attribute containing name or false if not. |
height(String:value)
Dom
Set the CSS height of the element. Note that EV Script runs server-side and therefore does not have access to dimensions within CSS files. It only has access to the style attribute of an element. When setting the height of a element you can supply height either as a Number or as a String. If a Number/String is supplied without units this method will assume 'px' to be the units.
|
hide()
Dom
Hide the element using display:none; within the style attribute. Returns the element itself allowing you to chain methods.
|
html([String:htmlCode])
Dom
| String
Get or set the HTML content for the element, this includes the top level node. When calling Dom.html() to get HTML the HTML is returned as a String. When setting HTML the String provided must be valid HTML and must have just one root node, but may contain any child node hierarchy. When setting the HTML this method returns the element itself allowing you to chain methods. |
id([String:reference])
Dom
| String
Get or set the id attribute for the element. |
innerHtml([String:htmlCode [, Boolean:clear]])
Dom
| String
Get or set the inner HTML of the current element. When setting inner HTML the default action is to clear existing content and replace it with new content. The default action may be altered to append additional html to the element by supplying 'false' as the clear argument. |
is(String:selector)
Boolean
This method allows you to determine whether an element matches the selector. At present we only accept following selectors on this method:
|
parent()
Dom
Returns the parent of the current element. |
remove([String:selector])
Dom
If no selector is provided the current element is removed from the Dom object. If a selector is provided any element matching the selector will be removed from the Dom objects. Any selector accepted by the find method is accepted by this method.
|
removeAttr(name)
Dom
Remove the attribute of name from the current element. Returns the Dom object itself allowing you to chain methods. |
removeClass(String:name)
Dom
Remove one or more class from the current element. The name argument may include one or more CSS class names separated by a space. The classes will be removed from the class attribute leaving any other class names intact.
|
show()
Dom
The show method removes any display css properties from the style attribute of the current element. |
text([String:value])
Dom
| String
Sets or gets the text content of a Dom element.
|
visible(Boolean:isVisible)
Dom
Set the current element as either visible or hidden. When the supplied isVisible argument is true a visibility: visible is applied to the style attribute of the current element. Conversely when isVisible is false a visibility: hidden property is applied.
|
width(String:width)
Dom
Set the CSS width of the element. Note that EV Script runs server-side and therefore does not have access to dimensions within CSS files. It only has access to the style attribute of an element. When setting the width of an element you can supply width either as a Number or as a String. If a Number/String is supplied without units this method will assume 'px' to be the units.
|
wrap(String:htmlCode)
Dom
Wrap the current element within a new Dom element supplied as a String and returns the new Dom object.
|
xpath(String:query)
DomQueryResult
Similar to the find method, but allows you to search your Dom element hierarchy using xpath queries. This method accepts most xpath queries. |