ractive

Ractive.js - Next-generation DOM manipulation

Got questions? Tag Stack Overflow questions with ractivejs or contact @RactiveJS on Twitter

What is Ractive.js?

It's a JavaScript library for building reactive user interfaces in a way that doesn't force you into a particular framework's way of thinking. Its features include...

• data-binding, with a beautiful declarative syntax
• event handling that doesn't make you tear your hair out
• flexible and performant animations and transitions

...among many others. It takes a radically different approach to DOM manipulation - one that saves both you and the browser unnecessary work.

To get a feel for how it will make your life as a web developer easier, visit ractivejs.org, follow the interactive tutorials, or try the 60 second setup.

Get help

If you don't find what you're looking for in the docs, ask a question in Google Groups forum, Stack Overflow with the ractivejs tag, or send a tweet to @RactiveJS.

Developing and building

If you want to hack on Ractive, the first step is to clone the repo and install all its development dependencies:

git clone https://github.com/ractivejs/ractive   # or your fork
cd ractive
npm install

While developing the library, you can serve it with gobble:

npm start

Navigate to localhost:4567 - you'll see two folders, plus ractive.js:

• sandbox - this contains some template files to help with debugging. Start by copying the sandbox/sample folder and following the instructions therein
• test - the test suite (duh)

After the initial build, any subsequent changes will result in fast incremental rebuilds. If you're using Chrome, you can use the LiveReload plugin.

Gobble is still in development - please report any bugs to the issue tracker - thanks!

To run a complete build (including linting, testing and minification):

npm run build

Distribution build requirements

• A real shell, so Linux and OS X should be good. Windows needs MSYS or something similar at least on the path.
• On Windows, if you get an EINVAL when running the tests, you may need to update the phantomjs script in the node_modules/.bin to use { stdio: 'inherit' } when spawning the child process instead of manually piping afterwards.

Contributing

Pull requests and issues are always welcome! Please read CONTRIBUTING.md to learn how to contribute.

Browser support

Tested successfully in IE8+ and all modern browsers. If your experience differs please let me know! (For legacy browser support, use the builds with legacy in the filename - these include polyfills for Array.prototype.forEach and other ES5 features used by Ractive.)

License

Copyright (c) 2012-14 Rich Harris and contributors. Released under an MIT license.

Changelog

0.7.0

2015-03-17

• 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...