React View-Models
Connect observable view-models to React presentational components to create auto rendering container components.
Install
ES6
;;;
CommonJS
var reactViewModel = ;var Component = Component;var makeReactComponent = makeReactComponent;
API
reactViewModel( displayName, ViewModel, Component )
Connect a ViewModel class to React presentational components and produce a renderer function (primarily for use in CanComponent.extend()
).
reactViewModel()
takes 3 arguments. The first (optional) is the displayName of the resulting ReactComponent (only used for render functions). The second is a ViewModel constructor function, which is an extended can-define/map. The third argument is a Presentational Component constructor function or render function. If Component
is a render function, a new React Component will be created, extending CanReactComponent
, which uses the provided render function. The reactViewModel()
function returns a renderer function, which can be used by CanComponent.extend()
or manually to create a DOM Fragment.
Since the Container Component doesn't produce DOM artifacts of it’s own, you won’t end up with any wrapper divs or anything to worry about, but in react-device-tools you will see the component with the displayName
(or defaults to CanReactComponentWrapper
) in the tree.
Example
var CanComponent = ;var reactViewModel = ;var stache = ; var ViewModel = DefineMap; moduleexports = CanComponent;
Component
class
Connect a ViewModel class to React presentational components
To use the Component
class, your Presentational Component should extend Component
instead of React.Component
, and you should provide a static ViewModel
on your class.
Every instance of the returned component will generate an instance of the ViewModel and provide it as props to the connected component. The ViewModel
instance will be initialized with the props
passed into the Container Component, and provided to your methods as this.props
. Whenever the container component will receive new props
, the new values are passed to the viewModels .set()
method, which may in turn cause an observable change event, which will re-run the observed render process and provide the child component new props, which may cause a new render.
note: If you extend any of the react lifecycle methods, you must call super so as not to break the view-model binding. This includes: componentWillReceiveProps
, componentWillMount
, componentDidMount
, componentWillUpdate
, componentDidUpdate
, componentWillUnmount
Example
;; { return <div>thispropstext</div>; } AppComponentViewModel = DefineMap;
makeReactComponent( displayName, CanComponent )
Convert a CanComponent class into a React Component.
makeReactComponent()
takes 2 arguments. The first (optional) is the displayName of the ReactComponent. The second argument is a CanComponent constructor function. The makeReactComponent()
function returns a React Component which can then be imported and used in any react component or render function as usual.
Since the Component doesn't produce DOM artifacts of it’s own, you won’t end up with any wrapper divs or anything to worry about, but in react-device-tools you will see the component with the displayName
(or defaults to CanComponentWrapper
) in the tree.
Example
;; const InnerComponent = ; { return <InnerComponent text="inner text" /> ; }
Common use cases when using a view model
Here are some examples that may come up when using a view-model that may not be obvious at first:
Transforming a prop before passing it down to a child component
Sometimes you want a prop that is set on your connected component to be set to the exact same prop key on the child component, but modified slightly before passing it down. Here's an example of that:
const ViewModel = DefineMap;
Calling a parents callback, while also doing something special in your view models callback
Sometimes, you still want to notify the connected components owner component that the state changed (by calling a callback), but only after or while doing something different within the view-model. In this case, you'll want to define the callback prop as a observable attribute with a getter, rather than a method, and use the lastSetVal
argument to call the parent components callback.
const ViewModel = DefineMap;
Contributing
Running the tests
Tests can run in the browser by opening a webserver and visiting the test/test.html
page.
Automated tests that run the tests from the command line in Firefox can be run with
npm test