Mr Branding: Sample PhoneGap App with ReactJS

Tuesday, September 22, 2015

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:

Lightweight – frameworks that provide the CSS layer for the UI but have no specific JavaScript dependencies. Ratchet and Topcoat are some examples.
Responsive – frameworks built in a responsive manner but not necessarily designed for mobile specifically (Bootstrap, Foundation by Zurb).
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.“

The creators of TouchstoneJS also created Elemental UI, a UI toolkit based around React.js for websites/apps, and KeystoneJS, an open source CMS and web application framework for Node.js apps you may also want to check out.

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:

These samples are a bit out of date and will be updated but you should still be able to get a general idea of how they’re used for now.

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.)

My sample uses JSONP to communicate with the iTunes Search API so it could be hosted as a web app too for easier sampling and avoid XHR issues.

One thing to make note of is that there are some things in the TouchstoneJS Starter project that are not in sync with the latest TouchstoneJS version at the moment but my sample IS in sync and I’ve made notes to things to be aware of in the code and README in the meantime.

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 – a set of projects including a mobile app created by the TouchstoneJS authors for the React Europe 2015 conference.
React Developer Tools for Chrome – I highly recommend adding this to your Chrome Developer tools for debugging React apps.

by Holly Schinsky via Devgirl's Weblog

Mr Branding