flight-with-state
v8.1.0
Published
A Flight mixin for storing and reacting to change in a component's internal state.
Downloads
366
Maintainers
Readme
flight-with-state
A Flight mixin for storing and reacting to change in a component's internal state.
Installation
npm install --save flight-with-state
This module requires lodash.merge
as a peer dependency.
Example
Here's an example component that uses with withState
.
var ToggleButton = flight.component(
// Use `withState` before your component definition.
withState,
function toggleButton() {
this.attributes({
initiallyActive: false
});
// Define an instance's `initialState`
this.initialState({
active: false
});
this.after('initialize', function () {
this.on('click', this.toggle);
// Track changes to the state using advice
this.after('stateChanged', this.update);
// Transition the state using `replaceState`
this.replaceState({
active: this.attr.initiallyActive
});
});
this.toggle = function () {
// Merge changes onto the state using `mergeState`
this.mergeState({
// Access the current state using `this.state`
active: !this.state.active
});
};
this.update = function (state, previousState) {
this.$node.toggleClass('is-active', state.active);
};
}
);
Tracking changes to your state should be done with advice on stateChanged
:
this.after('stateChanged', this.reactToStateChange);
API
initialState
initialState
, like attributes
, takes an object to set up the first state
of an instance of a component. If you can pass a function, it will be called at initialize-time to produce the initial value. This allows you to react to the attrs or node of a component to produce the initial state.
For example:
this.initialState({
active: false,
id: function () {
return this.attr.id;
}
})
Warning: data structures as values in initialState
will be shared by instances of a component. If you need a new data structure each time, return it from a function.
replaceState
replaceState
changes the component's state to a new value. You can react to a change to state using this.after('replaceState', this.doSomething)
.
this.replaceState({
active: false
});
// this.state.active === false
this.replaceState({
id: '123'
});
// this.state.id === '123'
// this.state.active === undefined
mergeState
mergeState
shallow merges an object into the component's state.
this.mergeState({
active: false
});
// this.state.active === false
this.mergeState({
id: '123'
});
// this.state.id === '123'
// this.state.active === false
fromState
Make a function that returns the piece of state specified by the key
passed.
var getActive = this.fromState('active');
...
getActive.call(this); // returns this.state.active
toState
Make a function that sets the state at key
to the value it is called with.
var setActive = this.toState('active');
...
setActive.call(this, false); // sets this.state.active to false
fromAttr
Make a function that returns a components attributes, specified by the key
passed.
var id = this.fromAttr('id');
...
id.call(this); // returns this.attr.id
fromAttr
is most useful when used with initialState
:
this.attributes({
isActive: false
});
this.initialState({
active: this.fromAttr('isActive')
});
Development
To develop this module, clone the repository and run:
$ npm install && npm test
If the tests pass, you have a working environment. You shouldn't need any external dependencies.
Contributing to this project
Anyone and everyone is welcome to contribute. Please take a moment to review the guidelines for contributing.