Skip to content

Commit 14c8a39

Browse files
mweststratemweststrate
committed
Merged better docs branch
1 parent 0ed1ac1 commit 14c8a39

7 files changed

Lines changed: 394 additions & 233 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ npm-debug.log
55
coverage/
66
.tscache
77
*.js.map
8+
lib/*.js.map
89
/test/typescript-test.js*
910
/dist/test
1011
notes.md

‎README.md‎

Lines changed: 33 additions & 123 deletions
Original file line numberDiff line numberDiff line change
@@ -3,36 +3,30 @@
33
<img src="https://mweststrate.github.io/mobservable/images/mobservable.png" align="right" width="120px" />
44

55

6-
##### _Unobtrusive reactive library that keeps views automatically in sync with data._
6+
##### _Keeps views automatically in sync with state. Unobtrusively._
77

88
[![Build Status](https://travis-ci.org/mweststrate/mobservable.svg?branch=master)](https://travis-ci.org/mweststrate/mobservable)
99
[![Coverage Status](https://coveralls.io/repos/mweststrate/mobservable/badge.svg?branch=master&service=github)](https://coveralls.io/github/mweststrate/mobservable?branch=master)
1010
[![mobservable channel on slack](https://img.shields.io/badge/slack-mobservable-blue.svg)](https://reactiflux.slack.com/messages/mobservable/)
1111

12-
[API documentation](https://github.com/mweststrate/mobservable/blob/master/docs/api.md) - [Typings](https://github.com/mweststrate/mobservable/blob/master/dist/mobservable.d.ts)
1312

14-
## Philosophy
13+
##### <center>A [Five minute, interactive introduction](https://mweststrate.github.io/mobservable/getting-started.html) to Mobservable and React</center>
1514

16-
Mobservable is light-weight standalone library to create reactive primitives, functions, arrays and objects.
17-
The goal of mobservable is simple:
1815

19-
1. Write simple views. Views should be subscription free.
20-
2. Write simple controllers and stores. Change data without thinking about how this should be reflected in views.
21-
3. Allow flexible model design, be able to use mutable objects, arrays, classes, real references, and cyclic data structures in your app.
22-
4. Performance: find the absolute minimum amount of changes that are needed to update views.
23-
5. Views* should be updated atomically and sychronously without showing stale or intermediate values.
16+
[API documentation](https://github.com/mweststrate/mobservable/blob/master/docs/api.md) - [Tips & Tricks](https://github.com/mweststrate/mobservable/blob/master/docs/syntax.md) - [ES5, ES6, TypeScript syntax examples](https://github.com/mweststrate/mobservable/blob/master/docs/api.md) - [TypeScript Typings](https://github.com/mweststrate/mobservable/blob/master/dist/mobservable.d.ts)
2417

25-
Mobservable is born as part of an enterprise scale visual editor,
26-
which needs high performance rendering and covers over 400 different domain concepts.
27-
So the best performance and the simplest possible controller and view code are both of the utmost importance.
28-
See [this blog](https://www.mendix.com/tech-blog/making-react-reactive-pursuit-high-performing-easily-maintainable-react-apps/) for more details about that journey.
29-
Mobservable applies reactive programming behind the scenes and is inspired by MVVM frameworks like knockout and ember, yet less obtrusive to use.
18+
## Introduction
3019

31-
\* 'Views' should be interpreted in the broadest sense: User interface, derived data, backend storage; anything that can be derived from your data in a pure manner is a view of the data.
20+
Mobservable is a library to create reactive state and views. Mobservable updates views automatically when the state changes, and thereby achieves [inversion of control](https://en.wikipedia.org/wiki/Inversion_of_control). This has major benefits for the simplicity, maintainability and performance of your code. This is the promise of Mobservable:
21+
* Write complex applications which unmatched simple code.
22+
* Enable unobtrusive state management: be free to use mutable objects, cyclic references, classes and real references to store state.
23+
* Write declarative views that track their own dependencies. No subscriptions, cursors or other redundant declarations to manage.
24+
* Build [high performing](mendix.com/tech-blog/making-react-reactive-pursuit-high-performing-easily-maintainable-react-apps/) React applications without Flux or Immutable data structures.
25+
* Predictable behavior: all views are updated synchronously and atomically.
3226

3327
## The essentials
3428

35-
Mobservable can be summarized in two functions that will fundamentally simplify the way you write Reactjs applications. Lets take a look at this really really simple timer application:
29+
Mobservable can be summarized in two functions that will fundamentally simplify the way you write React applications. Lets take a look at this really really simple timer application:
3630

3731
```javascript
3832
var timerData = {
@@ -52,8 +46,10 @@ var Timer = React.createClass({
5246
React.render(<Timer timerData={timerData} />, document.body);
5347
```
5448

55-
So what will this app do? It does nothing! The timer increases every second, but the UI never responds to that. After the interval updates the timer we should force the UI to update.
56-
But that is the kind of dependency we want to avoid in our code. So let's apply two simple functions of mobservable instead to fix this issue:
49+
So what will this app do? It does nothing! The timer increases every second, but the will UI never update. To fix that, we should force the UI to refresh somehow upon each interval.
50+
But that is the kind of dependency we should avoid in our code. We shouldn't have to _pull_ data from our state to update the UI. Instead, the data structures should be in control and call the UI when it needs an update. The state should be _pushed_ throughout our application. This is called inversion of control.
51+
52+
We can apply two simple functions of Mobservable to achieve this.
5753

5854
### mobservable.makeReactive
5955

@@ -75,7 +71,7 @@ var Timer = mobservable.reactiveComponent(React.createClass{
7571
}));
7672
```
7773

78-
Thats all folks! Its as simple as that. The `Timer` will now automatically update each time `timerData.secondsPassed` is altered.
74+
Its as simple as that. The `Timer` will now automatically update each time `timerData.secondsPassed` is altered.
7975
The actual interesting thing about these changes are the things that are *not* in the code:
8076

8177
* The `setInterval` method didn't alter. It still treats `timerData` as a plain JS object.
@@ -93,118 +89,24 @@ It does not only work for plain objects, but also for arrays, functions, classes
9389
<img src="https://mweststrate.github.io/mobservable/images/overview.png" height="300"/>
9490
</div>
9591

96-
## A Todo application
97-
98-
The following simple todo application can be found up & running on https://mweststrate.github.io/mobservable. A full TodoMVC implementation can be found [here](https://github.com/mweststrate/todomvc/tree/master/examples/react-mobservable).
99-
Note how the array, function and primitive of `todoStore` will all become reactive. There are just three calls to `mobservable` and all the components are kept in sync with the `todoStore`.
100-
101-
```javascript
102-
var todoStore = mobservable.makeReactive({
103-
todos: [
104-
{
105-
title: 'Find a clean mug',
106-
completed: true
107-
},
108-
{
109-
title: 'Make coffee',
110-
completed: false
111-
}
112-
],
113-
completedCount: function() {
114-
return this.todos.filter((todo) => todo.completed).length;
115-
},
116-
pending: 0
117-
});
118-
119-
todoStore.addTodo = function(title) {
120-
this.todos.push({
121-
title: title,
122-
completed: false
123-
});
124-
};
125-
126-
todoStore.removeTodo = function(todo) {
127-
this.todos.splice(this.todos.indexOf(todo), 1);
128-
};
129-
130-
todoStore.loadTodosAsync = function() {
131-
this.pending++;
132-
setTimeout(function() {
133-
this.addTodo('Asynchronously created todo');
134-
this.pending--;
135-
}.bind(this), 2000);
136-
};
137-
138-
var TodoList = mobservable.reactiveComponent(React.createClass({
139-
render: function() {
140-
var store = this.props.store;
141-
return (<div>
142-
<ul>
143-
{ store.todos.map((todo, idx) =>
144-
(<TodoView store={ store } todo={ todo } key={ idx } />)
145-
) }
146-
{ store.pending ? (<li>Loading more items...</li>) : null }
147-
</ul>
148-
<hr/>
149-
Completed { store.completedCount } of { store.todos.length } items.<br/>
150-
<button onClick={ this.onNewTodo }>New Todo</button>
151-
<button onClick={ this.loadMore }>Load more...</button>
152-
</div>);
153-
},
154-
155-
onNewTodo: function() {
156-
this.props.store.addTodo(prompt('Enter a new todo:', 'Try mobservable at home!'));
157-
},
158-
159-
loadMore: function() {
160-
this.props.store.loadTodosAsync();
161-
}
162-
}));
163-
164-
var TodoView = mobservable.reactiveComponent(React.createClass({
165-
render: function() {
166-
var todo = this.props.todo;
167-
return (<li>
168-
<input type='checkbox' checked={ todo.completed } onChange={ this.onToggleCompleted } />
169-
{todo.title}{' '}
170-
<a href='#' onClick={ this.onEdit }>[edit]</a>
171-
<a href='#' onClick={ this.onRemove }>[remove]</a>
172-
</li>);
173-
},
174-
175-
onToggleCompleted: function() {
176-
this.props.todo.completed = !this.props.todo.completed;
177-
},
178-
179-
onEdit: function(e) {
180-
e.preventDefault();
181-
this.props.todo.title = prompt('Todo:', this.props.todo.title);
182-
},
183-
184-
onRemove: function(e) {
185-
e.preventDefault();
186-
this.props.store.removeTodo(this.props.todo);
187-
}
188-
}));
189-
190-
React.render(<TodoList store={todoStore} />, document.getElementById('approot'));
191-
```
192-
19392
## Getting started
19493

19594
Either:
95+
* [Edit](https://mweststrate.github.io/mobservable/getting-started.html#demo) a simple ToDo application online.
19696
* `npm install mobservable --save`
197-
* clone the boilerplate repository containing the above example from: https://github.com/mweststrate/react-mobservable-boilerplate
198-
* or fork this [JSFiddle](https://jsfiddle.net/mweststrate/wgbe4guu/)
97+
* Clone the boilerplate repository containing the above example from: https://github.com/mweststrate/react-mobservable-boilerplate.
98+
* Or fork this [JSFiddle](https://jsfiddle.net/mweststrate/wgbe4guu/).
19999

200100
## Examples
201101

102+
* The [ports of the _Notes_ and _Kanban_ examples](https://github.com/survivejs/mobservable-demo) from the book "SurviveJS - Webpack and React" to mobservable.
202103
* A simple webshop using [React + mobservable](https://jsfiddle.net/mweststrate/46vL0phw) or [JQuery + mobservable](http://jsfiddle.net/mweststrate/vxn7qgdw).
203-
* [Simple timer](https://jsfiddle.net/mweststrate/wgbe4guu/)
104+
* [Simple timer](https://jsfiddle.net/mweststrate/wgbe4guu/) application in JSFiddle.
204105
* [TodoMVC](https://rawgit.com/mweststrate/todomvc/immutable-to-observable/examples/react-mobservable/index.html#/), based on the ReactJS TodoMVC.
205106

206107
## Read more
207108

109+
* [Five minute interactive introducton](https://mweststrate.github.io/mobservable/getting-started.html) to Mobservable and React
208110
* [Making React reactive: the pursuit of high performing, easily maintainable React apps](https://www.mendix.com/tech-blog/making-react-reactive-pursuit-high-performing-easily-maintainable-react-apps/)
209111
* [Pure rendering in the light of time and state](https://medium.com/@mweststrate/pure-rendering-in-the-light-of-time-and-state-4b537d8d40b1)
210112
* [Official homepage](http://mweststrate.github.io/mobservable/)
@@ -239,20 +141,28 @@ Useful to bridge reactive code to imperative code.
239141

240142
## FAQ
241143

242-
**Is mobservable a framework?**
144+
##### Is mobservable a framework?
243145

244146
Mobservabe is *not* a framework. It does not tell you how to structure your code, where to store state or how to process events. Yet it might free you from frameworks that poses all kinds of restrictions on your code in the name of performance.
245147

246-
**Can I combine flux with mobservable?**
148+
##### Can I combine flux with mobservable?
247149

248150
Flux implementations that do not work on the assumption that the data in their stores is immutable should work well with mobservable.
249151
However, the need for flux is less when using mobservable.
250152
Mobservable already optimizes rendering and since it works with most kinds of data, including cycles and classes.
251153
So other programming paradigms like classic MVC are now can be easily applied in applications that combine ReactJS with mobservable.
252154

253-
**Can I use mobservable together with framework X?**
155+
##### Can I use mobservable together with framework X?
254156

255157
Probably.
256158
Mobservable is framework agnostic and can be applied in any JS environment.
257159
It just ships with a small function to transform Reactjs components into reactive view functions for convenience.
258160
Mobservable works just as well server side, and is already combined with JQuery (see this [Fiddle](http://jsfiddle.net/mweststrate/vxn7qgdw)) and [Deku](https://gist.github.com/mattmccray/d8740ea97013c7505a9b).
161+
162+
##### Can I record states and re-hydrate them?
163+
164+
Yes, some examples are coming shortly!
165+
166+
##### Can you tell me how it works?
167+
168+
Sure, join the reactiflux channel our checkout [dnode.ts](dnode.ts). Or, submit an issue to motivate me to make some nice drawings :).

0 commit comments

Comments
 (0)