Sample PhoneGap App with ReactJS

ReactJS has been getting a lot of attention and recently I decided to dig in myself to see what all the hype is about. ReactJS comes from the developers at Facebook, which may contribute to the popularity of it due to being backed by a big company (think AngularJS and Google).

For the purposes of this post, I focused on two main goals: 1) get my feet wet with ReactJS and 2) write a sample hybrid app using it. I haven’t seen many hybrid samples using ReactJS around and figured it may help to share my findings with others interested as well.

Mobile UI Framework Choices

When looking into using a mobile UI framework, you should consider the different categories available and choose based on your needs and preferences. Below are some general categories of UI frameworks available when building for mobile:

1. Lightweight – frameworks that provide the CSS layer for the UI but have no specific JavaScript dependencies. Ratchet and Topcoat are some examples.
2. Responsive – frameworks built in a responsive manner but not necessarily designed for mobile specifically (Bootstrap, Foundation by Zurb).
3. Mimic Native SDK’s – JavaScript frameworks built to mimic the native SDK’s for mobile. These frameworks typically handle things like application state, view stacks, navigation and rich interactions along with a full set of mobile-optimized UI widgets using JavaScript. Ionic, Onsen UI, Kendo UI, jQuery Mobile and Sencha Touch for instance.

I personally prefer the 3rd type of UI framework when building my own apps and have been a huge fan of the Ionic Framework since discovering it. Since I’m building specifically for ReactJS in this case however, I started searching for what options were available based around React. I ran across TouchstoneJS and decided to give it a whirl.

TouchstoneJS – Mobile UI Framework for React

TouchsoneJS is an early stage project built by Thinkmill and is described as a:

“React.js powered UI framework for developing beautiful hybrid mobile apps.“

TouchstoneJS Features

Below is a list of high-level features:

• Mobile UI Components (comprehensive set including headers, lists, tabs, popups, form controls, buttons etc)
• Application State Management
• Navigation
• View Transitions
• View Stacks
• Optimized Animations
• Customizable Components

Sample App – iTunes Media Finder

To get started my sample I first cloned the TouchstoneJS starter project and went to work trying to figure out how it was built using the Touchstone framework since there currently aren’t any docs available.

For my sample app content, I decided to use the iTunes Search API again since I’ve created a few others using it with other UI frameworks and it’s a good use case for trying out various UI components (lists, form controls, navigation). The previous samples I built against the iTunes Search API are listed below for reference:

1. Ionic iTunes Explorer
2. Onsen UI iTunes Explorer
3. Twitter Bootstrap Sample (web-based)

My new iTunes ReactJS/TouchstoneJS app is available in my github account with instructions on how to use it. But I’ve also included this web app version below so you can try it out quickly:

(A fullscreen version is also available here.)

iTunes Media Finder – Sample Highlights

Below are a list of features my sample app contains along with some code snippets to show a bit of detail on how it’s done:

• Navigation – shows the use of titles, left/right buttons and action handling for switching between views

getNavigation (props,app) {
    return {
        title: 'Search Criteria',
        leftArrow: false,
        rightAction: () => { app.transitionTo('tabs:about', { transition: 'fade-expand' }) },
        rightIcon: 'ion-information-circled'
    }
}

• View Transitions – uses different types of transitions and ways to trigger them

     this.context.app.transitionTo('tabs:media-list',
  	{transition: 'show-from-right',viewProps:{prevView: 'criteria', mediaType: this.state.mediaType, searchTerm: this.state.searchTerm,
  	numResults: this.state.numResults}})
  

• Tabs – implements a simple tabbed interface

<UI.Tabs.Navigator>
    <UI.Tabs.Tab onTap={this.selectTab.bind(this, 'criteria')} selected={selectedTabSpan === 'criteria'}>
          <span className="Tabs-Icon Tabs-Icon--form" />
      <UI.Tabs.Label>Search Media</UI.Tabs.Label>
    </UI.Tabs.Tab>

   <UI.Tabs.Tab onTap={this.selectTab.bind(this, 'settings')} selected={selectedTabSpan === 'settings'}>
         <span className="Tabs-Icon Tabs-Icon--settings" />
       <UI.Tabs.Label>Preferences</UI.Tabs.Label>
   </UI.Tabs.Tab>
</UI.Tabs.Navigator>

• UI Controls – uses most of the UI controls available in the framework
• Loading Popup – shows the use of a spinner when loading the list of results

<UI.Popup visible={this.state.popup.visible}>
	<UI.PopupIcon name={this.state.popup.iconName} type={this.state.popup.iconType} spinning={this.state.popup.loading} />
	<div><strong>{this.state.popup.header}</strong></div>
</UI.Popup>

• Results Filtering – filters the results list with a matching string
• Alert – built-in animation property you can set to slide down/up upon show and hide

   <UI.Alertbar type={alertbar.type || 'default'} visible={alertbar.visible} animated>{alertbar.text}</UI.Alertbar>

   <UI.SearchField type="dark" value={this.state.filterString} onSubmit={this.submitFilter} onChange={this.updateFilter}
   onCancel={this.clearFilter} onClear={this.clearFilter} placeholder="Filter..." />

• Preferences support – ability so save settings between tabs
• Pre-configured – icons, splash screens, plugins and settings for Android and iOS already set in config.xml for your own reference.

Summary

The TouchstoneJS framework is still in early stages, lacks documentation and some features you may be looking for specifically (side menus, OS specific support, themes). However it does provide view navigation, a comprehensive set of UI widgets and application state out of the box and is definitely worth checking out if you want a jump start to building hybrid apps with ReactJS.

Their starter app and touchstonejs-tasks project are also really helpful for getting started quickly. If you use my sample iTunes app project or the TouchstoneJS starter project, it’s already configured to use the touchstonejs-tasks for taking care of the build process. The Thinkmill developers also wrote and included some other useful libraries for things like tap event handling, flexible layout containers and optimized tweens so you don’t have to worry about it.

If you run into any issues with my sample, please post to the issue tracker for the project and I’ll take a look. Also if you notice anything I could be doing better in it please submit a PR or mention in an issue. I’m still learning ReactJS myself and open to feedback :).

Resources

• React Europe Showbag – an open source set of projects developed by the authors of TouchstoneJS to build the ReactEurope 2015 conference app.
• React Developer Tools for Chrome – I highly recommend adding this to your Chrome Developer tools for debugging React apps.

Filed in: Cordova • Mobile Development • PhoneGap • ReactJS Tags: react cordova • react cordova sample • react hybrid • react mobile • react phonegap sample • reactjs • reactjs cordova • reactjs phonegap