How to Use Wijmo Controls in ReactJS Apps

Here's a quick introduction on how to use Wijmo controls in your ReactJS applications. As of Build 207, Wijmo officially supports ReactJS.

What is React?

React is Facebook's library for building user interfaces in JavaScript. React is unique and incredibly popular, so we won't spend any time discussing its details here. If you're interested in a quick introduction to React and a comparison between it and other frameworks and libraries, here's a great article on that topic: Angular 2 versus React.

How is React different from Angular?

React is not a full framework but “a JavaScript library for building user interfaces”. It's very different from Angular and most typical JavaScript frameworks.

Instead of adding support for custom tags and attributes in HTML markup, it builds and maintains virtual document trees, and synchronizes those with the browser’s actual DOM when necessary. The virtual trees are created using JavaScript or JSX (a JavaScript syntax extension that makes JavaScript look like HTML).

React uses components that manage their own state. Building complex UIs is a matter of composing components. Component logic is written in JavaScript (instead of templates), so you can keep your data intact through the entire app.

The listing below shows a very simple React application:


<script src="https://cdnjs.cloudflare.com/ajax/libs/react/15.1.0/react.js"></script>  
<script src="https://cdnjs.cloudflare.com/ajax/libs/react/15.1.0/react-dom.js"></script>  

<!-- JSX script -->  
<script src="https://cdnjs.cloudflare.com/ajax/libs/babel-core/5.6.16/browser.js"></script>  
<script type="text/babel">  

  var TodoList = React.createClass({  
    // TodoList component definition...  
    return <ul>{this.props.items.map(createItem)}</ul>;  
  });  
  var TodoApp = React.createClass({  
    // TodoApp component definition...  
    render: function() {  
      return (  
        <div>  
          <h3>TODO</h3>  
          <TodoList items={this.state.items} />  
        </div>  
      );  
    }  
  });  

  // render the app component into the browser  
  ReactDOM.render(<TodoApp />, mountNode);  
</script>

The application creates two components and renders the main one on the browser.

The script is written in JSX, which is transpiled into JavaScript on-the-fly using babel. This conversion could also be performed off-line during the build process.

One of the main ideas behind React is that of keeping a copy of the DOM using their own data structures. React applications work against this copy, and React takes care of applying the changes to the actual DOM. This can result in performance gains because React computes the differences between the DOMs and is smart about applying the changes.

Because React creates its own version of the DOM, using its own components, they can bypass the browser entirely and render the document themselves. This is the idea behind React Native, which can be used to create native applications for IOS and Android. Of course, if you choose that route then you won’t be able to use Wijmo or any other libraries that rely on “real” HTML.

How to use Wijmo in React applications

To use Wijmo in your React applications, start by adding references to React and Wijmo to your page, and then include the “wijmo.react.js” module which defines components that wrap the Wijmo controls. For example:

<head>  
    <title>Wijmo and React</title>  

    <!-- React -->  
    <script src="https://cdnjs.cloudflare.com/ajax/libs/react/15.1.0/react.js"></script>  
    <script src="https://cdnjs.cloudflare.com/ajax/libs/react/15.1.0/react-dom.js"></script>  

    <!--JSX/babel -->  
    <script src="https://cdnjs.cloudflare.com/ajax/libs/babel-core/5.6.16/browser.js"></script>  

    <!-- Wijmo -->  
    <link href="http://cdn.wijmo.com/5.latest/styles/wijmo.min.css" rel="stylesheet"/>  
    <script src="http://cdn.wijmo.com/5.latest/controls/wijmo.min.js"></script>  
    <script src="http://cdn.wijmo.com/5.latest/controls/wijmo.input.min.js"></script>  
    <script src="http://cdn.wijmo.com/5.latest/controls/wijmo.grid.min.js"></script>  

    <!--Wijmo/React interop -->  
    <script src="http://cdn.wijmo.com/5.latest/interop/react/wijmo.react.min.js"></script>  

    <!-- app scripts and styles -->  
    <link href="styles/app.css" rel="stylesheet"/>  
    <script src="scripts/app.js"></script>  
</head>

Now you can use the Wijmo components in your React application.

For example, this is some JSX that creates and binds a FlexGrid:

<Wj.FlexGrid  
    autoGenerateColumns={false}  
    columns={[  
        { binding: 'name', header: 'Name' },  
        { binding: 'sales', header: 'Sales', format: 'c0' },  
        { binding: 'expenses', header: 'Expenses', format: 'c0' },  
        { binding: 'active', header: 'Active' },  
        { binding: 'date', header: 'Date' }  
    ]}  
    itemsSource={this.state.view}>  
</Wj.FlexGrid>

The syntax is typical of JSX/React, and quite different from HTML/Angular.

Component and property names contain no hyphens (JSX is ultimately JavaScript). Values assigned to properties may be literals (enclosed in quotes) or they may be JavaScript values (enclosed in curly brackets).

In this example, we are setting the grid’s columns property to an array containing items with the column properties. There’s no need for special components to define grid columns.

Here’s another example that creates and binds a ComboBox control:

<Wj.ComboBox  
    text={this.state.view.currentItem.name}  
    itemsSource={this.state.names}  
    isEditable={true}  
    required={false}  
    placeholder="Name"  
    textChanged={this.nameChanged}>  
</Wj.ComboBox>

This example is interesting because it shows how to implement two-way binding. The text property of the ComboBox is automatically set when the current item changes. This is standard one-way binding, built-into React and the component.

When the user edits the text, the ComboBox does not automatically apply the new value to the bound data object. Instead, the component must handle the textChanged event and apply the new value itself. In this case, this is handled by the “nameChanged” method in the App component (which is the component that contains the ComboBox):

var App = React.createClass({  

  // initialize model:   
  getInitialState: function() {  
      return { names: names, view: view }  
  },  

  // two-way bindings  
  nameChanged: function(s, e) {  
    this.state.view.currentItem.name = s.text;  
    this.state.view.refresh();  
    this.forceUpdate();  
}

This is the standard way to implement two-way bindings in React applications. Handle change events and apply the new values by changing the component state.

Give it a try!

The “wijmo.react.js” file is officially supported and included with the Wijmo distribution:

Download Wijmo

You can see it in action in these samples:

We want your feedback!

React is “officially” supported by Wijmo. The “wijmo.react.js” file includes the controls available in Wijmo, but some features (like grid cell templates) are not added yet.

If you have any suggestions or requests, please send us your feedback!

MESCIUS inc.

comments powered by Disqus