Millermedia-meteor-core NPM

millermedia-meteor-core

An npm package consisting of a set of screen and routing implementations for use with internal Miller Media Meteor projects.

Installation

Requires Meteor.js, React.js, and Onsen UI

From the root directory of your Meteor project, install the millermedia-meteor-core package:

$ meteor npm install --save millermedia-meteor-core

Components

The following React components are made available via this package:

App - A base component to render the entire app
BaseScreen - A base component to scaffold new screens
Client - A base class for the client singleton instance
startup - A startup function that applies common app fixes
Server - A base class for the server singleton instance
meteor_call - A wrapper function for Meteor.call(). Takes a Meteor method name and a data object and returns a Promise.

App

The App component will be the main component for your app. It serves as a wrapper for the Navigator component provided by the react-onsenui package.

Props:

initialRoute (array): An array of objects of the format { component: MyScreen }, where MyScreen is an extension of the BaseScreen component (detailed in the next section).
swipeable (bool): Enables swipe-to-pop functionality for iOS.

Methods:

renderRoute() - Given a route, render the page. Used in <Navigator/> component (Onsen UI) delivered via the main render method.
handleDeviceBackButton() - Handles the device back button. Will minimize the app when there is no current route.

BaseScreen

The BaseScreen component serves as a wrapper for the Page component provided by the react-onsenui package; however, it provides many built-in utility methods to simplify the implementation of screens deriving from it.

Props:

screenID (string): Optional. You can override the unique identifier for the screen. It's used internally to generate a pageClass property on the screen for CSS targeting. Defaults to the screenID specified by the Screen component itself.
theme (object): An object containing properties describing the main colors (using standard CSS values, e.g. '#ff0000' or 'red') to be used on the page, as follows:
- backgroundColor (string) - The toolbar background color (default '#ffffff')
- foregroundColor (string) - The toolbar foreground color (default '#ffffff or #333333, depending on the lightness of the background color).
- gradientStartColor (string) - The bottom color of the toolbar bottom-to-top gradient (defaults to a darkened version of the background color)
- gradientEndColor (string) - The top color of the toolbar bottom-to-top gradient (defaults to a lightened version of the background color)

Methods:

getScreenContent() - The main content output method. Returns a React component.
getTitle() - Returns a React component for display in the center of the main toolbar.
getToolbarLeft() - Returns a React component for display in the left of the main toolbar.
getToolbarRight() - Returns a React component for display in the right of the main toolbar.
getToolbar() - Returns a <Toolbar/> component (Onsen UI) containing the returned components from getTitle(), getToolbarLeft(), and getToolbarRight().
getToolbarBottom() - Returns a <BottomToolbar/> component (Onsen UI).
getPageProps() - Get additional props to pass to the <Page/> React component (Onsen UI), which wraps the content outputted by getScreenContent().
getActiveSubscreen() - Get the active screen in a sub navigation branch.
handleDeviceBackButton() - Handles the device back button. Will attempt to run this method for any active subscreen first.
trackView() - Allows screens to override how their views are tracked.
setStatusBar() - Allows screens to override how the StatusBar is styled.
onShow() - Callback for when screen is shown.
onShowHandler() - Callback for when screen is shown. Runs the trackView, setStatusBar, and onShow methods.
themeStyle() - Generates theme styles for this screen dynamically. Returns a React component containing a <style> block.
dom() - Get a handle on the current DOM for the active screen.
navigation() - Get the navigator for the active screen.

BaseTab

The BaseTab component serves as a wrapper for the Tabbar component provided by the react-onsenui package; however, it provides many built-in utility methods to simplify the implementation of screens deriving from it. It extends the 'BaseScreen` component.

Props:

screen (React.Component): Required. The screen instance that renders the tab screen.

Methods:

resetScreen() - Resets the active screen to a default state.
renderRoute() - Given a route, render the page. Used in <Navigator/> component (Onsen UI) delivered via the main render method.
getTabContent() - Returns a <Navigator/> component (Onsen UI).
getTabPageProps() - Get additional props to pass to the <Page/> React component (Onsen UI), which wraps the content outputted by getScreenContent().
screen() - Get the screen which contains the active tab.
tabbar() - Get the tab bar for the active screen.

TextSearchDelay

The TextSearchDelay component is a wrapper for the Input component provided by the OnsenUI framework. It will wait a configurable period of time after accepting input before performing a configurable operation on the received input value (e.g. perform a search).

Props:

value (string): The current input value. Should typically be set to a value stored in the parent component's state (default "").
wait_interval (number): The amount of time, in milliseconds, to wait before triggering the onChange method (default 2000).
className (string): The class name to pass to the Input component (default "").
placeholder (string): The placeholder text to show when the input field is empty (default "").
type (string): The input type (default text).
onChange (function): The function to run after the configured wait_interval. Takes the input value (string) as an argument.

Client

The Client class implements some standard functionality useful to all of our mobile apps:

readyForHCP() - Call this method on your client instance to indicate that hot code pushes can trigger the app to reload.
notReadyForHCP() - Call this method to indicated that hot code push should not trigger the app to reload.

The startup function should be used to start the app and apply some common fixes to mobile devices.

import { Client, startup } from 'millermedia-meteor-core';

const client = new Client;

startup(client, () => {
    // ready to render the App
});

Example Usage

Create a new Meteor project with React:

$ meteor create my-new-app --react && cd my-new-app

Install millermedia-meteor-core:

$ meteor npm install --save millermedia-meteor-core

Install any required peer dependencies (these will be listed during installation in the previous step):

$ meteor npm install --save onsenui react-onsenui {any other dependencies not listed here...}

Open /client/main.jsx and remove the following import statement:

import { App } from '/imports/ui/App';

In the same file, add the following import statements:

import onsen from 'onsenui';
import 'onsenui/css/onsenui.min.css'; 
import 'onsenui/css/onsen-css-components.min.css';
import { App, BaseScreen } from 'millermedia-meteor-core';

Add the following code to create two example screens that derive from BaseScreen:

class AboutScreen extends BaseScreen {
    screenID = 'about';
    title = 'About';

    getScreenContent = () => {
        return (
            <h1>About</h1>
        )
    }
}

class HomeScreen extends BaseScreen {
    screenID = 'home';
    title = 'Home';

    getScreenContent = () => {
        return (
            <div>
                <h1>Home</h1>
                <a 
                    href="#" 
                    onClick={
                        () => this.navigation.pushPage({ component: AboutScreen })
                    }>About</a>
            </div>
        )
    }
}

Replace the existing Meteor.startup() code block with the following:

Meteor.startup(() => {
    const initialRoute = [{ component: HomeScreen }];
    render(<App initialRoute={initialRoute} />, document.getElementById('react-target'));
});

Start the meteor server and visit localhost:3000 to view the results: