Skip to content

Latest commit

 

History

History
580 lines (401 loc) · 21.2 KB

GUIDE.md

File metadata and controls

580 lines (401 loc) · 21.2 KB
Raw

React-Ionic Guide

If you just got here and miss some context, check out the README first, and have a look at the React-Ionic site.

Routing

In most cases the routing definition will be the entry point of your app. React-Ionic uses react-router for routing.

The way you set up routing is not different from any other React app, there is no specific React-Ionic way of using the router.

A very basic example will look like this:

import ReactDOM from 'react-dom';
import React from 'react';
import { Router, Route, IndexRoute } from "react-router";
import createBrowserHistory from 'history/lib/createBrowserHistory';
import App from './components/app.jsx';
import Page from './components/page.jsx';

var main = function () {
  var history = createBrowserHistory();

  var routes = (
    <Route path="/" component={App}>
      <Route path="/page" component={Page}/>
    </Route>
 );

 ReactDOM.render(<Router history={history}>{routes}</Router>, document.getElementById('app'));
};

Then simply call main() or if you work with Meteor you need to run it with Meteor.startup():

if (typeof Meteor !== 'undefined') {
  Meteor.startup(main);
} else {
  main();
}

See the kitchensink router for a more extensive example.

Important: For React-Ionic to work properly with React-router it is required that IonBody has access to the this.props.location property (which is set by React-router to the top level Route component: the component that included IonBody). This can be accomplished by passing this.props.location as a prop to IonBody in your top-level route component:

return (
  <IonBody location={this.props.location} >
    { this.props.children }
  </IonBody>
);

Layout Structure

The overall structure of a typical app will be like: App > Layout > Page.

Where App contains IonBody, Layout contains IonHeaderBar and IonView (or the navigation versions of it, see below), and the Page contains IonContent wrapped around the actual content.

This multi-layer approach allows for creating one or more templates for multiple pages that share similar design, functionality, state, layout etc.

The actual Page component will the inserted into the IonView component by the router as this.props.children. The same is true for embedding the Layout into the IonBody component.

For actual examples of this approach see: App > Layout > Page.

Navigation

The Navigation components ensure that page transitions are animated following the iOS or Android requirements.

Navigation is usually placed in a layout component (see above) inside the IonBody. It typically looks like this:

<IonNavBar customClasses="bar-dark"
           title={headerTitle}
           leftButton={backButton}
/>

<IonNavView>
  <IonView>
    {this.props.children}
  </IonView>
</IonNavView>

Where the backButton is created from the IonNavBackButton component:

var backButton = (
  <IonNavBackButton icon="ion-ios-arrow-back"
                    color=""
                    type="clear"
                    history={this.props.history}
                    customClasses="button-stage"
  />
);

A complete example can be found here.

Global States

The full list of global states is:

ionNavDirection
ionModal
ionPopover
ionActionSheet
ionPopup
ionBackdrop
ionLoading
ionKeyboardHeight
ionHasTabs
ionHasTabsTop
ionHasHeader
ionHasSubheader
ionHasFooter
ionHasSubfooter
ionSnapper  // deprecated
ionGetSnapper
ionKeyboard

About most of them you don't need to bother, but they are all accessible like "props" (i.e. read-only) through context.

For example, to read the state of ionKeyboardHeight in your component add this:

contextTypes: {
  ionKeyboardHeight: React.PropTypes.number
},

and read it like:

this.context.ionKeyboardHeight

The use of the relevant states in your app is explained in the appropriate sections below.

Global Methods

The full list of global methods is:

ionSetTransitionDirection
ionShowModal
ionUpdateActionSheet
ionUpdatePopup
ionShowBackdrop
ionShowLoading
ionUpdateHasX
ionSetSnapper
ionShowPopover

These methods are also accessible though context like:

contextTypes: {
  ionShowBackdrop: React.PropTypes.func
},

and call it like:

this.context.ionShowBackdrop(true);

The use of the relevant methods is explained in more detail in the components section below.

Components

Action Sheet

The Action Sheet is a slide-up pane that lets the user choose from a set of options. Dangerous options are highlighted in red and made obvious.

How to use

First define the actionSheet object, e.g.:

var actionSheet = {
  titleText: 'ActionSheet Demo',
  destructiveText: 'Delete',
  cancelText: 'Cancel',
  buttons: [
    { text: <span>Share <i className="icon ion-share"></i></span> },
    { text: <span>Move <i className="icon ion-arrow-move"></i></span> },
  ],
  cancel: function() {
    console.log('Cancelled!');
  },
  buttonClicked: function(index) {
    if (index === 0) {
      console.log('Shared!');
    }
    if (index === 1) {
      console.log('Moved!');
    }
    return true;
  },
  destructiveButtonClicked: function() {
    console.log('Destructive Action!');
    return true;
  }
};

Then, to activate the actionSheet, simply call the ionUpdateActionSheet method:

contextTypes: {
  ionUpdateActionSheet: React.PropTypes.func
},

and

this.context.ionUpdateActionSheet(actionSheet)

More information

Backdrop

Shows and hides a backdrop over the UI. Appears behind popups, loading, and other overlays.

How to use

// Method propagates from IonBody:
this.context.ionShowBackdrop(true); // or false

More information

Buttons

The full range of button options of Ionic is supported next to either onClick or "Link" behavior.

How to use

// As a link, using the "link" prop:
<IonButton  icon="ion-chevron-right"
            iconPosition="right"
            link="/next/page"
            color="dark"
            type="outline"
>Forward</IonButton>

// Call a function onClick:
<IonButton color="dark" 
           type="outline" 
           onClick={() => this.context.ionShowModal(false)}
>Close modal</IonButton>

More information

Form Elements

Some form elements don't have Ionic specific javascript functionality. React-Ionic includes the following components:

  • IonItemCheckbox
  • IonItemRadio
  • IonItemToggle

How to use

import { IonContent, IonList, IonItem, IonItemCheckBox, IonItemToggle, IonItemRadio, IonRange } from 'reactionic';
// for the full example check out the source link below

Headers & Footers

Headers are fixed regions at the top of a screen that can contain a title label, and left/right buttons for navigation or to carry out various actions.

Footers are regions at the bottom of a screen that can contain various types of content.

How to use

// To see it in context, have a look at the source of 
// the demo app, or at the layout section above.
<IonHeaderBar customClasses="with-class"
              title="About life"
              leftButton={leftHeaderButton}
              rightButton={null}
/>

// ....

<IonFooterBar><h1 className="title">The End</h1></IonFooterBar>

More information

Lists

The List is a common and simple way of displaying... that's right, a list. This is a widely used interface across most current mobile OS's, and can include content ranging from basic text all the way to buttons, toggles, icons, and thumbnails.

How to use

// Simple list with just one item
<IonList>
  <IonItem divider>List Icons</IonItem>
  <IonItem iconLeft>
    <IonIcon icon="email" />
    Check mail
  </IonItem>
</IonList>

More information

Loading

An overlay that can be used to indicate activity while blocking user interaction.

How to use

// See the demo source for more examples
<IonButton color="dark"
           type="outline"
           onClick={() => this.context.ionShowLoading(true, {
                            backdrop:false,
                            delay:0,
                            duration: 3000,
                            customTemplate:null
                          })}>Show Loading (3 sec)
</IonButton>

More information

Modal

The Modal is a content pane that can go over the user’s main view temporarily. Usually used for making a choice or editing an item.

How to use

// Define what is in the modal first (the modal contents etc.)
var DemoModal = React.createClass({
render() {
  return (
      <IonModal {...this.props}
              customTemplate={false}
              title="Some modal"
              barClasses="bar-dark"
              customClasses="">
        <div>Content goes here</div>
      </IonModal>
    );
  }
});

// Then open it like this:
var demoModal = <DemoModal {...this.props} />;

// ....

<IonButton color="dark" 
           type="outline" 
           onClick={() => this.context.ionShowModal(demoModal)}
>Open modal</IonButton>

More information

Popover

The Popover is a view that floats above an app’s content. Popovers provide an easy way to present or gather information from the user.

How to use

The popover is typically opened from the top-right header button. First define a component, say demoPopover, as a basic list:

<div className="content">
  <div className="list">
    <a className="item item-icon-right" href="https://facebook.github.io/react/" target="_blank">
      React
      <IonIcon icon="ios-arrow-right" />
    </a>            
    <a className="item item-icon-right" href="http://ionicframework.com/" target="_blank">
      Ionic
      <IonIcon icon="ios-arrow-right" />
    </a>
  </div>
</div>

Then add an onClick event on the button that will open the popover calling:

this.context.ionShowPopover(demoPopover)

More information

Popup

The Ionic Popup component allows programmatically creating and showing popup windows that require the user to respond in order to continue.

How to use

First define the Popup object, e.g.:

{
    popupType: 'show',
    title: 'A Popup',
    template: 'Here\'s a quick popup.',
    buttons: [{
      text: 'Close me',
      type: 'button-positive',
      onTap: function() {
                          console.log('Closed');
                        }
    }]
}

Then, to activate the Popup, simply call the ionUpdatePopup method:

this.context.ionUpdatePopup(popupObject)

For different Popup types see the example demo source code below.

More information

Side Menu

A container element for side menu(s) and the main content. Allows the left and/or right side menu to be toggled by dragging the main content area side to side.

How to use

The side-menu wraps two components inside the IonSideMenuContainer: IonSideMenus and IonSideMenuContent.

IonSideMenuContent contains the page content as it would for a normal page without side menus,

IonSideMenus contains the two actual side menus wrapped in the IonSideMenu component.

A complete example can be found here.

If only one side menu is desired. Or other Snap.js settings would like to be changed during the instantiation of the side menu/s then it is recommended to do so with passing the settings property to the SideMenuContainer object like below:

      <IonSideMenuContainer
        settings={{
          disable: 'right',
          hyperextensible: false,
        }}
        {...this.props}
      >

If disabling is desired of the snapper on certain components (slider input, google maps, etc) so that you can't swipe to open the menu then add the following to the surrounding <div>:

<div data-snap-ignore="true">
    ...
</div>

More information

Slide box

The Slide Box is a multi-page container where each page can be swiped or dragged between.

How to use

Simply add a div for each slide inside the IonSlideBox component like:

<IonSlideBox>
  <div className="slide-demo"><h3>Slide 1</h3></div>
  <div className="slide-demo dark"><h3>Slide 2</h3></div>
  <div className="slide-demo blue"><h3>Slide 3</h3></div>
</IonSlideBox>

More information

Spinner

The IonSpinner component provides a variety of animated spinners.

How to use

Depending on this.context.ionPlatform show one of these

<IonSpinner icon="ios" />
<IonSpinner icon="android" />

And there a are a few more spinners to choose from, see the demo source.

More information

Tabs

Tabs are a horizontal region of buttons or links that allow for a consistent navigation experience between screens. It can contain any combination of text and icons, and is a popular method for enabling mobile navigation.

How to use

<IonTabs platform={this.props.platform} 
         customClasses="tabs-light tabs-icon-top">
   <IonTab icon="ios-home" to="/tabs/one" label="Tab 1" />
   <IonTab icon="ios-star" to="/tabs/two" label="Tab 2" />
   <IonTab icon="ios-heart" to="/tabs/three" label="Tab 3" />
   <IonTab icon="ios-gear" to="/tabs/four" label="Tab 4" />
</IonTabs>

More information

Helpers

Platform

React-Ionic changes looks and feel depending on the platform (web, iOS or Android). For this to work you will have to set the platform property of IonBody.

The default platform object looks like this:

 platform: {
   isIOS: false,
   isAndroid: false,
   isCordova: false,
   transitionTimeOut: 450,
   name: 'Web'
 }

and is made available as a context: this.context.ionPlatform.

An example of how the platform object can be set dynamically is provided here (requires Meteor).

Timeouts

When using time-out in a React app, it's best to use something like this setTimeoutMixin mixing.

If you are working in a Meteor app, Meteor.setTimeout() will do as well.

Keyboard

React-Ionic makes use of a Cordova keyboard plugin for some direct keyboard manipulation and access. This keyboard helper is wrapping that plugin.

This IonKeyboard object is available as a context: this.context.ionKeyboard.