Updates for edge, 0.8, and known issues

docs/0.7/Get started.md.hbs

@@ -4,7 +4,7 @@ title: Get started
 
 Welcome! These pages aim to provide all the information you need to master Ractive.
 
-If you see something wrong, out of date, or missing from this documentation, please [raise an issue on GitHub](https://github.com/ractivejs/docs.ractivejs.org/issues) or - even better - submit a pull request. Your fellow Ractive users will thank you!
+If you see something wrong, out of date, or missing from this documentation, please check out our {{{createLink 'Known issues, FAQs, and Tips' 'known issues and FAQs'}}}, [raise an issue on GitHub](https://github.com/ractivejs/docs.ractivejs.org/issues) or - even better - submit a pull request. Your fellow Ractive users will thank you!
 
 Using Ractive is very simple. An instance is created using `new Ractive({...})`
 with the desired options:

docs/edge/Tips.md.hbs → docs/0.7/Known issues, FAQs, and Tips.md.hbs

@@ -1,8 +1,22 @@
 ---
-title: Tips
+title: Known issues, FAQs, and Tips
 ---
-Using Ractive with...
----------------------
+
+## Known Issues
+
+### Memory and crashing issues with Safari on iOS 9
+
+It seems that Apple has introduced some memory management _feature_ with Safari in iOS 9 that causes large templates to crash Safari during parsing. Fortunately, this can be worked around by splitting your templates into smaller partials or, more efficiently, by pre-parsing your templates and serving them as a JS object. You can use {{{createLink 'Ractive.parse()'}}} to create the JS object as a build step or when the page is being served.
+
+Since there isn't _really_ any browser for iOS other than Safari, all browser on iOS 9 are affected by this issue. iOS 8 seems to remain unaffected.
+
+## FAQs
+
+__Coming Soon!™__
+
+## Tips
+
+### Using Ractive with...
 
 * {{{createLink 'using-ractive-with-backbone' '...Backbone'}}}
 * {{{createLink 'using-ractive-with-requirejs' '...RequireJS'}}}
@@ -12,8 +26,7 @@ Using Ractive with...
 * {{{createLink 'using-ractive-with-jquery-mobile' '...jQuery Mobile'}}}
 <!-- TODO * [...Underscore (and other utility libraries)](using-ractive-with-underscore) -->
 
-Building an app with Ractive
-----------------------------
+### Building an app with Ractive
 
 Ractive can take care of your UI, and for simple applications it can take care of your *application state* as well. But if you're building a complex app you'll likely have other things to worry about as well - routing and history management, fetching and saving data to and from a server, validating data, handling realtime communication, user authentication, and all the other fun stuff that goes into a web app.
 

docs/0.7/Tips.md.hbs

@@ -1,8 +1,22 @@
 ---
-title: Tips
+title: Known issues, FAQs, and Tips
 ---
-Using Ractive with...
----------------------
+
+## Known Issues
+
+### Memory and crashing issues with Safari on iOS 9
+
+It seems that Apple has introduced some memory management _feature_ with Safari in iOS 9 that causes large templates to crash Safari during parsing. Fortunately, this can be worked around by splitting your templates into smaller partials or, more efficiently, by pre-parsing your templates and serving them as a JS object. You can use {{{createLink 'Ractive.parse()'}}} to create the JS object as a build step or when the page is being served.
+
+iOS 8 seems to remain unaffected.
+
+## FAQs
+
+__Coming Soon!&tmp;__
+
+## Tips
+
+### Using Ractive with...
 
 * {{{createLink 'using-ractive-with-backbone' '...Backbone'}}}
 * {{{createLink 'using-ractive-with-requirejs' '...RequireJS'}}}
@@ -12,8 +26,7 @@ Using Ractive with...
 * {{{createLink 'using-ractive-with-jquery-mobile' '...jQuery Mobile'}}}
 <!-- TODO * [...Underscore (and other utility libraries)](using-ractive-with-underscore) -->
 
-Building an app with Ractive
-----------------------------
+### Building an app with Ractive
 
 Ractive can take care of your UI, and for simple applications it can take care of your *application state* as well. But if you're building a complex app you'll likely have other things to worry about as well - routing and history management, fetching and saving data to and from a server, validating data, handling realtime communication, user authentication, and all the other fun stuff that goes into a web app.
 

docs/edge/Get started.md.hbs

@@ -4,7 +4,7 @@ title: Get started
 
 Welcome! These pages aim to provide all the information you need to master Ractive.
 
-If you see something wrong, out of date, or missing from this documentation, please [raise an issue on GitHub](https://github.com/ractivejs/docs.ractivejs.org/issues) or - even better - submit a pull request. Your fellow Ractive users will thank you!
+If you see something wrong, out of date, or missing from this documentation, please check out our {{{createLink 'Known issues, FAQs, and Tips' 'known issues and FAQs'}}}, [raise an issue on GitHub](https://github.com/ractivejs/docs.ractivejs.org/issues) or - even better - submit a pull request. Your fellow Ractive users will thank you!
 
 Using Ractive is very simple. An instance is created using `new Ractive({...})`
 with the desired options:

docs/edge/Known issues, FAQs, and Tips.md.hbs

@@ -0,0 +1,37 @@
+---
+title: Known issues, FAQs, and Tips
+---
+
+## Known Issues
+
+### Memory and crashing issues with Safari on iOS 9
+
+It seems that Apple has introduced some memory management _feature_ with Safari in iOS 9 that causes large templates to crash Safari during parsing. Fortunately, this can be worked around by splitting your templates into smaller partials or, more efficiently, by pre-parsing your templates and serving them as a JS object. You can use {{{createLink 'Ractive.parse()'}}} to create the JS object as a build step or when the page is being served.
+
+Since there isn't _really_ any browser for iOS other than Safari, all browser on iOS 9 are affected by this issue. iOS 8 seems to remain unaffected.
+
+## FAQs
+
+__Coming Soon!™__
+
+## Tips
+
+### Using Ractive with...
+
+* {{{createLink 'using-ractive-with-backbone' '...Backbone'}}}
+* {{{createLink 'using-ractive-with-requirejs' '...RequireJS'}}}
+* {{{createLink 'using-ractive-with-browserify' '...Browserify'}}}
+* {{{createLink 'using-ractive-with-yeoman' '...Yeoman'}}}
+* {{{createLink 'Promises' '...built-in Promise support'}}}
+* {{{createLink 'using-ractive-with-jquery-mobile' '...jQuery Mobile'}}}
+<!-- TODO * [...Underscore (and other utility libraries)](using-ractive-with-underscore) -->
+
+### Building an app with Ractive
+
+Ractive can take care of your UI, and for simple applications it can take care of your *application state* as well. But if you're building a complex app you'll likely have other things to worry about as well - routing and history management, fetching and saving data to and from a server, validating data, handling realtime communication, user authentication, and all the other fun stuff that goes into a web app.
+
+Unlike mega-frameworks like Angular and Ember, Ractive doesn't have an opinion about these things - you're encouraged to build your app from loosely coupled modules. It means you're not beholden to a particular framework's way of doing things, and you can swap out (for example) your routing library for something better later on, but it does mean that you're now responsible for making those decisions.
+
+This section is designed to help with that, by collecting tips and advice. If you think your experience can help other developers, please add it to the wiki!
+
+* {{{createLink 'Routing'}}}

docs/edge/Migrating.md.hbs

@@ -8,11 +8,47 @@ These migration notes are cribbed from the [CHANGELOG](https://github.com/ractiv
 
 ### What's new
 
-*Nothing yet*
+Ractive's data handling has been completely rewritten to use a full viewmodel hierarchy as opposed to the previous hashmap-like implementation. This has made the code much easier to reason about, and it should also eliminate many data-related bugs. It also has made large swaths of Ractive considerably faster.
+
+Spread arguments (`...arguments`) and `arguments` access is now available for method event handlers. Individual arguments are available using array notation (`arguments[n]`), dot notation (`arguments.0`), or `1`-based dollar vars, like regular expression matches (`$1`, `$2`, etc).
+
+There is now support for linking data to extra keypaths in the model. This is particularly handy for master-detail scenarios where you have a complex lest of objects and you want to focus on a single one at a time. A keypath like `'foo.bar.bazzes.0'` can be linked to `'baz'` so that the detail section doesn't have to worry about a non-bindable expressions or copying objects around. Both sides of the link are automatically kept in sync. See {{{createLink 'ractive.link()'}}}.
+
+You can now use ES2015 object literal shorthand in templates e.g. `{ foo }` is equivalent to `{ foo: foo }`.
+
+If you have object keys with `.`s in them, you can now escape them with a `\`. So if you have a `bar` object with a `foo.baz` property, it can be accessed with `bar.foo\.baz`. Keys and keypaths in the template are given as escaped paths so that they can be used directly with Ractive methods.
+
+`<textarea>`s now handle HTML content as plain text to match what happens in browsers. They can now also set up two-way binding with a single interpolator as content instead of using the value attribute e.g. `<textarea>\{{someBinding}}</textarea>` is equivalent to `<textarea value="\{{someBinding}}"></textarea>`.
+
+Progressive enhancement is now supported with a few limitations. If you pass `enhance: true` when creating your Ractive instance, it will not discard the contents of its target element and will instead try to reuse elements and nodes as it builds the virtual DOM from its template. This option is incompatible with the `append` option.
+
+The `Object`, `String`, and `Boolean` globals are now accessible from within templates.
+
+You can now set up aliases with context and iterative mustache sections that can be used to clarify templates and avoid issues with object-literal context sections and two-way binding. For context sections, use `\{{#with someExpressionOrRef as alias1, some.deeply.nested[reference].expression as alias2}}...\{{/with}}` to set up as many aliases as you need. For iterative sections, you can alias the context with the iteration (the current item) by using `\{{#each some.list as item}}...\{{/each}}`. Partial contexts also support aliasing, since partial context is just a shortcut for `\{{#with context}}\{{>partial}}\{{/with}}`, as `\{{>somePartial some.path as alias1, some.other[expression](arg1, arg2) as alias2}}`.
+
+There is a new CSP-compatible parsing mode that collects all of the expressions in the template at the end of the parse and stores them as `function`s on the template root. At render-time, any expressions look for a corresponding pre-built function before using `new Function(...)` to create one. Templates parsed in this way are no longer JSON compatible. To enable this mode, pass `csp: true` when pre-parsing your template.
+
+If your environment supports it, you can now use Unicode characters from the Supplementary Multilingual Plane and the Supplemental Idiographic Plane in your templates.
+
+There are two new special references available on your templates for access to the current Ractive instance and your environment's global object. `@ractive` will resolve to the nearest Ractive instance in the template, which includes components should the template belong to one. `@global` resolves to `window` in most browsers and `global` in Node.js. Both special references are also available outside of the template so that Ractive can be notified of changes outside the template easily.
+
+Keywords can now be used as references, so you can now use `new`, `if`, `while`, etc as references.
+
+Keypaths within components are now adjusted to be relative to the component. If you need to access the path to the data relative to the root instance, you can use the new special reference `@rootpath`.
+
+Partials defined in `<script>` tags can now contain top-level inline partial definitions that will get added to the instance along with the scripte-defined partial.
+
+You can now retrieve the CSS for a Ractive instance with a new `toCSS` method. You can also get the CSS for all instances with a new static Ractive method of the same name.
 
 ### Breaking changes and deprecation
 
-* *Nothing yet*
+* Names in partial mustaches have been further relaxed to allow `/`s. They can also now handle relative contexts because partial name expressions no longer support spaces around the `.` delimiters in object paths. `\{{> foo.bar.baz .bat}}` before this change would have parsed as a single expression to get the partial name from `foo.bar.baz.bat`. It will now get the name from `foo.bar.baz` and have a context provided from `.bat`.
+
+* Other elements are no longer allowed within `<option>` elements.
+
+* Integer literals in interpolators are now considered to be integer literal expressions rather than references. They were considered references before so that you could access array members by index within a context. If you need to access an array member within a context section, you can still do so with `\{{this.0}}`.
+
+* The private `_ractive` tracking data added to Ractive controlled DOM nodes has changed significantly. The format of `Ractive.getNodeInfo` objects is still compatible.
 
 ## Migrating from 0.6.x
 

docs/edge/Mustaches.md.hbs

@@ -473,58 +473,43 @@ In this example, clicking the button gets a "random" coin flip result, sets it i
 <a name="aliasing"></a>
 ### Aliasing
 
-Since a section with a non-falsy value uses the value as its context, an object expression can be used to create an arbitrary context within a section. Any currently visible context keypaths can be referenced within the new context object, which allows you to keep keypaths available that would otherwise be unreachable.
-
-```html
-\{{# { id: '10t' } }}
-  Error: \{{id}}
-\{{/}}
-```
-
-Output:
-```html
-Error: 10t
-```
-
-Using a section with an object expression to keep references accessible or convenient:
-
-```html
-<ul>
-\{{#things:outerIndex}}
-  \{{# { thing: ., i: outerIndex } }}
-    \{{#colors:j}}
-      <li>\{{i}}-\{{j}} \{{.}} \{{thing}}</li>
-    \{{/}}
-  \{{/}}
-\{{/}}
-</ul>
-```
-
-**Note** `i` as `outerIndex` is not required, `outerIndex` is still accessible within the `\{{#colors}}` section.
-
-Data:
+Any section (or `\{{#with}}` section) provides its own context to the template that falls within it, and any references within the section will be resolved against the section context. Ambiguous references are resolved up the model hierarchy _and_ the context hierarchy. Given a data structure that looks like
 ```js
 {
-  colors: ['Purple', 'Orange', 'Green'],
-  things: ['People-Eater', 'Orange', 'Hornet']
+  foo: {
+    baz: 99,
+    bar: {
+      baz: 42
+    }
+  },
+  list: [
+    baz: 198,
+    bar: {
+      baz: 84
+    }
+  ]
 }
 ```
-
-Output:
+and a template
 ```html
-<ul>
-  <li>0-0 Purple People-Eater</li>
-  <li>0-1 Orange People-Eater</li>
-  <li>0-2 Green People-Eater</li>
-  <li>1-0 Purple Orange</li>
-  <li>1-1 Orange Orange</li>
-  <li>1-2 Green Orange</li>
-  <li>2-0 Purple Hornet</li>
-  <li>2-1 Orange Hornet</li>
-  <li>2-2 Green Hornet</li>
-</ul>
+\{{#each list}}
+  explicit 1: \{{.bar.baz}}
+  \{{#with .bar}}
+    implicit 1: \{{baz}}
+    \{{#with ~/foo}}
+      explicit 2: \{{.bar.baz}}
+      implicit 2: \{{baz}}
+    \{{/with}}
+  \{{/with}}
+\{{/each}}
 ```
+there is no way to reference `~/list.0.baz` from the second implicit site because the site has a different context (`~/foo`) and using an ambiguous reference (`baz`) results in `~/foo.baz`  being used. Aliasing offers an escape hatch for similarly complex scenarios where ambiguity can cause the wrong reference to be used or performance issues to arise, because ambiguity is expensive.
+
+Alias block use the existing `\{{#with}}` mustache, but instead of setting a context, they set names for one or more keypaths. Aliases follow the form `destination as alias`, where destination is any valid reference at that point in the template e.g. `\{{#with .foo as myFoo, @key as someKey, 10 * @index + ~/offset as someCalculation, .baz.bat as lastOne}}`. Because plain reference aliases, like the `myFoo` and `lastOne` aliases in the example, refer to exactly one non-computed keypath, they can also be used for two-way binding deeper in the template. For example, `<input value="\{{myFoo}}" />` as a child of the alias block would bind to `.foo` in the context where the alias block is defined.
+
+Aliasing is also extended to `\{{#each}}` blocks so that the iterated item can be named rather than just referred to as `this` or `.`. For instance, `\{{#each list as item}}` would make `item` equivalent to `this` directly within the `each` block, but `item` would still refer to same value in further nested contexts. Index and key aliases can still be used with an aliased iteration e.g. `\{{#each object as item: key, index}}`.
 
+Finally, partials can also be used with alias shorthand in much the same way that they can be passed context e.g. `\{{>somePartial .foo.bar as myBar, 20 * @index + baz as myComp}}`.
 
 <a name="static"></a>
 ### Static mustaches