Skip to content

Latest commit

 

History

History
183 lines (126 loc) · 6.39 KB

base-store.md

File metadata and controls

183 lines (126 loc) · 6.39 KB
Raw

API docs FluxPlus.BaseStore

Back to index

The base store is a parent class you can use to create simple stores. They will register themselves with the dispatcher and handle FluxPlus.Action payloads. It also implements EventEmitter so your ReactJS controller views can listen to change events.

Please note you are welcome to extend on these stores for your own application framework. They are provided as a quick way to handle valid Action payloads.

Events

change

Emitted when either the stored entities or the active entity is changed.

See handleAction for more details.

Properties

string entityName

This is the name of the entities to check for.

When implementing a store based on the BaseStore class, you want to override this property with your value. It acts much like a selector to pick entities from incoming action payloads.

MyStore.prototype.entityName = "users";

This will instruct the base store to handle actions that contain users entities.

Methods

constructor (FluxPlus.Dispatcher dispatcher)

This creates a new BaseStore instance. The constructor will verify you have set the required property (entityName) and register itself with the provided dispatcher.

Note: you should only use one dispatcher per application. Do NOT instantiate a new Dispatcher for every store!

// This is a BAD idea!
var myStore = new MyStore(new FluxPlus.Dispatcher());

A better idea would be to use Browserify style modules to include your single Dispatcher instance.

// This will create our single Dispatcher instance.
module.exports = new FluxPlus.Dispatcher();

Then use this for your stores.

var Dispatcher = require('../the-dispatcher');
var myStore = new MyStore(Dispatcher);

mixed getActive ()

Returns the currently active entity. By default this value is null until actions are dispatched that set it to a different value.

mixed getOne (mixed id)

Returns a single entity based on the given ID.

If this ID is a scalar value (string, integer, etc.) it is assumed this is the same format as extractId() would return.

However if you provide an object the extractId() method will be called to do this for you. One use-case for this is if you have a composite primary key, but do not want to expose unique key generation logic to other parts of your code.

// Using composite keys with an obscure format.
MyStore.prototype.extractId = function(entity) {
  //Semicolon separator, particular ordering and case-insensitive productKey.
  return entity.categoryName + ';' + entity.productKey.toLowerCase()
};

// ...

// Fetches "Candy;choco-04" internally.
var product = myStore.getOne( {categoryName:"Candy", productKey:"CHOCO-04"} );

// What we avoided with this: having to know about the format.
var product = myStore.getOne( categoryName + ";" + productKey.toLowerCase() );

Array getAll ()

Returns a shallow clone of the entire store contents. This means you can manipulate the array without affecting the store. While manipulating the entities it contains would.

void handleAction (FluxPlus.Action action)

The default implementation for handling incoming actions. This method will be registered on the Dispatcher you provided to the constructor.

By default, this will do two things:

  1. The active entity may be updated by both ActionSource CLIENT and SERVER actions. See extractActive() for more details.
  2. Entity operations will only be performed for ActionSource.SERVER actions.

Either of these two will emit a change event.

If you would like to implement an optimistic store, for example when building a chat service. You will want to override this method so you can store data generated on the client, submit the data to the server and possibly roll back if the server returns an error.

Note: we discourage you from calling this method directly for any other purpose than unit testing. Use the dispatcher for this.

mixed extractId (object entity)

This method finds the unique identifier of an entity object. By default this checks for an id property. If your entities have a different identifier, you should override this method.

// Our primary key is called userId.
MyStore.prototype.extractId = function(entity) {
  return entity.userId;
};

mixed extractActive (FluxPlus.Action action)

This method finds out whether an action contains a new active entity for this store. By default this checks for an entity in the FluxPlus.Action.active property where the key is equal to the entityName of this store.

Since the current implementation of actives is still in drafting stages, feel free to override this method with your own filtering.

Return value should be false if there is no new active entity, any other value will be set as active. So to unset your active entity, this function should return null.

MyStore.prototype.extractActive = function(action) {
  
  // We want to look for specific action names.
  if(action.name == "UserTasks.setActive"){
    
    // And use a non-standard property on the action to store our active user.
    return action.activeUser;
    
  }
  
};

If you find yourself overriding this method a lot, please submit an issue and tell us about your use-cases. It will help us to find a good default implementation.