Hello Relacx

Here we have a React component named App and it renders a text in H1 tag.
The text to be rendered is passed in the props object.

To render a component in a DOM node, the render method is used.

App Ready

This is similar to the Hello Relacx tutorial. The difference is in the render method where the after render property is being used in the options parameter.
The after render method is triggered just after the Component is rendered.

Passing State

Passing state is as simple as passing props. In the options parameter of render method pass in the state object using state as key.

NOTE: state is available in the component in props, i.e
this.props.state

In the code you can see that the render method passes state with one property "time"
The time property is used in App as "this.props.state.time" which is furthur passed to the Clock component.

This may look the same as props but it is different, because state can be changed.
The next tutorial shows how to update the state.

Updating State

State changes are required when some action occurs. Actions can be anything like a button click, key press, mouse move etc.
Responding to actions requires controllers with functions in them for every action.

A controller in Relacx is created by the controller method. In the tutorial, a controller for the Clock component is being created. let ClockController = Relacx.controller(Clock); The ClockController can now be used to add actions to it using the addAction method.

To attach actions to the component, the action method in the controller; available in props; is used. this.props.controller.action("updateClick");

Action Listener

Action listeners are used to respond to actions outside the scope of the component.

In the code you can see the ClockController has an actionListener by the name "UPDATE_TIME".

    
        ClockController.addActionListener("UPDATE_TIME", function(){
            this.setState({
                time: new Date()
            });
        });
    

The action in this tutorial is triggered from the afterRender property in the render method.

Relacx.broadcastAction("UPDATE_TIME");

As mentioned in the docs, Action Listeners can also take the 1st parameter as an array of action names, the function attached to the action listener receives 2 parameters, the action name and some data associated with the action.
For this tutorial we did not need any data, nor we needed to check which action has been triggered since we are listening to only one action.

For more clarification here is a sample example:

    
        ClockController.addActionListener(["UPDATE_TIME", "RESET_TIME"], function(actionName, data){
            if(actionName === "UPDATE_TIME"){
                this.setState({
                    time: new Date()
                });
            }
        });
    

Broadcasting Action

In the previous tutorial we learnt how to broadcast an action and how to use an action listener to respond to the action.
In this tutorial we will learn how to create actions which automatically broadcast also.

In the code you can see a new component named NoteTime, this component will note down the time each time the clock is clicked.

This time instead of adding an action to the ClockController, we have added a broadcastAction.
This works the same way as an action, the only difference being that the name of the action is used to broadcast that action and whatevet the action returns is passed to all the action listeners listening to that action.

    
ClockController.addBroadcastAction("TIME_CLICK", function(){
    let currentTime = this.getState().time;
    return currentTime;
});
    

The code snippet above shows how to add a broadcast action, you can see it is the exact same as addAction method.

The NoteTime component has a controller named TimesNoteController with an action listener for "TIME_CLICK".
Whenever the TIME_CLICK action is performed, the returned data i.e the date object in this tutorial is available in the TimesNoteController's action listener for TIME_CLICK, and then that data is used by the controller to update it's component's state.

    
TimesNoteController.addActionListener("TIME_CLICK", function(action, data){
   var list = this.getState().list;
   list = list.slice();
   list.push(data);
   this.setState({
       list:list
   });
});

Update Parent State

So we have learned a lot about about Relacx and how you can attach actions to components, trigger actions, broadcast them, and update the state of the component.
Uptill now we have not discussed how the state is being managed in Relacx.

This is the only part in Relacx where you need to take care and it forms the basis of state management.

All the tutorials we have went through work just fine, but they do not affect the state of the parent,
If you go ahead and try creating a controller for the App component, which is our root component, and try to update the state of any child inside it, nothing will happen.
or if you try getting the state using the getState method, you will get back what you passed into the state object in render method and not the updated state.

This is because all the components inside the App component are independent of the parent's state. If you want to update the parent's state whenever the child state changes then you need to tell Relacx by passing the parent's reference in the parent object along with the path in the parent's state which will be updated by the child.

This tutorial works the same way as the previous one, note here when we are creating the Clock component in the App's render method.
This time there are 2 more properties being passed in the options parameter of component method.
parent and childPath

What these 2 properties tell Relacx is that :
1. The parent component of Clock is "this", i.e the App component
2. The state of the Clock component is in the property called "time" in the state of the parent component.

To understand this further, lets take another example.
Suppose the state in the render method of Relacx was the following:

    
    Relacx.render(App, document.getElementById("app"), {
        state:{
            clock:{
                    time : new Date(),
                    alarmOn: false
                  },
            notedTimes :{list:[]}
        }
    });

Then the clock instance in the render method of App would be as follow :

    
    let clock = Relacx.component(Clock, {
            state : {time:this.props.state.clock.time},
            parent: this,
            childPath : "clock.time"
    });
    

Note that the path is concatenated with the DOT operator ("clock.time").

So the childPath is simply the path in the parent's state where the child's state resides.
For instance, when you are creating components in a loop, your child path should contain the index of the data element.
Like "list.5", to reference the element at position 5 of the list.