edge -> 0.8 docs

Author: evs-chris

Gruntfile.js

@@ -11,7 +11,7 @@ module.exports = function ( grunt ) {
 
 	config = {
 		pkg: grunt.file.readJSON( 'package.json' ),
-		latest: '0.7',
+		latest: '0.8',
 		edge: 'edge',
 		prod: grunt.option( 'prod' ),
 

docs/0.8/Adaptors.md.hbs

@@ -0,0 +1,52 @@
+---
+title: Adaptors
+---
+
+Adaptors are a way of teaching Ractive to communicate seamlessly with other libraries such as Backbone. This means that you can, for example, have some or all of your app's data handled by Backbone - including fetching from and saving to your server, validation, sorting, filtering and so on - but still build a reactive user interface using Ractive, without having to create custom View classes or adding a whole load of event binding code.
+
+It's probably easier to show, rather than tell: [this example application](http://examples.ractivejs.org/backbone) uses Backbone models describing all the James Bond films. The [code for the Backbone adaptor is here](https://github.com/ractivejs/ractive-adaptors-backbone).
+
+
+Using adaptors
+--------------
+
+Add the adaptor code to your app. Using the Backbone adaptor as an example:
+
+```html
+<script src='lib/underscore.js'></script> <!-- Backbone dependency -->
+<script src='lib/backbone.js'></script>
+<script src='lib/ractive.js'></script>
+
+<!-- the adaptor -->
+<script src='lib/adaptors/ractive-adaptors-backbone.js'></script>
+```
+
+If you're using module loaders, beware - the adaptor needs access to both `ractive` and `backbone`. You may need to change your paths config (or equivalent), or modify the adaptor source code to fit your app.
+
+Unlike components or other registries where there is a template-level directive that informs Ractive that plugin is to be used, adaptors are a data-level construct and so you use the `adapt` option to tell Ractive which adaptors are to be used with that instance. If you define the adaptors directly on the instance or component, you do not need to specify them in the `adapt` option.
+
+For our example, when you create a new Ractive instance, you can specify which adaptors to use like so:
+
+```js
+ractive = new Ractive({
+  el: container,
+  template: myTemplate,
+  data: myBackboneModel,
+  adapt: [ 'Backbone' ]
+});
+```
+
+Ractive will then see if there's a `Backbone` property of `Ractive.adaptors`. (If not, an error will be thrown.) Alternatively, you can pass in the adaptor itself rather than the name, e.g.
+
+```js
+ractive = new Ractive({
+  el: container,
+  template: myTemplate,
+  data: myBackboneModel,
+  adapt: [ Ractive.adaptors.Backbone ]
+});
+```
+
+## Creating adaptor plugins
+
+See {{{createLink 'Writing adaptor plugins'}}} to learn how to create your own adaptors.

docs/0.8/Advanced configuration.md.hbs

@@ -0,0 +1,212 @@
+---
+title: Advanced Configuration
+---
+In addition to supplying static values for configurations options, some of the Ractive options
+can be specified using a function that will resolve when the ractive instance is instantiated,
+and re-evaluated upon {{{createLink 'ractive.reset()'}}}.
+
+An option function may be supplied to either {{{createLink 'Ractive.extend()'}}} or {{{createLink 'new Ractive()'}}}.
+
+Option functions receive the post-configured `data` option as the first argument and `this` in
+the function refers to the ractive instance being instantiated.
+Bear in mind that the ractive instance is in the process of being configured, so not all options
+are necessarily configured yet, and functional methods like `observe` or `set` should not be called.
+
+## Template
+
+The template can be specified using the return value of an option function:
+
+```js
+new Ractive({
+	template: function ( data ) {
+		return data.foo ? '<p>hello world</p>' : '<div>yes, we have no foo</div>';
+	},
+	data: { foo: true }
+});
+```
+The return value can be any of the valid template options: a preparsed template,
+a string that will parsed as a template, or an string starting with `#` that refers to an element id from which
+the template should be retrieved.
+
+In general, these should be sufficient for most use cases. However, if you need to dissect templates or extract
+partials dynamically, the template option function also receives a second argument
+with a helper parser object `p` that offers the following methods:
+
+> ### p.fromId( id )
+> Retrieves the template from the DOM `<script>` tag specified by `id`. Leading `#` is optional. Make sure to set `type='text/ractive'` on the `<script>` tag or the browser will try and execute the contents as javascript and you'll get an exception.
+
+> ### p.isParsed( template )
+> Test whether the supplied instance has already been parsed
+
+> ### p.parse( template [, parseOptions ] )
+> Parses the template via {{{createLink 'Ractive.parse()' }}}. If no `parseOptions` specified, defaults to those
+> of the current instance. Full Ractive runtime must be loaded.
+
+During a {{{createLink 'ractive.reset()' }}} operation, an option function for a template will be re-evaluated
+and _if_ the return value changes the ractive instance will be re-rendered.
+
+## Partials
+
+The value for a named partial can also be specified using a function:
+
+```js
+new Ractive({
+	template: '<div>\{{>dynamicPartial}}</div>',
+	partials: {
+		dynamicPartial: function ( data ) {
+			return data.condition ? '<p>hello world</p>' : '<div>yes, we have no foo</div>';
+		}
+	}
+});
+```
+
+Partial option functions also received the helper parser `p` as the second argument. This is useful in
+partials as you cannot return an element id from a partial function and must use `p.fromId` to return
+the template content of an element.
+
+Partial functions also cannot directly return the string token of a registered partial. Instead,
+return the value from the ractive instance:
+
+```js
+	partials: {
+		dynamicPartial: function ( data ) {
+			// assuming data.partial is the string token of a registered partial:
+			return this.partials[data.partial];
+		}
+	}
+```
+
+## Components
+
+A component value can be specified using an option function. The return value can either be
+a component or (unlike partials) the string token of a registered component:
+
+```js
+Ractive.components.view1 = Ractive.extend({...});
+Ractive.components.view2 = Ractive.extend({...});
+
+new Ractive({
+	template: '<div><dynamicComponent/></div>',
+	components: {
+		dynamicComponent: function ( data ) {
+			return data.foo ? 'view1' : 'view2';
+		}
+	}
+});
+```
+
+## Data
+
+The data option function can either return a value or use the prototype inheritance chain to construct the
+data object. Use `this._super` to call the parent data option. Ractive will handle integrating
+static data options and data option functions. If a return value is specified, further parent data options
+will not be considered.
+
+```js
+
+var Component1 = Ractive.extend({
+    data: {
+	    formatTitle: function (title) {
+		    return '"' + title.toUpperCase() + '"';
+		}
+	}
+});
+
+var Component2 = Component1.extend({
+    data: function( data ) {
+	    this._super( data );
+	    data.scale = 5;
+	}
+});
+
+var ractive = new Component2({
+    data: { foo: 'bar' }
+})
+
+// r.data: { foo: "bar", formatTitle: function, scale: 5 }
+
+```
+
+The data object instance passed to the instantiated ractive instance will always be retained as
+the `ractive.data` instance, _unless_ a return value is specified from an option function in which
+ case that return value instance will be used as `ractive.data`
+
+### Copying Parent Data
+
+Because parent data is common to all instances, you can use an option function to return a
+unique copy of the data.
+
+```js
+
+var Shared = Ractive.extend({
+	data: {
+		foo: { bar: 42 }
+	}
+});
+
+var shared1 = new Shared();
+var shared2 = new Shared();
+shared1.set( 'foo.bar', 12 );
+shared2.get( 'foo.bar' ); // returns 12
+
+
+var NotShared = Ractive.extend({
+	data: function () {
+		return {
+			foo: { bar: 42 }
+		};
+	}
+});
+
+var notShared1 = new NotShared();
+var notShared2 = new NotShared();
+notShared1.set( 'foo.bar', 12 );
+notShared2.get( 'foo.bar' ); // returns 42
+
+```
+
+### Asynchronous Data
+
+A data option function can be a handy way to fetch asynchronous data _and_ supply initial synchronous values:
+
+```js
+data: function () {
+
+	$.get( 'somedata.url', function( data ) {
+		this.set( '', data );
+	}.bind(this) );
+
+	return {
+		foo: 'default'
+	};
+}
+```
+
+### Specifying a Model
+
+Another use of the data option function is to provide a model:
+
+```js
+data: function ( data ) {
+	return new Model( data );
+}
+```
+
+If you use a constructor guard clause (currently popular for `new`-less use of javascript constructors),
+you can directly supply the model:
+
+
+```js
+function Model ( data ) {
+	if ( !( this instanceof Model) ) { return new Model( data ); }
+	// model setup
+}
+
+var MyComponent = Ractive.extend({
+    data: Model
+});
+
+var r = new MyComponent({
+    data: { foo: 'bar' }
+})
+```

docs/0.8/Array modification.md.hbs

@@ -0,0 +1,69 @@
+---
+title: Array modification
+---
+Ractive can intercept the *mutator methods* (`pop`, `push`, `shift`, `unshift`, `splice`, `sort` and `reverse`) of arrays that it [depends on](dependants) for more convenient data binding.
+
+Consider the following:
+
+```html
+<ul>
+  \{{#list}}
+    <li>\{{this}}</li>
+  \{{/list}}
+</ul>
+```
+
+```js
+list = [ 'a', 'b', 'c' ];
+
+ractive = new Ractive({
+  el: myContainer,
+  template: myTemplate,
+  data: { list: list }
+});
+
+list.push( 'd' ); // adds a new list item - <li>d</li>
+```
+
+You can enable this behaviour by passing in `modifyArrays: true` as an {{{createLink 'options' 'initialisation options'}}}
+
+
+## How it works
+
+Don't worry, we're not modifying `Array.prototype`. (What do you think this is, [Ember](http://emberjs.com/guides/configuring-ember/disabling-prototype-extensions/)? :-)
+
+Instead, we're using a technique called [prototype chain injection](http://perfectionkills.com/how-ecmascript-5-still-does-not-allow-to-subclass-an-array/#wrappers_prototype_chain_injection), which allows us to remain performant and memory-efficient without mucking about extending native objects.
+
+This uses the non-standard (but very unlikely to disappear!) `__proto__` property. That might seem kludgy, but if [Mike Bostock thinks it's okay](http://bost.ocks.org/mike/selection/#subclass) then that's good enough for us.
+
+Older browsers (I'm looking at you, IE8) don't support `__proto__` - in these cases, we simply add the wrapped methods as properties of the array itself.
+
+As well as intercepting or wrapping the mutator methods, Ractive adds a (non-enumerable, in modern browsers) `_ractive` property to arrays, which contains information about which Ractive instances depend on the array, and which keypaths it is assigned to.
+
+
+## Hygiene
+
+When an array is no longer depended on by any Ractive instances, we can revert it to its normal state - resetting its prototype (if we used prototype chain injection) or deleting the wrapped methods (if we're in a crap browser), and removing the `_ractive` property.
+
+
+## Performance and UI benefits
+
+As well as convenience, using arrays like this helps Ractive make smart decisions about how to update the DOM. Continuing the example above, compare these two alternative methods of inserting a new item at the *start* of our list:
+
+```js
+// at the moment, list = [ 'a', 'b', 'c', 'd' ]
+
+// 1. Reset the list:
+ractive.set( 'list', [ 'z', 'a', 'b', 'c', 'd' ] )
+
+// 2. Use `unshift`:
+list.unshift( 'z' );
+```
+
+In the first example, Ractive will see that the content of the first list item has changed from `'a'` to `'z'`, and that the second has changed from `'b'` to `'a'`, and so on, and update the DOM accordingly. It will also see that there is now a fifth item, so will append `<li>d</li>` to the list.
+
+In the second example, Ractive will understand that all it needs to do is insert `<li>z</li>` at the start of the list, leaving everything else untouched.
+
+This is particularly important if you're using {{{createLink 'transitions'}}}, as it will be obvious to the user which elements are being added and removed.
+
+Note that if `list.unshift('z')` isn't an option, you could use {{{createLink 'ractive.merge()'}}} to achieve the same effect.

docs/0.8/CSP.md.hbs

@@ -0,0 +1,8 @@
+---
+title: Content Security Policy
+---
+
+To use ractive with [Content Security Policy](http://www.html5rocks.com/en/tutorials/security/content-security-policy/), you'll currently need `'unsafe-eval'` specified for `scriptSrc` in your CSP header.
+
+This may change in future - see https://github.com/ractivejs/ractive/issues/1897 .
+