« Changelog History


ractive v0.9.0 Release Notes

  • 2017-05-26

    • 🐛 Bug fixes

      • Observers on uninitialized data may be added during the config event (#2725)
      • The unwrap option of ractive.get will now properly return the wrapped object if is set to false (#1178)
      • Overriding a Ractive prototype method during Ractive.extend without calling _super() will now issue a warning, as it's probably being done in error (#2358)
      • toHTML will output CSS scoping ids for components that have a css option specified (#2709)
      • easing functions that can't be run using CSS transitions will now cause the transition to be run as JS (#2152)

    • 💥 Breaking changes

      • All deprecations have been removed, including proxy events with args, un-prefixed method events, decorator="...", transition="...", the ractive.data getter, partial comment definitions, and lifecycle methods like init and beforeInit.
      • With deprecations removed, directive values are now parsed with the plain expression parser, which doesn't automatically encode HTML entities in string literals.
      • The template spec is now a bit simpler after the removal of deprecations, and templates parsed with previous versions of Ractive are no longer compatible.
      • Partial context ({{>foo thisIsTheContext}}) now only applies inside the partial template, meaning it is no longer equivalent to {{#with thisIsTheContext}}{{>foo}}{{/with}}. The with is wrapped around the content of foo, so that the context doesn't interfere with the partial expression.
      • Any partial may be yielded, so yielding non-inline partials will no longer warn.
      • The same partial may be yielded multiple times.
      • Events now fire in an initial implicit this. namespace. This means that with this.on( '*.foo', handler ), handler will be called if and component fires a foo event or if the this instance fires a foo event.
      • The noIntro option now applies to any nested components that are also being rendered, unless they have their own explicit setting.
      • Legacy builds removed. Only regular and runtime builds are now available.
      • Library does not contain polyfills anymore for the following APIs:
      • Array.isArray
      • Array.prototype.every
      • Array.prototype.filter
      • Array.prototype.find
      • Array.prototype.forEach
      • Array.prototype.indexOf
      • Array.prototype.map
      • Array.prototype.reduce
      • Function.prototype.bind
      • Node.prototype.contains (only used in testing)
      • Object.assign
      • Object.create
      • Object.defineProperty
      • Object.defineProperties
      • Object.freeze
      • Object.keys
      • performance.now
      • Promise
      • requestAnimationFrame
      • String.prototype.trim
      • window.addEventListener
      • window.getComputedStyle
      • Ships with a separate, minimal polyfill file containing only the above APIs for older browsers.
      • ractive.nodes no longer contains elements by id. The same functionality can be handled more safely and conveniently with a decorator.
      • HTML elements are now exclusively created with a lowercase name.
      • Keypath expressions are no longer supported, as they are largely redundant with getContext functionality. (@keypath(../some.ref) is no longer a valid reference)
      • Unresolved references will now resolve to the immediate context rather than registering with every available context to be resolved when one of the contexts grows a matching base key.
      • Event directives within iterative sections will automatically use delegation (see below).
      • The undocumented observeList function has been moved to an option of observe (see below).
      • The change lifecycle event has been removed and replaced with recursive observers (see below).
      • Live element and component queries e.g. ractive.findAll( 'some selector', { live: true } ) are no longer supported. If you need similar functionality, you can use a specialized decorator for elements or lifecycle events for components.
      • Linking a keypath that happens to be observed will now cause any observers to fire.
      • The event reference in event directives is deprecated, and all event handlers will now receive a context as their first parameter regardless of whether or not they originated with a DOM event (see below).
      • ractive.merge has been moved to an option of set to better reflect what it actually does (hint: it doesn't actually merge - see below).
      • Components are now isolated by default. You can change the global default by setting Ractive.defaults.isolated if you need the old behavior to be the default.
      • ractive.runtime.js is now named runtime.js, so if you require it, it is require('ractive/runtime.js').
      • You can no longer create a component using another component as the options argument to extend e.g. MyComponent.extend(OtherComponent). You can still extend a component with one or more options objects e.g. MyComponent.extend({ ...options }, { ...other }).extend({ ...more }).
      • class- directives are now parsed in an expression context, meaning that mustaches are no longer required. This normalizes templates into two categories: stringy things that require mustaches, and value things that don't. The style- directive remains in the stringy category.
      • The magic and array adaptors have been removed from core, though they may reappear as plugins.
      • getNodeInfo has been renamed to getContext. The old name is deprecated and will be removed in a future release.
      • Non-isolated components may now implicitly map during set operations. You can achieve the previous behavior by passing isolated: true as an option.

    • 🆕 New features (experimental - feedback welcome!)

      • You can now create cross-instance links by passing an options object with a target instance e.g. this.link('source.path', 'dest.path', { ractive: sourceInstance }). This covers many of the cases handled by the ractive-ractive adaptor in a considerably more efficient manner.
      • There is now an API to manage embedding external instances i.e. out-of-template components. You can use ractive.attachChild(otherRactive, { options }) and ractive.detachChild(otherRactive) to create a component relationship between two instances. There is a new anchor construct <#anchorName /> that behaves mostly like a regular inline component except that it won't create its own Ractive instance. You can target an anchor when attaching a child by giving an anchor name as an option e.g. ractive.attachChild(otherRactive, { target: 'anchorName' }). Attached children need not be components, so you can attach a plain Ractive instance e.g. const foo = new Ractive({ ... }); ractive.attachChild(foo);.
      • {{yield}} can now be used with any partial, not just inlines, and it may also use an expression to look up the target partial. It basically behaves as a regular partial with a special context.
      • {{yield}} can also specify aliases, so that yielding is useful inside an iterative section. {{yield partialName with foo as bar}} and {{yield with foo as bar}} will make foo from the component context available to the partialName partial as bar.
      • You can specify that child keypaths of computations should trigger updates on the computation's dependencies, which should have the effect of keeping the models involved in the computation in sync with changes to the computed models. The flag to enable this behavior at instance creation is syncComputedChildren: true. With that flag set, children of computations are available for two-way binding and mutation from event or getContext objects using relative keypaths.
      • @.foo has been introduced as shorthand for @this.foo. This mirrors the data shorthand .foo for this.foo.
      • You can now pop contexts using ^^/ in the same way that you can pop keypaths with ../.
      • Special keypaths that resolve to Ractive instances now resolve using the proper model rather than a computation, so they now stay in sync.
      • There is now a special key data on special keypaths that resolve to Ractive instances that resolves to the instance's root model. This allows things like @.root.data.foo to keep the root instance foo reference in sync throughout the component tree.
      • There is a new Ractive-private shared store, @shared. This is roughly the same as @global, but it is not susceptible to interference from the global scope.
      • There is a new option, resolveInstanceMembers, which defaults to true, and when enabled, it adds the instance scope @this to the end of the reference resolution process. This means that as long as there are no conflicting members in the context hierarchy, things like <button on-click="set('foo', 'bar')">yep</button> work as expected. Note that if the resolved function will only be bound to the instance if it contains a this reference, which can be a little strange if you're debugging.
      • There is a new option, warnAboutAmbiguity, which defaults to false, and when set, it will issue a warning any time a reference fails to resolve to a member in the immediate context.
      • API methods can now handle things like ractive.set('~/foo', 'bar'), mirroring how context methods for getContext and events are handled. Things like ractive.set('.foo', 'bar') will now issue a warning and do nothing rather than creating an incorrect keypath (<empty string>.foo).
      • You can now trigger event listeners in the VDOM from event and node info objects e.g. with <div on-foo="@global.alert('hello')" > with ractive.getContext('div').raise('foo'); will trigger an alert.
      • There are two new options available for subscribing events and observers when an instance is created using two new options.
      • on takes a hash of event listeners that will be subscribed just after the construct phase of instantiation, meaning that any lifecycle events after construct may also have listeners added in the event hash.
      • observe takes a hash of observers that will be subscribed just after the config phase of instantiation.
      • Both of these options are additive, so any subscriptions defined in component super classes are applied first in sequence from the root of the component class hierarchy down to the options of the instance being created.
      • The hashes can contain keys that could be passed directly to the matching method e.g. ractive.on( key, ... ) or ractive.observe( key, ... ).
      • The hashes can contain values that are either a callback function or an object that has a handler property that is a callback function. If the object form is used, any additional keys are passed to the method. If a once property is supplied and is truthy, then the appropriate single-fire method will be used to subscribe. For instance observe: { 'foo.* bar': { handler() { ... }, strict: true, once: true, defer: true } } passed in an options object is equivalent to calling ractive.observeOnce( 'foo.* bar', function() { ... }, { strict: true, defer: true } ) during the init phase of instantiation.
      • Event listener handles returned from ractive.on( ... ) now have methods to silence and resume the listener. The existing cancel() method now has siblings isSilenced(), silence(), and resume(). When a listener is silenced, it will not call its callback.
      • Like event listeners, observer listener handles also have methods to silence and resume the listener. While an observer is silenced, it will still track state changes internally, meaning the old value on the next call after being resumed will be the last value it observed, including those observed while it was silenced. It simply won't fire its callback while it is silenced.
      • You can now stop component outros from firing while a component is being unrendered by specifying noOutro: true, which mirrors the behavior of noIntro.
      • You can now specify whether or not transitions should occur if they are on a child element of another transitioning element by using:
      • Instance option nestedTransitions, which defaults to true, meaning that transitions will fire whether they are on elements that are children of other transitioning elements or not.
      • The transition option nested, which also defaults to true.
      • There's a new ractive command distributed with the node module that allows easy pre-parsing of templates and building of components. If you have the module installed locally, see ./node_modules/.bin/ractive for more details.
      • You can now specify required and optional attributes when creating a component with Ractive.extend() using the attributes option. The value of attributes may be an array of strings, specifying that all of the named attributes are optional, or an object with required and/or optional keys that each have an array of strings as their value.
      • If attributes are specified for a component, then by default any additional attributes passed to the component will not be treated as mappings directly but instead, will be collected into a special partial named extra-attributes. You can yield this partial in an element to apply the extra attributes to it, which allows passing things like class and style along to the main element in a component easily. Note that the extra attributes will not create mappings by default, and you must yield the extra-attributes partial to put it in the scope of the containing instance. {{yield extra-attributes}}
      • If the attributes object includes mapAll: true as one of its keys, then any extra attributes will be mapped and the extra-attributes partial will contain attributes that reference the mappings, which means the partial should not be yielded. {{>extra-attributes}}
      • Event delegation is now enabled by default for iterative sections. If the iterative section is contained within an element, then any event directives in the iterations will use a shared DOM listener on the element containing the section. You can disable delegation globally with Ractive.defaults.delegate = false, on an instance with delegate: false, or at the element level with the directive (attribute) no-delegation on the element containing the section.
      • Observers have been refactored with the following new options:
      • array: true will cause the observer to fire with an object containing lists of the added and removed elements. This option replaces ractive.observeList.
      • old: function() { ... } is a hook that allows you to set the old value that the observer passes to your callback. You can use this to freeze the old value, provide a deep clone, etc.
      • Using recursive path notation e.g. some.path.** or **, you can observe any changes to the data in a way that gives you the actual value and keypath that changed e.g. with some.path.foo.bar.baz changing to 42, the observer callback would get 42 and the full keypath some.path.foo.bar.baz rather than the object at some.path, as with a regular or wildcard observer.
      • ractive.set now has the following new options:
      • { deep: true } will cause the given value to merge into the target keypath e.g. with foo as { a: 1, b: { c: 2 } }, ractive.set(foo, { d: 3, b: { e: 4 } }, { deep: true } ) will result in { a: 1, b: { c: 2, e: 4 }, d: 3 }.
      • { keep: true } will cause any VDOM fragments that would be torn down as the result of the set (or add, subtract, or toggle) to be retained. This makes it possible to have components in conditional sections not be destroyed and recreated as the section toggles.
      • { shuffle: true } when used with an array will move any existing DOM corresponding to elements in both the new and old array to their new indices. The corresponds to the removed merge method. If you want to shuffle the array against itself, you can pass null as the new value e.g. ractive.set( 'some.array', null, { shuffle: true } ).
      • The first argument to the callback supplied to ractive.on will be a context object regardless of whether or not the event originated as a DOM event. This means that all event listeners share the same base callback signature. Any additional arguments to fire will follow the context argument.
      • The event reference for event directives has been deprecated and replaced by @context, @event, and @node:
      • @context is a Ractive context object that also has an event property continaing the original event and a name that is the name of the fired event.
      • @event is the original event object, so a MouseEvent for an on-click delegate.
      • @node is the DOM node to which the event directive is attached.
      • You can now re-proxy an event from an event directive expression by returning a single array with a string first element e.g. <button on-click="['foo', arg1, arg2]">, which is the equivalent of @this.fire('foo', @context, arg1, arg2).
      • You can now use an existing class, be it ES5, ES6, or any other conforming implementation, using Ractive.extendWith( MyClass, { ...extendOpts } ). This allows class Foo { constructor( opts ) { super( opts ); /* other init */ }, someMethod () { ... }, ... } to be turned into a Ractive component.
      • To complete the split of template handling in to stringy mustaches and non-stringy expression values, the bind- directive has been introduced to bind an attribute value without mustaches e.g. <input value="{{foo}}" /> is the same as <input bind-value="foo" />. This can be used with components to create mappings to same-named values in the current context e.g. <component bind-item />.
      • There is now a post-parsing hook available in the form of parser transforms, which are simply functions that receive a template element node and return a falsey value, telling the parser to do nothing, an object with a remove boolean, telling the parser to remove the node, or an object with a replace key, telling the parser to replace the node with the given content. Any expressions injected by parser transforms also participate in the CSP adjustment process. There is also a special reference @local, which only exists directly within a given context that is intended for use by parser transforms that need minor private state management.

    • 🆕 New features (stable)

      • target is now an alias for el when creating a Ractive instance.
      • You can now use spread expressions with array and object literals in expressions in addition to method calls. Object spreads will require Object.assign to be available.
      • There is a new lifecycle hook, destruct that fires after teardown is complete and any related transitions have completed.
      • Lifecycle events now receive the source Ractive instance as their last argument.
      • You can now use context-relative observe and observeOnce from event and node info objects.
      • You can now access decorator objects from event and node info objects using obj.decorators.name, where name is the decorator name as specified in the template e.g. foo in <div as-foo />.
      • You can now get the source keypath and Ractive instance for a link/mapping using ractive.readLink( 'some.keypath' ).
      • You can now use non-tagged template strings in your templates, and they will be replaced with the appropriate expression during parsing.
      • Setting a component name to a falsey value when creating or extending a Ractive instance will block use of that component e.g. Ractive.extend({ components: { Foo: false } }) will cause Foo to be treated as an element.
      • The object passed to transition functions now has an isOutro property, which you can use to detect ractive.transition, wherein t.isIntro and t.isOutro will both be false.
      • Text nodes and interpolators will now use splitText for progressive enhancement, which should reduce or eliminate any flash during initial enhanced rendering.
      • Triples now support progressive enhancement, mostly using outerHTML to compare the target nodes to what should be rendered.
      • The css option for components can now specify an element or selector, and the textContent of the element will supply the value.
      • You can specify { force: true } to ractive.update to force the target keypath to update event if internal checks determine that the value has not changed. This is useful for causing re-evaluation of all references to a function.