Skip to content
This repository has been archived by the owner on Nov 27, 2018. It is now read-only.

Getting Started

Jump to bottom
Samuel Simões edited this page Mar 2, 2016 · 11 revisions

Fluxo provides to your app object and arrays wrappers to improve the state management, an important part of any javascript app today. In this tutorial we going to see how to create a simple app using it and React.js with a derivative Facebook Flux pattern.

💡 You can check and try this on the JSFiddle.

##The sample app

Let's create a super simple app that shows some person's name and has a button to change it like this:

At first glance you already are saying "I can do this with one line of vanilla JS", and ok, it can be done with one JS line, but this very simple example is only to show the most basic implementation of an app using Fluxo. This tutorial proposes a structured and predictable way to create dynamic apps that relies on an unidirectional data flow instead of "manually poke" DOM.

##Store

A good start point to our app is the instantiation of the person store that will hold the state of the person entity.

var personStore = new Fluxo.ObjectStore({ name: "Foo Name" });

Every time that I need change this store's data we'll invoke specific methods provided by Fluxo.ObjectStore to change this data. Example: if you need to set a new name you follow this:

personStore.setAttribute("name", "My new name");

All store's data lives on store's data attribute.

personStore.data.name // => "Foo Name"

##View layer

The view layer will present our state, which we are holding on the personStore instance created above.

It needs to follow three important rules.

  • It only presents the current state of the attached stores.
  • It need be ready to reload itself when the attached stores change.
  • It never changes the state/store directly. When our user execute some action on the view layer that needs change our state, it just calls a specific object (which we'll talk about soon) that have this competence.

On our app we'll use React.js to the view layer. To connect our stores on your React.js component you going to need FluxoReactConnectStores, the utility that makes this connection.

The FluxoReactConnectStores usage consist on calling it with your component and your stores.

The first argument is the component that you will connect and the second one is a literal object where the key is the store name and the value is the store instance. Look the example below:

var PersonComponent = React.createClass({
  render: function() {
    return (
      <div>
        <p><strong>Name:</strong> {this.props.person.name}</p>
        <button>Give new name!</button>
      </div>
    );
  }
});

var PersonComponentConnected = FluxoReactConnectStores(PersonComponent, { person: personStore });

React.render(<PersonComponentConnected/>, document.getElementById("app-container"));

As you can see our attached store's data will be available on the component's props upon the this.props.person (line 5).

Now, every time that you change the store's data, the component will receive the new state, which in React cause the re-render.

##Action layer

The action layer is where you should put the mediation code. Example: when our user click on a button on our view component that should give a new name to our presented person, this click event will invoke an action on the action layer that will mediate the intended result.

If you have a good eye you noticed that we have a unidirectional flow on our app expressed on the image below. This makes our app much more easy to understand and predict what some action will do, once we have the action routine on a specific place.

Fluxo hasn't any opinion or something like "action creator wrapper". We really believe that simple javascript objects can do this job quite well.

So we'll create a POJO to handle the Person actions:

var PersonActionHandler = {
  initialize: function (personStore) {
    this.personStore = personStore;
  },

  giveNewName: function (newName) {
    this.personStore.setAttribute("name", newName);
  }
};

PersonActionHandler.initialize(personStore);

As you can see we created our action handler with two actions, the initialize action, that we are calling right after on the object's creation and the giveNewName that receive one argument, a new name.

##Putting all together

Now we need to create the click handler on our component that gives a new name to the presented person.

This click handler will invoke an action on our previous created action handler.

var PersonComponent = React.createClass({
  onClick: function () {
    PersonActionHandler.giveNewName("A new name! " + new Date().toString());
  },

  render: function() {
    return (
      <div>
        <p><strong>Name:</strong> {this.props.person.name}</p>
        <button onClick={this.onClick}>Give new name!</button>
      </div>
    );
  }
});

var PersonComponentConnected = FluxoReactConnectStores(PersonComponent, { person: personStore });

React.render(<PersonComponentConnected/>, document.getElementById("app-container"));

Now you click on the button, the action giveNewName is called, the store is updated and emits the change signal and the view reacts on the changes presenting the new state. Awesome, isn't it?

And it is, a very simple app with Fluxo and React.js. I hope that you have understand and don't forget to read the full Fluxo documentation, React.js documentation and Facebook Flux documentation.

###Some examples

Clone this wiki locally