From 85f4d540c71a2e56a19c8646a980b42311cd99d4 Mon Sep 17 00:00:00 2001 From: Tim Branyen Date: Wed, 22 Jun 2016 22:40:05 -0700 Subject: [PATCH] Update the README --- README.md | 148 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 101 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 27d73c84..c4c66946 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,30 @@ -diffHTML: A JavaScript View Layer ---------------------------------- +#
<±/> diffHTML
-Latest stable version: 0.9.1 +*A powerful JavaScript library for building user interfaces.* [![Build Status](https://travis-ci.org/tbranyen/diffhtml.svg?branch=master)](https://travis-ci.org/tbranyen/diffhtml) [![Coverage Status](https://coveralls.io/repos/tbranyen/diffhtml/badge.svg?branch=master&service=github)](https://coveralls.io/github/tbranyen/diffhtml?branch=master) [![Join the chat at https://gitter.im/tbranyen/diffhtml](https://img.shields.io/badge/GITTER-join%20chat-green.svg)](https://gitter.im/tbranyen/diffhtml) -Inspired by React and motivated by the Web, this is a lowish-level tool which -aims to help web developers write components for the web. By focusing on the -markup representing how your application state should look, diffHTML will -figure out how to modify the page with a minimal amount of operations. This -tool is designed and optimized around HTML and standards features within -JavaScript. +Stable version: 0.9.1 -It works by parsing your HTML markup into a lightweight JSON-serializable -Virtual DOM heirarchy. I refer to these as Virtual Trees or *VTree*. These -element (and attribute) objects are pooled to provide consistent memory -management and garbage collection. diffHTML maintains a single VTree root that -mirrors a mounted element in the DOM, it reconciles all future renders into -this tree and the DOM. +Inspired by React and motivated by the Web, this is a library designed to help +web developers write components for the web. By focusing on the markup +representing how your application state should look, diffHTML will figure out +how to modify the page with a minimal amount of operations. This tool is +designed and optimized around HTML and standard features within JavaScript. -#### Features +## Quick Jump + +- [Features](#features) +- [Install](#install) +- [Quick start](#quick-start) +- [API](#API) + +## Features + +[Back to quick jump...](#quick-jump) - Helps you build components using HTML and JavaScript - [Provides a tagged template @@ -32,30 +34,59 @@ this tree and the DOM. - Object pooling to avoid GC thrashing and expensive childNode/attribute/uuid generation -### Install +#### Browser support + +## Install -The latest built version is available for quick download from the [master +[Back to quick jump...](#quick-jump) + +The latest built version (but not necessarily the latest stable) is available +for quick download from the [master branch](https://raw.githubusercontent.com/tbranyen/diffhtml/master/dist/diffhtml.js). +Use this to test the bleeding edge. Or you can use npm: ``` sh -npm install diffhtml +npm install diffhtml --save ``` The module can be required via Node or browser environments. It is exported as -a global named `diff` unless loaded as a module. +a global named `diff` unless loaded as a module, in which case you determine +the name. + +In the browser: + +``` html + + +``` -You can import only what you need if you're using ES6 modules with a -transpiler: +With CommonJS you can import the entire module: ``` javascript -import { innerHTML } from 'diffhtml'; +const diff = require('diffhtml'); +diff.innerHTML(document.body, 'Hello world!'); +``` + +You can import only what you need if you're using ES Modules: +``` javascript +import { innerHTML } from 'diffhtml'; innerHTML(document.body, 'Hello world!'); ``` -##### Polyfills +#### Module format locations + +This library is authored in vanilla ES2015 with no experimental syntax enabled, the syntax is ES Modules and is transpiled to CJS with Babel. The UMD build is generated by browserify. + +| Format | Location +| ------------------------ | --------------------------- +| UMD (AMD/CJS/Browser) | `diffhtml/dist/diffhtml.js` +| CJS | `diffhtml/dist/cjs/*` +| ES6 | `diffhtml/lib/*` + +#### Supporting legacy browsers diffHTML is authored using many modern browser features, such as [Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set), @@ -67,16 +98,9 @@ polyfill loaded first: https://babeljs.io/docs/usage/polyfill/ -##### Module format locations - -The codebase is authored with JavaScript (ES6 enhancements) and transpiled into -ES5 (CJS) into the `dist/cjs` folder on every NPM publish. If you want -to reference the ES5 files, point your entry to `diffhtml/dist/cjs`. If you -want ES6, point to `diffhtml/lib`. If you want the UMD build you can simply -point to `diffhtml` as it is the default or reference `dist/diffhtml.js` in -your browser. +## Quick start -### Quick start +[Back to quick jump](#quick-jump) Before diving into all the API details, the easiest way to understand using diffHTML is to replace the usage of `innerHTML`. @@ -111,7 +135,7 @@ function render(string) { } ``` -### API +## API The exposed API provides the following methods: @@ -129,14 +153,14 @@ The follow error types are exposed so you can test exceptions: - TransitionStateError - Happens when errors occur during transitions. - DOMException - Happens whenever a DOM manipulation fails. -##### Options +#### Options This is an optional argument that can be passed to any diff method. The `inner` property can only be used with the element method. - `inner` - Boolean that determines if `innerHTML` is used. -##### Diff an element with markup +### Diff an element with markup This method will take in a string of markup that matches the element root you are diffing against. This allows you to change attributes and text on the @@ -149,7 +173,7 @@ You cannot override the `inner` options property here. diff.outerHTML(document.body, '

Hello world!

'); ``` -##### Diff an element's children with markup +### Diff an element's children with markup This method also takes in a string of markup, but unlike `outerHTML` this is children-only markup that will be nested inside the element passed. @@ -161,7 +185,7 @@ You cannot override the `inner` options property here. diff.innerHTML(document.body, '

Hello world!

'); ``` -##### Diff an element to another element +### Diff an element to another element Unlike the previous two methods, this will take in two elements and diff them together. @@ -188,7 +212,7 @@ h1.innerHTML = 'Hello world!'; diff.element(document.body, h1, { inner: true }); ``` -##### Release element +### Release element Use this method if you need to clean up memory allocations and anything else internal to diffHTML associated with your element. This is very useful for unit @@ -203,7 +227,7 @@ diff.element(document.body, h1, { inner: true }); diff.release(document.body); ``` -##### Add a transition state callback +### Add a transition state callback Adds a global transition listener. With many elements this could be an expensive operation, so try to limit the amount of listeners added if you're @@ -245,7 +269,7 @@ Format is: `name[callbackArgs]` - `textChanged[element, oldValue, newValue]` For when text has changed in either TextNodes or SVG text elements. -##### A note about detached/replaced element accuracy +### A note about detached/replaced element accuracy When rendering Nodes that contain lists of identical elements, you may not receive the elements you expect in the detached and replaced transition state @@ -307,7 +331,7 @@ Now the transformative operations are: 1. Remove the second element -##### Remove a transition state callback +### Remove a transition state callback Removes a global transition listener. @@ -326,7 +350,7 @@ diff.removeTransitionState('attached'); diff.removeTransitionState('attached', callbackReference); ``` -#### HTML +### HTML You can use the `diff.html` tagged template helper to build up dynamic trees in a way that looks very similar to JSX. @@ -385,7 +409,7 @@ diff.outerHtml(fixture, html` `); ``` -#### [Prollyfill](https://twitter.com/slexaxton/status/257543702124306432) +### [Prollyfill](https://twitter.com/slexaxton/status/257543702124306432) *Click above to learn what prollyfill "means".* @@ -410,7 +434,7 @@ Scans for changes in attributes and text on the parent, and all child nodes. document.querySelector('main').diffOuterHTML = ''; ``` -##### `Element.prototype.diffInnerHTML` +### `Element.prototype.diffInnerHTML` Only scans for changes in child nodes. @@ -418,7 +442,7 @@ Only scans for changes in child nodes. document.querySelector('main').diffInnerHTML = ''; ``` -##### `Element.prototype.diffElement` +### `Element.prototype.diffElement` Compares the two elements for changes like `outerHTML`, if you pass `{ inner: true }` as the second argument it will act like `innerHTML`. @@ -430,7 +454,7 @@ newElement.innerHTML = '
'; document.querySelector('main').diffElement(newElement); ``` -##### `Element.prototype.diffRelease` +### `Element.prototype.diffRelease` Cleans up after diffHTML and removes the associated worker. @@ -441,4 +465,34 @@ newElement.innerHTML = '
'; document.querySelector('main').diffRelease(newElement); ``` +<<<<<<< Updated upstream +======= +### Middleware + +A controlled way of exposing the internals of diffHTML to external tooling and +has a very simple interface for creating and consuming. + +Two interesting projects that illustrate use cases for middleware: + +- [Logger](https://github.com/tbranyen/diffhtml-logger) +- [Components](https://github.com/tbranyen/diffhtml-components) + +### Consuming + +Very simple, use the `use` method. + +``` javascript +import logger from 'diffhtml-logger'; +import { use } from 'diffhtml'; + +use(logger); +``` + +### Create + +``` javascript +const logMiddleware = ( +``` + +>>>>>>> Stashed changes [More information and a demo are available on http://www.diffhtml.org/](http://www.diffhtml.org/)