Exploring the React API - sameeri/Code-React GitHub Wiki

It's time to explore the React API.

Given, you have included React as a source in your web page/web application, React should be available as a global object, which is called.. React.

React

console.log('The React global object.', React);
console.log(window.React);
console.log('React and window.React are the same object', React === window.React);

This object, React is an object namespace, and exposes a bunch of functionality, as it's API. Since the primary focus of React is re-usable components, let's start there!

React.createClass()

ReactClass React.createClass(specificationObject)

React provides a function called createClass(). This method expects a component specification object, which has at the minimum, a render() method, on it. Thus the following two lines of code, would cause React to throw an error.

var ourComponent = React.createClass();//No input provided.
console.log(ourComponent);//Error would be thrown in the previous statement.
var ourComponent = React.createClass({});//An Empty specification object.
console.log(ourComponent);//Error would be thrown in the previous statement.

So, let's put a render() method on the object and see what happens..

var specificationObject = {render: function(){
}};
var ourComponent = React.createClass(specificationObject);
console.log(ourComponent);

\\Output of the console statement..
function (config, children) {
    // This factory should not be called when JSX is used. Use JSX instead.
    if ("production" !== "development") {
      warnForLegacyFactoryCall();
    }
    return factory.apply(this, arguments);
  }

ourComponent is a function. It takes two parameters, config and children. Let's see what happens if we invoke the function with nothing.

var ourComponentInvocation = ourComponent();
console.log(ourComponentInvocation);

It produces an object. This object is a ReactElement. It has the following properties on it.

{"key":null,"ref":null,"_owner":null,"_context":{},"_store":{"validated":false,"props":{}}}

Let's pass in a configuration object. This is a plain JavaScript object that would be configuring the component.

var ourComponentInvocation = ourComponent({name:"Sameeri", role: "Engineer"});
console.log(ourComponentInvocation);

The configuration object passed is stored as is, inside the ReactElement being created on the props property.

{"key":null,"ref":null,"_owner":null,"_context":{},"_store":{"validated":false,"props":{"name":"Sameeri","role":"Engineer"}}}

React.createElement()

ReactElement React.createElement(string/ReactClass type,
  [object props],
  [children ...])
```sh

The React.createClass() returns a function. It's a `ReactClass`. We can think of it as a JavaScript constructor function that can produce a lot of objects of a certain component type. 

React provides an API function to create an instance of a component, `React.createElement()`.
Let's see how to use this API call.

```js
var specificationObject = {render: function(){
}};
var ourComponent = React.createClass(specificationObject);
var ourComponentInstance = React.createElement(ourComponent);
console.log(ourComponentInstance);

The output is still a ReactElement, the same kind of object we got when we just invoked the component function. We could also pass the configuration object, as the second parameter.

var ourComponentInstance = React.createElement(ourComponent, {name:"sameeri"});

Creating HTML elements

React provides us a way to create many of the html elements as components. We could create a div element so

var div = React.createElement('div', null, 'Some text inside the div');

Understanding composition

We can create our components so.. Usually our component would be a composition of components. Like a ul with a list of items. Composition can be seen like this..

var childDiv = React.createElement('div', null, 'Child Div');
var parentContainer = React.createElement('div', null, childDiv, 'I am the parent container');

Hello World Component

Armed with this knowledge, let's create our component that displays "Hello World!" as a h1 tag on the screen.

var specificationObject = {render: function(){return React.createElement('h1', null, 'Hello World!'}};
var HelloWorldComponent = React.createClass(specificationObject);

This only creates a component specification. To make it appear on the screen, you would have to invoke another API method called React.render()

React.render()

 ReactComponent render(
  ReactElement element,
  DOMElement container,
  [function callback]
)

To actually display the component on the screen, we have to render it. The way React enables us to do this is via the React.render() method. React.render() expects an instance of a component, and where in the page it should render, that is a container element, so create an instance of your component and pass it to this method to make your component appear on screen.

var specificationObject = {render: function(){return React.createElement('h1', null, 'Hello World!'}};
var HelloWorldComponent = React.createClass(specificationObject);
var container = document.getElementById('container'); //assuming such an element exists in your page.
React.render(React.createElement(HelloWorldComponent), container);