<commit_before># Tungsten.js

Tungsten.js is a modular framework for creating web UIs with high-performance rendering on both server and client.

## What Tungsten.js Provides

* High-performance virtual DOM updates powered by [virtual-dom](https://github.com/Matt-Esch/virtual-dom)
* Mustache templates, parsed with [Ractive.js](https://github.com/ractivejs/ractive), which render to virtual DOM objects
* Event system which binds and delegates each event type to the document root
* Adaptor for [Backbone.js](https://github.com/jashkenas/backbone) or [Ampersand.js](https://github.com/ampersandjs) views

## Motivation

Tungsten.js was built as an alternative to existing front-end JavaScript libraries because we needed a library with:

* Fast, first-class server-side rendering across multiple platforms
* Fast client-side DOM updates with support back to IE8
* Modular interfaces to swap out library components as necessary

## How Tungsten.js Works

In Tungsten.js, the initial page loaded is rendered with [Mustache](http://mustache.github.io/) templates on the server (in, say, [C++](https://github.com/mrtazz/plustache), [PHP](https://github.com/bobthecow/mustache.php), or [Go](https://github.com/hoisie/mustache)) then rehydrated by Tungsten.js on the client.  Subsequent DOM updates are made with those same mustache templates which have been [pre-compiled](precompile/tungsten_template/index.js) to functions which return virtual DOM objects used by [virtual-dom](https://github.com/Matt-Esch/virtual-dom) to diff and patch the existing DOM.

An adaptor layer is used to connect with Tungsten.js with a preferred modular client-side framework to handle data and view management.  The default adaptor is a thin layer on top of [Backbone.js](https://github.com/jashkenas/backbone) with a `childViews` hash to define relationships between views and a `compiledTemplate` property to define the root pre-compiled template function.  There is also a similar Ampersand.js adaptor available.

Tungsten.js has no hard dependency on [jQuery](https://github.com/jquery/jquery), and uses the jQuery-less [backbone.native](https://github.com/inkling/backbone.native) in its Backbone adaptor.

Tungsten.js is ~15kb packed and gzipped. Bundled with Backbone and the adaptor, it's ~25kb packed and gzipped.

## Backbone.js Adaptor

Tungsten.js is pre-packaged with an adaptor for using Backbone.js.  This adaptor is can be included via CommonJS or ES6 Modules at `tungstenjs/adaptors/backbone/index.js` and exposes base modules for Backbone (as well as a direct reference to Backbone itself).

`View`, `Model`, and `Collection` are drop-in replacements for `Backbone.View`, `Backbone.Model`, and `Backbone.Collection` constructor functions.  They can be extended as usual to create custom constructors.

The Backbone.js adaptor includes a forked version of [backbone-nested-models](https://github.com/blittle/backbone-nested-models).

## Usage

### Install

``` npm install tungstenjs --save```

For the latest, but unstable, version:

``` npm install git+http://github.com:wayfair/tungstenjs.git#master --save```

### Bundler

Using a module bundler such as [webpack](http://webpack.github.io/) is recommend.  Tungsten.js with the Backbone or Ampersand adaptor expects `jquery` to be shimmed, either with jQuery itself or with the jQuery-less shim [backbone.native](https://github.com/inkling/backbone.native).  With webpack, this looks like:

    module.exports = {
      // [...]
      resolve: {
        alias: {
          'jquery': 'backbone.native'
        }
      }
    };

See [examples](https://github.com/wayfair/tungstenjs/tree/master/examples) for more details.

### Requirements

* `Node.js` (for builds; not necessary for production runtime)
* `webpack` or other CommonJS compatible client-side module loader
* [{{ mustache }}](http://mustache.github.io/) renderer on server (for server-side rendering)

### Including an Adaptor

The Backbone.js adaptor can be included by requiring `tungstenjs/adaptors/backbone` after installing the `tungstenjs` Node module.  Similarly, the Ampersand.js adaptor can be included by requiring `tungstenjs/adaptors/ampersand`.  Each of these adaptors provide a `view`, `model`, and `collection` property which should be used as the base view, model, and collection constructors in the application.  As usual with Backbone and Ampersand, custom constructors can extend from each of these.

###  Getting Started

When using the Backbone or Ampersand adaptor, we recommend starting with an app model, app view, and app ([mustache](https://mustache.github.io/)) template.  These are the entry points for a Tungsten.js applications.  A place to bootstrap the app and get everything started is also needed: often this is in the form of an init file:
 
    var AppView = require('./views/app_view');
    var AppModel = require('./models/app_model');
    var template = require('../templates/app_view.mustache');
    
    module.exports = new AppView({
      el: '#app',
      template: template,
      model: new AppModel(window.data)
    });
    
Each template and partial should be pre-compiled with the provided wrapper for the [Ractive](http://www.ractivejs.org/)-based precompiler.  A [webpack](http://webpack.github.io/) loader, `tungsten_template`, is provided for this purpose, and can be included like so in the `webpack.config.js`:

    module.exports = {
      // [...]
      resolveLoader: {
        modulesDirectories: ['node_modules', 'node_modules/tungstenjs/precompile']
      },
      module: {
        loaders: [
          { test: /\.mustache$/, loader: 'tungsten_template' }
        ]
      }
    }
<commit_msg>Add json loader to example in readme<commit_after># Tungsten.js

Tungsten.js is a modular framework for creating web UIs with high-performance rendering on both server and client.

## What Tungsten.js Provides

* High-performance virtual DOM updates powered by [virtual-dom](https://github.com/Matt-Esch/virtual-dom)
* Mustache templates, parsed with [Ractive.js](https://github.com/ractivejs/ractive), which render to virtual DOM objects
* Event system which binds and delegates each event type to the document root
* Adaptor for [Backbone.js](https://github.com/jashkenas/backbone) or [Ampersand.js](https://github.com/ampersandjs) views

## Motivation

Tungsten.js was built as an alternative to existing front-end JavaScript libraries because we needed a library with:

* Fast, first-class server-side rendering across multiple platforms
* Fast client-side DOM updates with support back to IE8
* Modular interfaces to swap out library components as necessary

## How Tungsten.js Works

In Tungsten.js, the initial page loaded is rendered with [Mustache](http://mustache.github.io/) templates on the server (in, say, [C++](https://github.com/mrtazz/plustache), [PHP](https://github.com/bobthecow/mustache.php), or [Go](https://github.com/hoisie/mustache)) then rehydrated by Tungsten.js on the client.  Subsequent DOM updates are made with those same mustache templates which have been [pre-compiled](precompile/tungsten_template/index.js) to functions which return virtual DOM objects used by [virtual-dom](https://github.com/Matt-Esch/virtual-dom) to diff and patch the existing DOM.

An adaptor layer is used to connect with Tungsten.js with a preferred modular client-side framework to handle data and view management.  The default adaptor is a thin layer on top of [Backbone.js](https://github.com/jashkenas/backbone) with a `childViews` hash to define relationships between views and a `compiledTemplate` property to define the root pre-compiled template function.  There is also a similar Ampersand.js adaptor available.

Tungsten.js has no hard dependency on [jQuery](https://github.com/jquery/jquery), and uses the jQuery-less [backbone.native](https://github.com/inkling/backbone.native) in its Backbone adaptor.

Tungsten.js is ~15kb packed and gzipped. Bundled with Backbone and the adaptor, it's ~25kb packed and gzipped.

## Backbone.js Adaptor

Tungsten.js is pre-packaged with an adaptor for using Backbone.js.  This adaptor is can be included via CommonJS or ES6 Modules at `tungstenjs/adaptors/backbone/index.js` and exposes base modules for Backbone (as well as a direct reference to Backbone itself).

`View`, `Model`, and `Collection` are drop-in replacements for `Backbone.View`, `Backbone.Model`, and `Backbone.Collection` constructor functions.  They can be extended as usual to create custom constructors.

The Backbone.js adaptor includes a forked version of [backbone-nested-models](https://github.com/blittle/backbone-nested-models).

## Usage

### Install

``` npm install tungstenjs --save```

For the latest, but unstable, version:

``` npm install git+http://github.com:wayfair/tungstenjs.git#master --save```

### Bundler

Using a module bundler such as [webpack](http://webpack.github.io/) is recommend.  Tungsten.js with the Backbone or Ampersand adaptor expects `jquery` to be shimmed, either with jQuery itself or with the jQuery-less shim [backbone.native](https://github.com/inkling/backbone.native).  With webpack, this looks like:

    module.exports = {
      // [...]
      resolve: {
        alias: {
          'jquery': 'backbone.native'
        }
      }
    };

See [examples](https://github.com/wayfair/tungstenjs/tree/master/examples) for more details.

### Requirements

* `Node.js` (for builds; not necessary for production runtime)
* `webpack` or other CommonJS compatible client-side module loader
* [{{ mustache }}](http://mustache.github.io/) renderer on server (for server-side rendering)

### Including an Adaptor

The Backbone.js adaptor can be included by requiring `tungstenjs/adaptors/backbone` after installing the `tungstenjs` Node module.  Similarly, the Ampersand.js adaptor can be included by requiring `tungstenjs/adaptors/ampersand`.  Each of these adaptors provide a `view`, `model`, and `collection` property which should be used as the base view, model, and collection constructors in the application.  As usual with Backbone and Ampersand, custom constructors can extend from each of these.

###  Getting Started

When using the Backbone or Ampersand adaptor, we recommend starting with an app model, app view, and app ([mustache](https://mustache.github.io/)) template.  These are the entry points for a Tungsten.js applications.  A place to bootstrap the app and get everything started is also needed: often this is in the form of an init file:
 
    var AppView = require('./views/app_view');
    var AppModel = require('./models/app_model');
    var template = require('../templates/app_view.mustache');
    
    module.exports = new AppView({
      el: '#app',
      template: template,
      model: new AppModel(window.data)
    });
    
Each template and partial should be pre-compiled with the provided wrapper for the [Ractive](http://www.ractivejs.org/)-based precompiler.  A [webpack](http://webpack.github.io/) loader, `tungsten_template`, is provided for this purpose, and can be included like so in the `webpack.config.js` (currently we also include a json-loader for the HTML tokenizer):

    module.exports = {
      // [...]
      resolveLoader: {
        modulesDirectories: ['node_modules', 'node_modules/tungstenjs/precompile']
      },
      module: {
        loaders: [
          { test: /\.mustache$/, loader: 'tungsten_template' },
          { test: /\.json$/, loader: 'json-loader' }
        ]
      }
    }

{'fraction_non_alphanumeric': 0.10188251699494509, 'fraction_numerical': 0.0010458427749694963, 'mean_word_length': 4.084182543198937, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 30, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1582477', 'n_tokens_mistral': 3314, 'n_tokens_neox': 3200, 'n_words': 1222}