ractive - npm Package Versions

Breaking changes

• Templates parsed with previous versions of Ractive are no longer compatible.
• IE8 is no longer supported.
• Two-way binding is no longer allowed in computed contexts e.g. \{{#each filter(someList)}}<input value="\{{.prop}}" />\{{/each}} because changes to the computed child (filter(someList).0.prop aren't kept in sync with their source (someList.?.prop) as Ractive doesn't know how to reverse the expression. There is an ongoing discussion about how to address this, including an open PR that would put this behavior behind a flag and attempt to keep the sources up to date as the computation children changed.
• 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.
• \{{#with obj}} will no longer render if obj is falsey (https://github.com/ractivejs/ractive/issues/1856)
• modifyArrays now defaults to false. If you modify arrays using splice operations directly, you will need to notify Ractive to sync with the changes afterwards.

Deprecated features

• Method event calls and proxy events with arguments are now deprecated and being replaced with {{{createLink 'Method calls' 'event expressions' }}}.
• {{{createLink 'events' 'Event objects' }}} now have fairly comprehensive contextual helpers installed on them. The old keypath, key, index properties are deprecated.
• Element directives are now supported inside of conditionals. Part of this change and that of event expressions has changed the template format, and this, compiled templates from previous versions of Ractive are no longer compatible. The template syntax, while evolved, is still compatible with previous versions. Some of the deprecated constructs will be removed in a future version.
• The intro, outro, and intro-outro directives have been deprecated and replaced by named and suffixed directives ${name}[-in][-out] e.g. fade-in-out. Arguments passed to these directives should no longer be wrapped in mustaches, as they are parsed as an array. Dynamism for transitions can be achieved with attribute sections.
• The decorator directive has similarly deprecated and replaced by prefixed and named directives as-${decorator} e.g. as-ace-editor. Arguments passed to these directives should also no longer be wrapped in mustaches, as they are also parsed as an array. Multiple decorators are now supported by simply including multiple directives e.g. as-registered="'some-id'" as-validated="{ maxLen: 10, match: /^foo/ }".
• Accessing expression models via keypath is now deprecated and will be removed in a future version. Expression keypaths can overlap, which can cause unexpected things to happen for the overlapping paths. You can now use context methods on an event or node info object with relative keypaths to interact with expression contexts. For example: \{{#with some.expression()}}<button on-click="@this.set(@keypath + '.foo', 42)">set .foo to 42</button>\{{/with}} would become \{{#with some.expression()}}<button on-click="event.set('.foo', 42)">set .foo to 42</button>\{{/with}}.

New features

• 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 list 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. Keypaths in the template are given as escaped paths so that they can be used directly with Ractive methods. There are also a few new static methods on Ractive to deal with escaping, unescaping, splitting, and joining keypaths.
• <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 (see {{{createLink 'options' 'enhance' 'enhance'}}}). 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 functions 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. @this 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.
• You can now trigger a transition with ractive.transition( transition, node, options ), and node can be supplied implicitly from an event handler. Transitions can now return a Promise and complete will automatically be called when the promise resolves.
• Class and style attributes now get special treatment that keeps them from clobbering external changes. There are also special attribute forms for targeting a single class or inline style at a time using e.g. style-left="\{{x}}px" and class-someClass="\{{someCondition || someOtherCondition}}". For the special style form, additional hyphens in the attribute are turned into camel case. For the special class form, the truthiness of the value determines whether or not the class is added to the list.
• As set will create intermediate objects when setting an undefined keypath, array methods will now swap in an empty array instead of erroring when called with an undefined keypath. Trying to use an array method with a non-array value including null will still throw.
• Event objects created by event directives and the results of {{{createLink 'Ractive.getNodeInfo()'}}} are now enhanced with a number of contextual helper methods to make interacting with Ractive in template-relative contexts programmatically easier. The old node info object properties are now deprecated, and their functionality has been replaced by the resolve and get methods.
• Transitioning elements will not longer keep unrelated elements from being removed. Transitions now have a safety check that forces them to complete within a short interval from their target duration, which keeps misbehaving transitions and browsers from causing elements to get stuck in the DOM.
• elseif and else blocks no longer include previous blocks' conditions in their own, so expensive computations are no longer repeated and conditions for elseif are no longer forced to be an expression. Instead, subordinate blocks connect with their siblings when they render and only show if all prior siblings have falsey conditions.
• merge can now be called with the same array that exists at the given keypath, and the differences will be computed from the model's cached array members. This allows extensive in-place modification of an array to be handled as a series of splice operations but in a single operation. Note that merge may be moved to a set option at some pooint in the future.

Bug fixes and other changes - way too many to list

Breaking changes

• ractive.data is no longer exposed. Use ractive.get() and ractive.set() rather than accessing data directly
• When instantiating or extending components, data properties on the instance/child component always override parent data

Deprecated features

• ractive.debug is replaced with a global Ractive.DEBUG flag (see below)
• Inline partial definition comments (<!-- {{>myPartial}} -->...) should be replaced with inline partial sections (see below)
• options.data should, if supplied, be a plain old JavaScript object (non-POJOs) or a function that returns one. Non-POJOs and arrays should only exist as properties of options.data

New properties

• ractive.parent - reference to parent component
• ractive.container - reference to container component (e.g. in <x><y/></x>, x === y.container)
• ractive.root - reference to a component's top level parent (i.e. created with new Ractive())

New methods

• ractive.findParent(name) - finds the nearest parent component matching name
• ractive.findContainer(name) - finds the nearest container component matching name
• ractive.resetPartial('name', template) - updates all instances of {{>name}}
• ractive.toHtml() is an alias for ractive.toHTML()
• ractive.once() and ractive.observeOnce() are self-cancelling versions of ractive.on() and ractive.observe()
• Ractive.getNodeInfo(node) returns information about node's owner and the context in which it lives

Other features

• Rearchitecture of inter-component mappings, resulting in much faster updates.
• Ractive.DEBUG flag controls whether warnings for non-fatal errors are printed to the console
• console can be accessed inside template expressions (e.g. {{console.log(this)}}), for debugging
• elseif in templates: {{#if something}}...{{elseif otherthing}}...{{/if}}
• Element-level twoway directive for granular control over two-way binding
• Element-level lazy directive, e.g. lazy=true or lazy=250 to prevent or throttle data updates from user input
• Inline partial section definitions ({{#partial myPartial}}...{{/partial}}). As well as defining partials within a template, they are used with named yields inside components (see next). Partial definitions must exist at the top level of a template, or as an immediate child of an element/component
• ractive.set() can be used to set multiple 'wildcard' keypaths simultaneously
• ractive.toggle(wildcardKeypath) toggles all keypaths matching wildcardKeypath individually. Ditto ractive.add() and ractive.subtract()
• Better parse errors for malformed templates
• Sourcemaps

Bug fixes - too many to list...

• If obj has no keys, then the else half of {{#each obj}}...{{else}}...{{/each}} will render

• this.event available in method calls
• Deprecation warnings are printed regardless of whether debug is true
• HTML entity decoding is done at parse time, not render time
• Special @keypath reference resolves to the current context
• @index, @key and @keypath references are resolved at render time, not parse time (fixes #1303)
• Centralised reference resolution logic
• console is a supported global in expression - e.g. {{console.log('debugging',foo)}}

• new Ractive() now inherits all options as methods/properties including event hooks.
• The deprecated init() function (see below) is mapped to onrender() and will fire more than once, and no longer contains options argument
• New reserved events (see below)
• Setting uninitialised data on a component will no longer cause it to leak out into the parent scope
• 'Smart updates', via ractive.merge() and ractive.shift() etc, work across component boundaries

• beforeInit(), init(), and complete() - replaced with onconstruct(), onrender() and oncomplete() methods

• Event hooks: onconstruct(), onconfig(), oninit(), onrender(), oncomplete(), onunrender(), onteardown(). These all have equivalent events, e.g. this.on('render',...), which are reserved (i.e. you cannot use them as proxy events in templates)
• Conditional attributes, e.g. <div {{#if selected}}class='selected'{{/if}}>...</div>
• Safe to specify touch events for browsers that do not support them
• Added support for {{else}} in {{#with}} block
• Added support for {{#each...}}...{{else}}...{{/each}} with empty objects (#1299)
• Within event handlers, the event object is available __/25/2020as this.event, and has a name property (useful alongside ractive.on('*',...)).
• Character position is include alongside line and column information when parsing with includeLinePositions: true
• Computed values and expressions are more efficient, and will not recompute unnecessarily