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)

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


var html = '<div>
    <h1>title</h1>
    <p>description</p>
</div>'.toDom();

html.children().addClass('child');
html.find('p').addClass('paragraph');
after(Mixed:element)

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


var html = '<div>
    <h1>title</h1>
    <p>description</p>
</div>'.toDom();

html.find('p').after('<p>appears after description</p>');
append(Mixed:element)

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


var html = '<div>
    <h1>title</h1>
    <p>description</p>
</div>'.toDom();

html.append('<a href="...">...read more</a>');
attr(String:name [, String:value])

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


var link = '<a>About Us</a>'.toDom();
link.attr('href', '/company'); // sets the attr
print(link.attr('href')); // renders "/company"
before(Mixed:element)

Returns Dom

Insert a new Dom element supplied as either a String or an existing Dom element before the Dom subject.


var html = '<div>
    <h1>title</h1>
    <p>description</p>
</div>'.toDom();

html.find('p').before('<p>appears before description</p>');
children()

Returns DomQueryResult

Get all child node elements for the current Dom element.


var div = '<div><p>1</p><p>2</p></div>'.toDom();
var kids = div.children();
for(var i in kids){
    var kid = kids[i];
    print(kid); 
}
clear()

Returns Dom

Remove all child nodes for the current Dom element and returns itself.


var div = '<div><p>1</p><p>2</p></div>'.toDom();
div.clear();
print(div); // <div></div>
css(String:property [, String:value])

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


var html = '<div />'.toDom();
html.css('background-image', 'url(/path/to/image.png)');
find(String:selector)

Returns DomQueryResult

Returns all Dom elements within the current Dom element matching the selector search. We currently support the following selector formats:

  • #id - ID Selector, match a single element with a given id attribute
  • .class - Class Selector, match all elements with a given class
  • element - Element Selector, match all elements with a given tag name
  • selector1,selector2 - Multi Selector, selects the combined elements matching all selectors
  • :first-child - Selects all elements that are the first child of their parent
  • :last-child - Select all elements that are the last child of their parent
  • :nth-child(n) - Select all elements that an nth child of their parent (Indexes start from 1)
  • :gt(n) - Select all elements at an index greater than index n (Indexes start from 0)
  • :lt(n) - Select all elements at an index less than index n (Indexes start from 0)
  • :eq(n) - Select the element at an index n (Indexes start from 0)
  • :odd() - Select all elements with an odd index (Indexes start from 0)
  • :even() - Select all elements with an even index (Indexes start from 0) 
  • parent > child - Child Selector, select child matches of the parent
  • [name] - Attribute Selector, select nodes with the named attribute
  • [name="value"] - Attribute Selector, select nodes with the named attribute and with a matching value. Note that the value must be quoted.
  • [name~="value"] - Attribute Selector, select nodes with the named attribute and containing a partial value match. Note that the value must be quoted.


var div = '<div><p>1</p><p>2</p></div>'.toDom();
// zero-indexed odd/even
div.find('p:odd').addClass('odd');
div.find('p:even').addClass('even');
// one-indexed odd/even
div.find('p:nth-child(odd)').addClass('nth-odd');
div.find('p:nth-child(even)').addClass('nth-even');
print(div); 
hasClass(String:className)

Returns Boolean

Returns true of the element has a class attribute containing name or false if not.

height(String:height)

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


var img = '<img src="..." />'.toDom();
img.height(200);
print(img); // <img style="height:200px" />
hide()

Returns Dom

Hide the element using display:none; within the style attribute. Returns the element itself allowing you to chain methods.


var div = '<div />'.toDom();
div.hide();
print(div); // <div style="display:none"></div>
html([String:html])

Returns 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:identifier])

Returns Dom | String

Get or set the id attribute for the element. 

innerHtml([String:html [, Boolean:clear])

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

Returns Boolean

This method allows you to determine whether an element matches the selector. At present we only accept following selectors on this method:

  • #id - ID Selector, match a single element with a given id attribute
  • .class - Class Selector, match all elements with a given class
  • element - Element Selector, match all elements with a given tag name
parent()

Returns Dom

Returns the parent of the current element.

remove([String:selector])

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


var div = '<div><p>Description <a href="#">[more]</a></p></div>'.toDom();
div.remove("a");
print(div); // <div><p>Description</div>
removeAttr(String:name)

Returns Dom

Remove the attribute of name from the current element. Returns the Dom object itself allowing you to chain methods. 

removeClass(String:name)

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


var div = '<div class="one two three" />'.toDom();
div.removeClass("one three");
print(div); // <div class="two"></div>
show()

Returns Dom

The show method removes any display css properties from the style attribute of the current element. 

text([String:value])

Returns Dom | String

Sets or gets the text content of a Dom element.


var div = '<div />'.toDom();
div.text("description");
print(div); // <div>description</div>
visible(Boolean:isVisible)

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


var div = '<div />'.toDom();
div.visible(false);
print(div); // <div style="visibility:hidden"></div>
width(String:width)

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


var img = '<img src="..." />'.toDom();
img.width(200);
print(img); // <img src="..." style="width:200px" />
wrap(String:html)

Returns Dom

Wrap the current element within a new Dom element supplied as a String and returns the new Dom object.


var p = '<p>Description</p>'.toDom();
var d = p.wrap('<div class="wrapper" />');
print(d); // <div class="wrapper"><p>Description</p></div>
xpath(String:query)

Returns DomQueryResult

Similar to the find method, but allows you to search your Dom element hierarchy using xpath queries. This method accepts most xpath queries.