domnode 2.0.1

A client-side library to easily change and traverse DOM documents.

DomNode

A client-side library to manipulate and traverse DOM objects in a easy and intuitive way. This library does not pretend to be a replacement for the DOM library but, in many cases, it can drastically simplify the code.

How to install

Edit your pubspec.yaml file and add the domnode package:

dependencies:
  domnode: any

Install dependencies:

> pub get

Import the library:

import 'package:domnode/core.dart';

void main() {
  // your code here
}

Introduction

Use query(String cssSelectors, [DomNode context]) to find elements and $(Object source, [Callback callback]) to create elements. Note that both dart:html and package:domnode share the same query function, so it's necessary to hide it from the dart:html library. For example:

For example:

// hides the native 'query' function to prevent collisions
import 'dart:html' hide query;
import 'package:domnode/core.dart';

void main() {
  // searches a node from the current document
  var node = query('#node_id');
  print(node);

  // searches a children node
  var subnode = query('#subnode_id', node);
  print(subnode);

  // creates an anchor node and appens it to the document's body
  query('body').append($('<a href="#" />')
    ..attr['href'] = 'path-to-page'
    ..html = 'Click me <em>Please</em>');

  // creates an anchor and changes some attributes
  $('<a />')
    ..addClass('class1')
    ..attr = {'href': 'path-to-page', '_target': 'blank'}
    ..css = {'text-decoration': 'none', 'color': 'blue'}
    ..text = 'Some text...';
    
  // wraps the document around a DomNode object
  var doc = $(document);
  print(doc.query('#element_id'));
  
  // creates a document from a string
  var root = $('''
  <root>
    <item id="1">Item 1</item>
    <item id="2">Item 2</item>
    <item id="3">Item 3</item>
  </root>''');
}

Examples

Getting elements from a document

DomNode is the main class of this library. It extends the IterableBase class, which means that you can think of it as if it were a single element or multiple elements. Use the query method to select zero, one or more elements. For example, consider the following code:

// gets a single node
var node = query('h1');
if (node.length == 0) {
  print('Node not found');
}

// gests multiple nodes
var nodes = query('p');
nodes.forEach((node) {
  print(node);
});

Events

Note that in the following example we are hidding the query function from the dart:html library to prevent collisions.

import 'dart:html' hide query;
import 'package:domnode/core.dart';

void main() {
  var listener = (e) {
    print('A ${e.type} event has been fired');
  };

  query('#id')
    // attaches an event listener
    ..on('click', listener)
    // fires an event
    ..trigger('click')
    // removes an event listener
    ..off('click', listener);
}

Attributes

var node = query('#id');

// gets an attribute
print(node.attr['href']);

// sets an attribute
node.attr['title'] = 'New title';

// does the attribute exist?
assert(node.attr['id'] == null);

// removes an attribute
node.attr.remove('id');

CSS attributes

var node = query('#id');

// gets a CSS attribute
print(query('h1').css['background-color']);

// sets a CSS attribute
node.css['background-color'] = 'yellow';

// does a CSS attribute exist?
assert(node.css['background-color'] != null);

// removes a CSS attribute
node.css.remove('background-color');

CSS classes

var node = query('#id');

// adds a class
node.addClass('class1');

// removes a class
node.removeClass('class1');

// does the class exist?
assert(node.hasClass('class1'));

// adds or removes a class
node.toggleClass('class1');

Inner contents

var body = query('body');
var node = query('#id');

// appends a new element
body.append('<p>New paragraph</p>');

// prepends a new element
body.prepend('<p>New paragraph at the beginning</p>');

// gets the inner text of a single element
print(node.text);

// changes the inner text of a single element
node.text = 'New title';

// gets the inner html of a single element
print(node.html);

// sets the inner html of a single element
node.html = 'This is text is <em>italic</em>';

// removes all childnodes of an element
node.empty();

Metrics

DomNode node = query('.myDiv');

// sets node size
node
  ..width = 640
  ..height = 480;
print('width: ${node.width}, height: ${node.height}');

// border size
print('border width ${node.borderWidth}, ' +
    'border height: ${node.borderHeight}');

// padding size
print('padding width ${node.paddingWidth}, ' +
    'padding height: ${node.paddingHeight}');

// margin size
print('margin width ${node.marginWidth}, ' +
    'margin height: ${node.marginHeight}');

Saving arbitrary data

var node = query('#id');

// sets arbitrary data to an element
node.data['test'] = {'one': 1, 'two': 2, 'three': 3};

// gets data from an element
print(node.data['test']);

Creating instances from a given source

You can use the $ function to create instances from different sources.

// creates an instance from a string
var node1 =
    $('<root><item id="1" /><item id="2" /><item id="3" /></root>');
print(node1);

// creates an instance from a document
var node2 = $(document);
print(node2);

// creates an instance from a DOM element
var element = document.querySelector('h1');
DomNode node3 = $(element);
print(node3);

Creating nodes from scratch

Note the intensive use of the $ function.

// creates a span and appends it to the body
query('body').append($('<span />')
  ..attr['id'] = 'span_id'
  ..attr['title'] = 'Span title'
  ..text = 'Some text here');

// creates a complex node
var node = $('<root />', (target) {
  // apends a new node with childNodes
  target.append($('<user />', (DomNode target) {
    target.append($('<first-name />')..text = 'James');
    target.append($('<last-name />')..text = 'Bond');
    target.append($('<age />')..text = 158);
    target
        .append($('<bio />')..html = 'My name is Bond, <em>James Bond</em>');
  }));

  // appends three subitems
  for (var i = 0; i < 3; i++) {
    target.append($('<item />')
      ..attr['id'] = 'item_${i}'
      ..attr['title'] = 'Item ${i}');
  }

  // prepends raw content
  target.prepend('<summary>Look at my horse, my horse is amazing</summary>');
});
print(node);