universal_html 1.0.13

Cross-platform 'dart:html'. Works in browser, server-side, and Flutter.

Introduction

Cross-platform dart:html that works in browser, Flutter, Dart VM, and Node.JS.

The project is licensed under the MIT license.

Issues?

• Have a bug report or feature request? Go to Github issue tracker.
• Have a fix? Just create a pull request.
• API documentation can be found here.

Similar projects

• universal_io (cross-platform dart:io)
• jsdom (DOM implementation in Javascript).

Getting started

1. Add dependency

In pubspec.yaml:

dependencies:
  universal_html: ^1.0.13

Now you can replace usage of "dart:html" with "package:universal_html/html.dart".

2. Choose library

Option 1

import 'package:universal_html/html.dart';

This library exports our implementation by default. The library exports dart:html only in browsers.

Getting warnings? In some cases, when you mix universal_io classes with dart:html classes, your IDE produces type warnings ("universal_html Element is not dart:html Element"). Your application should still compile (in Dart2js, universal_html classes will be dart:html classes). You can eliminate these warnings by using Option 2 (below).

Option 2

import 'package:universal_html/browser/html.dart';

This library exports dart:html by default. The library exports our implementation only when dart:io is available.

If you use this library, your package will not compile in Node.JS. Dart tools may also mistakenly think that your package is not compatible with VM/Flutter.

3. That's it!

import "package:universal_html/html.dart";

void main() {
  // Create a DOM tree
  final divElement = new DivElement();
  divElement.append(new Element.tag("h1")
    ..classes.add("greeting")
    ..appendText("Hello world!"));

  // Print outer HTML
  print(divElement.outerHtml);
  // --> <div><h1>Hello world</h1></div>

  // Do a CSS query
  print(divElement.querySelector("div > .greeting").text);
  // --> Hello world
}

Manual

Server-side rendering

import 'package:universal_html/driver.dart';
import 'package:universal_html/html.dart';

void main() {
  final renderer = new ServerSideRenderer(webAppMain);
  renderer.bind("localhost", 12345);
}

void webAppMain() {
  document.body.appendText("Hello world!");
}

Creating and using browser simulators

import 'package:universal_html/driver.dart';
import 'package:universal_html/html.dart';

Future main() async {
  // Construct a driver
  final driver = new HtmlDriver(userAgent:"My Hacker News bot");
  
  // Load a document.
  await driver.setDocumentFromUri(Uri.parse("https://news.ycombinator.com/"));
  
  // Select top story
  final topStoryTitle = driver.document.querySelectorAll(".athing > .title").first.text;
  print("Top Hacker News story is: ${topStoryTitle}");
}

Implemented APIs

Principles

• Our goal is that the implemented APIs behave identically to dart:html code running in Chrome.
• Non-implemented APIs either throw UnimplementedError or fail silently.
• We accept pull requests for more API implementations!

An incomplete list

• Document nodes
  • All the core classes (Node, Element, etc.)
  • Much of the element subclasses (CheckboxInputElement, ResetButtonElement, etc.)
  • Much of the CSS classes (CssStyleDeclaration, etc.)
• DOM parsing
  • innerHtml/outerHtml setters
  • DomParser
  • HTML parsing uses package:html and package:csslib
  • XML parsing uses package:xml
• DOM printing
  • element.innerHtml
  • element.outerHtml
• DOM events
  • For example, element.onClick.listen(...) would receive invocation of element.click().
• CSS selectors
  • Methods element.querySelector(..), element.querySelectorAll(..), element.matchesSelector(..)
  • Element name (table)
  • Element ID (#id)
  • Element class (.classA.classB)
  • Combinators:
    • element.class#id
    • s0 s1 s2
    • s0 s1 s2
    • s0 > s1 > s2
    • s0 ~ s1 ~ s2
    • s0 + s1 + s2
  • Pseudoselectors:
    • :disabled
    • :first-child
    • :last-child
    • :not(x)
    • :nth-child(5)
    • :nth-child(even)
    • :nth-child(3n+1)
    • :only-child
    • :root
  • Attribute selectors:
    • [name]
    • [name=value]
    • [name~=value]
    • [name|=value]
    • [name^=value]
    • [name$=value]
    • [name*=value]
• Navigator
  • locale, userAgent, etc.
• Window
  • console
  • history
    • back(...), pushState(...), etc.
  • location
    • origin, href, etc.
  • localStorage / sessionStorage
    • Stores values in the heap.
• HttpRequest
  • Does not implement same-origin security policies that browsers have.
• EventSource
  • Supports the full specification ('data', 'type', 'id', 'retry', comments, 'Last-Event-ID')
• Related libraries (dart:js, dart:svg, etc.).
  • Just API declarations. Any attempt to use APIs will throw UnimplementedException.
  • Available in:
    • "package:universal_html/indexed_db.dart"
    • "package:universal_html/js.dart"
    • "package:universal_html/js_util.dart"
    • "package:universal_html/svg.dart"