Using Flux Implementation

Lightweight flux implementation with the FE in mind and made to work with ReactJs. If using the Ajax template, then Backbone, underscore, and jQuery are needed as well.

Builds

Builds found in build/.

Source

Source found in src/.

Test script

There's a test JSX script found at test/src/test.jsx. Requires a node server to be running in order to test AJAX functionality.

node test/server.js

Then access in the browser.

http://127.0.0.1:4000/

API

• new Flux()
• .actions(qualifier) ⇒ Object.<string, function()>
• .actionWithContext(key, context, callback) ⇒ function
• .createActions(group, actions)
• .createStore(name, definition)
• .createTemplate(template, definition) ⇒ Template
• .dispatch(dispatchKey, data)
• .getStore(name) ⇒ Object
• .listenTo(context, callback) ⇒ function
• .setStores(args) ⇒ Object.<string, function()>

new Flux()

Creates a flux instance.

flux.actions(qualifier) ⇒ Object.<string, function()>

Retrieves actions based on a qualifier, where the qualifier is either an action group or store name.

Example:

// Create a store.
flux.createStore('MyStore', { increment: function() {} });

// Access actions from that store.
flux.actions('MyStore').increment();

Kind: instance method of Flux
Returns: Object.<string, function()> - A map of action methods that can be called directly with a payload.

Param	Type	Description
qualifier	string	Either or an action group or store name.

flux.actionWithContext(key, context, callback) ⇒ function

Helper method for actions that adds arbitrary contextual data to a dispatch when an action executes.

Example:

// Create a store with an event that listens for contextual data.
flux.createStore('MyStore', {
  update: flux.listenTo({mode: 'addition'}, function(payload) {
    // Add 'payload' to some state value.
  });
});

// Create a custom action that invokes a dispatch with contextual data.
flux.createActions('MyActions', function() {
  add: flux.actionWithContext('update', {mode: 'addition'}, function() {
    return 5;
  });
});

Kind: instance method of Flux
Returns: function - Proxy method that updates callback dispatch to include contextual data.

Param	Type	Description
key	string	Reference to key specified in store.
context	Object.<string, (string|number)>	Qualifying parameters for action context.
callback	function	Action body or logic.

flux.createActions(group, actions)

Entry point for creating a group of actions.

Example:

// Create a custom action.
flux.createActions('MyActions', function() {
  addValue: function(payload) {
    return payload;
  });
});

// Invoke the action 'addValue'.
flux.actions('MyActions').addValue(5);

Kind: instance method of Flux

Param	Type	Description
group	string	Identifier for the set of actions.
actions	Object.<string, function()>	The set of actions.

flux.createStore(name, definition)

Entry point for creating a store.

Example:

// Create a store with an event that updates the internal state of store.
flux.createStore('MyStore', {
  initialize: function() {
    return {
      value: 0
    };
  },
  increment: function(payload) {
    this.set('value', this.state.value + payload);
  }
});

Kind: instance method of Flux

Param	Type	Description
name	string	The name to use when identifying the store.
definition	Object.<string, function()>	The specification for the store containing events and configurations.

flux.createTemplate(template, definition) ⇒ Template

Uses a template in a store. Templates make it easier to define store behavior by applying custom logic to an event.

Example:

// Create backbone model that Flux.Ajax can utilize for making web requests.
var Accounts = Backbone.Model.extend({
  setUrl: function() {
    this.url = 'getAccounts';
  }
});

// Create a store that uses the Flux.Ajax template. This template can be
// used to perform GET and POST requests.
flux.createStore('MyStore', {
  searchAccounts: flux.createTemplate(Flux.Ajax, {
    // Use the backbone model defined above.
    model: Accounts,
    // Event hooks for applying additional custom behavior.
    onInit: function() {},
    onSuccess: function(payload) {
      // When request successfully completes, can perform custom logic.
      console.log(payload);
    },
    onFail: function(payload) {
      // When request fails to complete, can perform custom logic.
      console.log(payload);
    }
  })
});

// The store maintains an internal state for the template that is
// structured within the store like this:
> console.log(this.state.searchAccounts)
{
  model: Accounts,
  status: ACTION.UNINITIALIZED,
  error: null,
  errorType: null
}

// The template state can then be retrieved in a React component.
React.createClass({
  // Tells the component to which stores it should listen.
  mixins: [flux.setStores('MyStore')],

  // We manage the state of the component. Parameter 'states' is an
  // object containing the state of each store to which the component is
  // listening.
  syncStores: function(states) {
    console.log(states.MyStore.searchAccounts);
    this.setState(states);
  },

  render: function() {
    return null;
  }
});

Kind: instance method of Flux
Returns: Template - An instantiated instance of the template.

Param	Type	Description
template	Template	A subclass of Template defining the logic of the template.
definition	Object	Templates expose hooks that allow for customization. See template for outline of available hooks.

flux.dispatch(dispatchKey, data)

Dispatch an event from an action that stores listen to and consume.

Example:

// Create a custom action and then use 'this.dispatch' to asynchronously
// invoke a custom action.
flux.createActions('MyActions', function() {
  // Sometimes it makes sense to asynchronously invoke a dispatch. In this
  // situation use this.dispatch to invoke the dispatch.
  delayAdd: function(payload) {
    setTimeout(function() {
      // Using what's exposed on the method context.
      this.dispatch('addValue', payload);
      // Using Flux directly.
      Flux.dispatch(new DispatchKey('MyActions', payload));
    }, 2000);
  }
});

// Invoke the action 'delayValue'.
flux.actions('MyActions').delayValue(5);

Kind: instance method of Flux

Param	Type	Description
dispatchKey	DispatchKey	The dispatch identifier.
data	any	Dispatch payload that is often an {Object}.

flux.getStore(name) ⇒ Object

Retrieves the state of a store by name.

Example:

// Create a store.
flux.createStore('MyStore', {
  // Access another store and use that data in this store.
  copyValue: function() {
    var copy = flux.getStore('SecondaryStore').secondaryValue;
    ...
  }
});

Kind: instance method of Flux
Returns: Object - The state of the store.

Param	Type	Description
name	string	The name of the store.

flux.listenTo(context, callback) ⇒ function

Helper method for stores used for filtering dispatches by context.

Example:

// Create a store with an event that listens for contextual data.
flux.createStore('MyStore', {
  update: flux.listenTo({mode: 'addition'}, function(payload) {
    // Add 'payload' to some state value.
  })
});

// Create a custom action that invokes a dispatch with contextual data.
flux.createActions('MyActions', function() {
  add: flux.actionWithContext('update', {mode: 'addition'}, function() {
    return 5;
  })
});

Kind: instance method of Flux
Returns: function - Proxy for callback that implements context filtering.

Param	Type	Description
context	Object.<string, (string|number)>	The context by which the event should be filtered.
callback	function	Method to execute if context matches the context of the dispatch.

flux.setStores(args) ⇒ Object.<string, function()>

Helper utility enabling components to listen to updates from stores by returning React mixin that's added to the component.

Example:

// Create React component and then set a store on the component.
React.createClass({
  // Tells the component to which stores it should listen.
  mixins: [flux.setStores('MyStore')],

  syncStores: function(states) {
    ...
  },

  render: function() {
    ...
  }
});

Kind: instance method of Flux
Returns: Object.<string, function()> - Store hooks for react components.

Param	Type	Description
args	Array.<string>	A list of store names.