README

tscr-jgintl contains scaffolding scripts for generating Jingoal internal service frontends. It is compatible with the generate-tscr package.

Usage

This package does not need to be installed directly. Instead you can specify it via an option flag to generate-tscr on the command line.

generate-tscr myproject --template tscr-jgintl.

This generates a directory called myproject and does several tasks for you:

- installs necessary dependencies (react, redux, type definitions, etc.)
- scaffolds a frontend template

The frontend template usess the jgintl-components library.

The jgintl-components library contains common components for a Jingoal internal service frontend (routing, authentication, UI structure, password changing, etc).

Routes

By default, the template will generate a src/routes.tsx file. You can modify this file to add your own app's routes. It includes the routes necessary for jgintl-components to work right out of the box.

It uses react-router to handle routing.

If you need to change the path to redirect to after a user authenticates, you can change the const afterLoginPath to your own path.

const afterLoginPath = '/';

You can change the default component that / points to by modifying the IndexRoute:

{/* Add application specific routes here */}
<IndexRoute component={InsertYourComponentHere}/>

To add routes, create them below the following line:

{/* Add application specific routes here */}

And add your routes directly underneath it. You can add a Route using the <Route/> component provided by react-router.

<Route path='your-path' component={YourPath}/>

You need to specify at least two props for a route to work:

- path
- component

Route Guarding

If you need to guard a route, you can pass a function to the onEnter prop of a <Route onEnter={YourGuard}/>. jgintl-components provides two guard factories:

- authGuard(redirect: string = '/login'): Returns a guard function that will redirect the user if they are not signed in.
- notAuthGuard(redirect: string = '/'): Returns a guard function that will redirect the user if they are signed in.

Redux

By default, the template will scaffold a Redux store that uses the BaseReducer function from jgintl-components. BaseReducer manages the base key of the state. The IBaseState interface contains defines the data structure under your state base key.

To add a reducer you can create a reducer file under src/reducers and import it into the src/store.ts file. To use the reducer you must pass it to the combineReducers() function:

import { createStore, combineReducers } from 'redux';
import { BaseReducer, IBaseState } from 'jgintl-components';
import { MyCustomReducer } from './reducers/MyCustomReducer';

interface IAppState extends IBaseState {}

const rootReducer = combineReducers({
    myStateBranch: MyCustomReducer,
    base: BaseReducer
});

export const store = createStore(rootReducer);

Creating Redux Components

jgintl-components ships with a default interface for actions (IAction). When creating an action you should define two things:

 - action type (in `src/actionTypes.ts`)
 - message interface (in `src/messages.ts`)

This os beneficial in two ways:

• using a constant for the action type prevents duplicating action type strings (error prone).
• creating an interface for your message lets your message handlers safely consume the message.

function handleMyAction(msg: MyActionMsg): IState {
    // Do stuff...
}

export function MyReducer(state: IState, action: IAction): IState {
    let msg = action.msg;
    switch (action.type) {
    case ActionType.MyAction:
        return this.handleMyAction(msg);
    default:
        return state;
    }
}

NOTE: This approach can be error prone if you don't correctly match the action type with the correct message handler signature.

Maintenance

You can update this package by making changes to the local directory and then calling:

npm run publish-patch

This does the following things:

- update the dependency version for jgintl-components to the latest version
- bump the patch version in the package.json file
- publish to NPM