Skip to content

Commit b911f96

Browse files
jordangarciajordangarcia
committed
Update readme to point to examples
Move flux chat example readme into the example directory
1 parent 18c650d commit b911f96

File tree

2 files changed

+372
-368
lines changed

2 files changed

+372
-368
lines changed

‎README.md

Lines changed: 3 additions & 368 deletions
Original file line numberDiff line numberDiff line change
@@ -42,375 +42,10 @@ NuclearJS can be downloaded from npm.
4242
npm install nuclear-js
4343
```
4444

45-
## Let's see some examples
46-
47-
Let's see what the original [Flux Chat Example](https://github.com/facebook/flux/tree/master/examples/flux-chat) looks like in NuclearJS.
48-
49-
All of the above code lives in [examples/flux-chat](./examples/flux-chat)
50-
51-
##### `flux.js`
52-
53-
```js
54-
// create the Nuclear reactor instance, this will act as our dispatcher and interface for data fetching
55-
var Nuclear = require('nuclear-js')
56-
57-
module.exports = new Nuclear.Reactor({
58-
debug: true,
59-
})
60-
```
61-
62-
### Modules
63-
64-
The prescribed way of code organization in NuclearJS is to group all stores, actions and getters of the same domain in a module.
65-
66-
##### Example Module File Structure
67-
68-
For the flux-chat example we will create a chat module that holds all of the domain logic for the chat aspect. For smaller projects there may only need to be one module, but for larger projects using many modules can decouple your codebase and make it much easier to manage.
69-
70-
```js
71-
modules/chat
72-
├── stores/
73-
└── thread-store.js
74-
└── current-thread-id-store.js
75-
├── actions.js // exports functions that call flux.dispatch
76-
├── action-types.js // constants for the flux action types
77-
├── getters.js // getters exposed by the module providing read access to module's stores
78-
├── index.js // MAIN ENTRY POINT - facade that exposes a public api for the module
79-
└── tests.js // module unit tests that test the modules stores, getters, and actions
80-
```
81-
82-
##### `modules/chat/index.js`
83-
84-
```js
85-
var flux = require('../../flux')
86-
87-
flux.registerStores({
88-
currentThreadID: require('./stores/current-thread-id-store'),
89-
threads: require('./stores/thread-store'),
90-
})
91-
92-
module.exports = {
93-
actions: require('./actions'),
94-
95-
getters: require('./getters'),
96-
}
97-
```
98-
99-
- Modules expose a single public API, the `index.js` file. It is improper for an outside piece of code to require any file within the module except the `index.js` file.
100-
101-
- Stores are registered lazily through the module's index.js. This may seem weird at first, but in NuclearJS stores are more of an implementation detail and not ever directly referenceable.
102-
103-
- Data access to the module's store values is done entirely through the getters it exposes. This provides a decoupling between the store implementation and how the outside world references the state that a module manages. A getter is a contract between the outside world and the module that a particular piece of information is accessible. The evaluator of a getter does not care about the underlying store representation.
104-
105-
### Stores
106-
107-
##### `modules/chat/stores/thread-store.js`
108-
109-
```js
110-
var Nuclear = require('nuclear-js')
111-
var toImmutable = Nuclear.toImmutable
112-
var actionTypes = require('../action-types')
113-
114-
module.exports = new Nuclear.Store({
115-
getInitialState() {
116-
// for Nuclear to be so efficient all state must be immutable data
117-
// mapping of threadID => Thread
118-
return toImmutable({})
119-
},
120-
121-
initialize() {
122-
// all action handlers are pure functions that take the current state and payload
123-
this.on(actionTypes.ADD_MESSAGE, addMessage)
124-
this.on(actionTypes.CLICK_THREAD, setMessagesRead)
125-
}
126-
})
127-
128-
/**
129-
* @type Message
130-
* id {GUID}
131-
* threadID {GUID}
132-
* threadName {GUID}
133-
* authorName {String}
134-
* text {String}
135-
* isRead {Boolean}
136-
* timestamp {Timestamp}
137-
*/
138-
139-
/**
140-
* @param {Immutable.Map}
141-
* @param {Object} payload
142-
* @param {Message} payload.message
143-
*/
144-
function addMessage(state, { message }) {
145-
var msg = toImmutable(message)
146-
var threadID = msg.get('threadID')
147-
148-
return state.withMutations(threads => {
149-
// use standard ImmutableJS methods to transform state when handling an action
150-
if (!threads.has(threadID)) {
151-
threads.set(threadID, toImmutable({
152-
threadID: threadID,
153-
threadName: msg.get('threadName'),
154-
messages: toImmutable([]),
155-
}))
156-
}
157-
158-
// push new message into thread and sort by message timestamp
159-
threads.update(threadID, thread => {
160-
var sortedMessages = thread.get('messages')
161-
.push(msg)
162-
.sortBy(msg => msg.get('timestamp'))
163-
164-
return thread.set('messages', sortedMessages)
165-
})
166-
})
167-
}
168-
169-
/**
170-
* Mark all messages for a thread as "read"
171-
* @param {Immutable.Map}
172-
* @param {Object} payload
173-
* @param {GUID} payload.threadID
174-
*/
175-
function setMessagesRead(state, { threadID }) {
176-
return state.updateIn([threadID, 'messages'], messages => {
177-
return messages.map(msg => msg.set('isRead', true))
178-
})
179-
}
180-
```
181-
182-
##### `modules/message/stores/current-thread-id-store.js`
183-
184-
```js
185-
var Nuclear = require('nuclear-js')
186-
var toImmutable = Nuclear.toImmutable
187-
var actionTypes = require('../action-types')
188-
189-
module.exports = new Nuclear.Store({
190-
getInitialState() {
191-
// only keeps track of the current threadID
192-
return null
193-
},
194-
195-
initialize() {
196-
// all action handlers are pure functions that take the current state and payload
197-
this.on(actionTypes.CLICK_THREAD, setCurrentThreadID)
198-
}
199-
})
200-
201-
function setCurrentThreadID(state, { threadID }) {
202-
// return the new value of the store's state
203-
return threadID
204-
}
205-
```
206-
207-
At this point defined how our application manages state over time by creating and registering the thread store and currentThreadID store. When defining stores there is no need to worry about computable state like the most recent message in each thread, this is all handled through getters.
208-
209-
### Getters
210-
211-
Getters can take 2 forms:
212-
213-
1. A KeyPath such as `['messages']` which equates to a `state.getIn(['messages'])` on the app state `Immutable.Map`.
214-
2. An array with the form `[ [keypath | getter], [keypath | getter], ..., tranformFunction]`
215-
216-
##### `modules/chat/getters.js`
217-
218-
```js
219-
// it is idiomatic to facade all data access through getters, that way a component only has to subscribe to a getter making it agnostic
220-
// to the underlying stores / data transformation that is taking place
221-
exports.threadsMap = ['threads']
222-
223-
exports.threads = [
224-
exports.threadsMap,
225-
threadsMap => threadsMap.toList()
226-
]
227-
228-
exports.currentThread = [
229-
['currentThreadID'],
230-
exports.threadsMap,
231-
(currentThreadID, threadsMap) => threadsMap.get(currentThreadID)
232-
]
233-
234-
exports.latestThread = [
235-
exports.threads,
236-
threads => {
237-
return threads
238-
.sortBy(thread => {
239-
thread.get('messages').last().get('timestamp')
240-
})
241-
.last()
242-
}
243-
]
244-
245-
246-
exports.currentThreadID = [
247-
exports.currentThread,
248-
thread => thread ? thread.get('threadID') : null
249-
]
250-
251-
exports.unreadCount = [
252-
exports.threads,
253-
threads => {
254-
return threads.reduce((accum, thread) => {
255-
if (!thread.get('messages').last().get('isRead')) {
256-
accum++
257-
}
258-
return accum
259-
}, 0)
260-
}
261-
]
262-
```
263-
264-
Since stores are registered on the Nuclear Reactor by the module's index file, then a module is the only part of the system that knows the store ids, if this information need to be made public, the module will export a getter of the form `[<storeId>]`
265-
266-
267-
### Actions
268-
269-
##### `module/chat/actions.js`
270-
271-
```js
272-
var flux = require('../../flux')
273-
var actionTypes = require('./action-types')
274-
var getters = require('./getters')
275-
276-
/**
277-
* Handles the receiving of messages into the flux system
278-
* @param {Message[]} messages
279-
*/
280-
exports.receiveAll = function(messages) {
281-
messages.forEach(message => {
282-
flux.dispatch(actionTypes.ADD_MESSAGE, { message })
283-
})
284-
}
285-
286-
/**
287-
* Creates a message
288-
* @param {String} text
289-
* @param {GUID} threadName
290-
*/
291-
exports.createMessage = function(text, threadID) {
292-
var timestamp = Date.now()
293-
var id = 'm_' + timestamp
294-
var threadName = flux.evaluate([
295-
getters.threadsMap,
296-
threadsMap => threadsMap.getIn([threadID, 'threadName'])
297-
])
298-
var authorName = 'Jordan'
299-
300-
flux.dispatch(actionTypes.ADD_MESSAGE, {
301-
message: { id, threadID, threadName, authorName, timestamp, text }
302-
})
303-
}
304-
305-
exports.clickThread = function(threadID) {
306-
flux.dispatch(actionTypes.CLICK_THREAD, { threadID })
307-
}
308-
```
309-
310-
### Hooking it up to a component
311-
312-
###### `components/ThreadSection.react.js`
313-
314-
```js
315-
var React = require('react');
316-
var flux = require('../flux');
317-
var Chat = require('../modules/chat');
318-
319-
var ThreadListItem = require('./ThreadListItem.react');
320-
321-
var ThreadSection = React.createClass({
322-
mixins: [flux.ReactMixin],
323-
324-
getDataBindings() {
325-
return {
326-
threads: Chat.getters.threads,
327-
unreadCount: Chat.getters.unreadCount,
328-
currentThreadID: Chat.getters.currentThreadID,
329-
}
330-
},
331-
332-
render: function() {
333-
var threadListItems = this.state.threads.map(thread => {
334-
return (
335-
<ThreadListItem
336-
key={thread.get('threadID')}
337-
thread={thread}
338-
currentThreadID={this.state.currentThreadID}
339-
/>
340-
);
341-
}, this);
342-
var unread =
343-
this.state.unreadCount === 0 ?
344-
null :
345-
<span>Unread threads: {this.state.unreadCount}</span>;
346-
return (
347-
<div className="thread-section">
348-
<div className="thread-count">
349-
{unread}
350-
</div>
351-
<ul className="thread-list">
352-
{threadListItems}
353-
</ul>
354-
</div>
355-
);
356-
},
357-
});
358-
359-
module.exports = ThreadSection;
360-
```
361-
362-
`flux.ReactMixin` handles all of the pub/sub between the flux system and component and will only render the component via a `setState` call whenever any of the subscribed getters' value changes. The mixin will also automatically unsubscribe from observation when the component is unmounted.
363-
364-
##### `ThreadListItem.react.js`
365-
366-
```js
367-
var React = require('react');
368-
var Chat = require('../modules/chat');
369-
var cx = require('react/lib/cx');
370-
371-
var ReactPropTypes = React.PropTypes;
372-
373-
var ThreadListItem = React.createClass({
374-
375-
propTypes: {
376-
thread: ReactPropTypes.object,
377-
currentThreadID: ReactPropTypes.string
378-
},
379-
380-
render: function() {
381-
var thread = this.props.thread;
382-
var lastMessage = thread.get('messages').last();
383-
var dateString = (new Date(lastMessage.get('timestamp'))).toLocaleTimeString()
384-
return (
385-
<li
386-
className={cx({
387-
'thread-list-item': true,
388-
'active': thread.get('threadID') === this.props.currentThreadID
389-
})}
390-
onClick={this._onClick}>
391-
<h5 className="thread-name">{thread.get('threadName')}</h5>
392-
<div className="thread-time">
393-
{dateString}
394-
</div>
395-
<div className="thread-last-message">
396-
{lastMessage.get('text')}
397-
</div>
398-
</li>
399-
);
400-
},
401-
402-
_onClick: function() {
403-
var threadID = this.props.thread.get('threadID')
404-
if (this.props.currentThreadID !== threadID) {
405-
Chat.actions.clickThread(threadID);
406-
}
407-
}
408-
409-
});
410-
411-
module.exports = ThreadListItem;
412-
```
45+
## Examples
41346

47+
- **[Flux Chat Example](./examples/flux-chat)** - classic facebook flux chat example written in NuclearJS
48+
- **[Rest API Example](./examples/rest-api)** - shows how to deal with fetching data from an API using NuclearJS conventions
41449

41550
## Core Concepts
41651

0 commit comments

Comments
 (0)