React Blueprint
React Blueprint is a react-native insipred web app generator and tool set.
It uses the best libraries for React development without being too opinionated. We make no assumptions on how your app should look, but instead provide a strong architecture to build upon.
Included Libraries
- react
- react-router
- react-redux
- redux
- redux-thunk
- react-router-redux
- reselect
- radium
- babel
- webpack
- eslint
- sockjs-client
- superagent
- core-decorators
- lodash
Quick Start
Installation
- Install the command line interface -
npm i -g react-blueprint
- Generate your project -
react-blueprint init [app-name]
- Start your app -
cd [app-name] && npm start
The dev server will be running on localhost:3001
by default.
Removing Docs
Upon creation of your project, you will notice that these docs are rendered in your application. They have been included to provided some examples of usage. All the docs are located in src/components/Docs
. To remove the docs, open the projects main index at src/index.js
.
- Remove the import of
DocRoutes
on line24
- Change reference to
DocRoutes
toRoutes
on line42
When complete your new index should look as follows:
;;; ;;; ;; ;;; const store = ;const dest = document; // Enable Debuggerif __DEVELOPMENT__ windowReact = React; ; if __DEVTOOLS__ && !windowdevToolsExtension // Dev Render ; else // Production Render ;
At this point you can safely remove the Docs directory from src/components
and your app will be rendering the blank AppContainer located at src/containers/AppContainer
.
Examples
You can find example usage in the previously mentioned Docs
component. It has been structured to simulate the applcation structure (don't structure your components like this).
The main container component Docs
resides at src/components/Docs/containers/Docs.js
.
Generator
Commands
Generator Commands
Init
react-blueprint init [app-name]
- generates a React Blueprint project
NPM Commands
npm start
- Start the development server
npm run clean
- Cleans the build directory
npm run build
- Build the source files
npm run lint
- Lint the source files
npm test
- Run the test suite
File Structure
Static Directory
The static directory contains all your static assets. Images, fonts, stylesheets, and the index.html
.
Config Directory
The config directory contains your development and production config files. They are provided to your application via WebpackProvidePlugin
.
Source(src) Directory
The source directory contains all your application views and logic.
- actions - Redux actions
- components - Reusable components
- containers - Container components (components that act as route handlers)
- reducers - Redux store reducers
- selectors - Redux store selectors
- stores - There is only one store in a Redux app. This is kept in a directory to keep things uniform.
- utils - Various utilities including a websocket dispatcher, superagent request factory, custom decorators, LocalStorage middleware, style abstractions/variables and application copy centrailization.
Diagram of the tree structure:
.├── LICENSE├── README.md├── config│ ├── dev-config.js│ └── prod-config.js├── package.json├── src│ ├── actions│ │ ├── UIActions.js│ │ └── index.js│ ├── components│ │ ├── DevTools│ │ │ └── DevTools.js│ │ ├── Routes│ │ │ └── Routes.js│ │ └── index.js│ ├── containers│ │ ├── App│ │ │ └── App.js│ │ └── index.js│ ├── index.js│ ├── reducers│ │ ├── UIReducer.js│ │ └── index.js│ ├── selectors│ │ ├── RouteSelectors.js│ │ ├── UISelectors.js│ │ └── index.js│ ├── stores│ │ └── store.js│ └── utils│ ├── api.js│ ├── copy.js│ ├── decorators.js│ ├── index.js│ ├── localStorage.js│ ├── style.js│ └── websocket.js├── static│ ├── fonts│ │ ├── clearsans│ │ ├── clearsans_bold│ │ ├── clearsans_bold_italic│ │ ├── clearsans_italic│ │ ├── clearsans_light│ │ ├── clearsans_medium│ │ ├── clearsans_medium_italic│ │ ├── clearsans_thin│ │ └── fonts.css│ └── index.html├── webpack│ ├── dev.config.js│ ├── prod.config.js│ ├── webpack-dev-server.js│ └── webpack-isomorphic-tools.js└── webpack-assets.json
DevTools
React Blueprint is equipped with Redux DevTools increase visibility into and control of your applications state. All Redux actions are logged in the console using redux-logger.
In addition to the logger, we have provided Redux DevTools in the form of a panel overlay. See usage below:
Keybindings
H
Toggle the visibilty of the DevTools panelQ
Change the DevTools panel position
Components
React Blueprint components can be used independently of the project generator. If you generate a project using the React Blueprint CLI then the component library will be installed automatically. Otherwise install React Blueprint...
npm i react-blueprint --save
and import in your project
;
View
A flexbox component.
Examples
<View row> <View auto row> <View column width="100px"> <View className="red">Left</View> </View> <View column width="100px"> <View className="red">Left</View> </View> </View> <View row className="green">Hello test view</View></View>
<View column height="200px"> <View column auto> <View style= color: "green" height="20px">Green</View> <View style= color: "red" height="20px">Red</View> </View> <View style= color: "green" >Hello test view </View></View>
Props
All props are optional.
row
Bool - sets the flexDirection to row
column
Bool - sets the flexDirection to column
auto
Bool - sets the flex to '0 0 auto'
width
String | Number - width can be either a number
width={2}
, this acts asflex-grow
or a string with a unit (for example % or px)
it must be a valid css unit.
height
String | Number - sets the height of the component
it must be a valid css unit
className
String - className to apply to the component
style
Object - Will be merged the flex style. This allows you to override the style.
ScrollView
A scrolling view component with rendering optimizations. Based on react-infinite with some additions and optimizations.
Examples
Elements of Equal Height
- To use ScrollView with a list of elements you want to make scrollable, provide them to ScrollView as children.
Optimizations Disabled
- A simple ScrollView with no optimizations.
Elements of Varying Heights
- If not all of the children have the same height, you must provide an array of integers to the
elementHeight
prop instead.
useWindowAsScrollContainer
mode)
Using the Window to Scroll (- To use the entire window as a scroll container instead of just a single
div
(thus usingwindow.scrollY
instead of a DOM element'sscrollTop
), add theuseWindowAsScrollContainer
prop.
displayBottomUpwards
mode)
As A Chat or Message Box (- ScrollView now supports being used as a chat box, i.e. appended elements appear at the bottom when added, and the loading of the next page occurs when the user scrolls to the top of the container. To do so, simply add the
displayBottomUpwards
prop.
// insert messages for subsequent pages at this point
Note on Smooth Scrolling
- A wrapper
div
is applied that disables pointer events on the children for a default of 150 milliseconds after the last user scroll action for browsers with inertial scrolling. To configure this, settimeScrollStateLastsForAfterUserScrolls
.
Static Methods
Infinite.containerHeightScaleFactor(Number number)
Function - This function allows a value to be specified for
preloadBatchSize
andpreloadAdditionalHeight
that is a relative to the container height. Please see the documentation for those two props for further information on how to use it.
Instance Methods
scrollTo(Number top)
Function - This function will set the scrollTop of the
ScrollView
. Useful if you want to programatically set scroll position.
Props
children
React Node | [React Node] - The children of the
<ScrollView>
element are the components you want to render. This gives you as much flexibility as you need in the presentation of those components. Each child can be a different component if you desire. If you wish to render a set of children not all of which have the same height, you must map each component in the children array to an number representing its height and pass it in as theelementHeight
prop.
optimizeRendering
Bool - Defaults to
true
. SettingoptimizeRendering={false}
will keep your children rendered in the dom. TheelementHeight
prop can also be ignored.
⚠️ This is only intended to be used for simple applications where the scroll content is relatively small. You will experience limitations in this mode.
useWindowAsScrollContainer
Bool - Defaults to
false
. This option allows the window to be used as the scroll container, instead of an arbitrarydiv
, when it is set totrue
. This means that scroll position is detected bywindow.scrollY
instead of thescrollTop
of thediv
that ScrollView creates. Using this option is a way of achieving smoother scrolling on mobile before the problem is solved for containerdiv
s.
displayBottomUpwards
Bool - Defaults to
false
. This allows ScrollView to be used as a chatbox. This means that the scroll is stuck to the bottom by default, and the user scrolls up to the top of the container to load the next page. Thechildren
are displayed in the same order.
elementHeight
(Required) Number | [Number] - If each child element has the same height, you can pass a number representing that height as the
elementHeight
prop. If the children do not all have the same height, you can pass an array which is a map the children to numbers representing their heights to theelementHeight
prop.
containerHeight
Number - The height of the scrolling container in pixels. This is a required prop if
useWindowAsScrollContainer
is not set totrue
.
preloadBatchSize
Number | Object -
Defaults to
this.props.containerHeight * 0.5
. Imagine the total height of the scrollable divs. Now divide this equally into blockspreloadBatchSize
pixels high. Every time the container's scrollTop enters each of these blocks the set of elements rendered in full are those contained within the block and elements that are withinpreloadAdditionalHeight
above and below it. -
When working with the window as the scroll container, it is sometimes useful to specify a scale factor relative to the container height as the batch size, so your code does not need to know anything about the
window
. To do this, useInfinite.containerHeightScaleFactor
. So, for example, if you want the preloaded batch size to be twice the container height, writepreloadBatchSize={Infinite.containerHeightScaleFactor(2)}
.
preloadAdditionalHeight
Number | Object -
Defaults to
this.props.containerHeight
. The total height of the area in which elements are rendered in full is height of the current scroll block (seepreloadBatchSize
) as well aspreloadAdditionalHeight
above and below it. -
When working with the window as the scroll container, it is sometimes useful to specify this relative to the container height. If you want the preloaded additional height to be twice the container height, write
preloadAdditionalHeight={Infinite.containerHeightScaleFactor(2)}
. Please seepreloadBatchSize
for more details.
handleScroll(DOMNode node)
Function - Defaults to
function(){}
. A function that is called when the container is scrolled, i.e. when theonScroll
event of the infinite scrolling container is fired. The only argument passed to it is the native DOM Node of the scrolling container.
infiniteLoadBeginEdgeOffset
Number - Defaults to
undefined
, which means that infinite loading is disabled. To disable infinite loading, do not provide this property or set it to undefined.
Regular Mode
- When the user reaches this number of pixels from the bottom, the infinite load sequence will be triggered by showing the infinite load spinner delegate and calling the function
onInfiniteLoad
.
displayBottomUpwards
mode
- When the user reaches this number of pixels from the top of the container, the infinite load sequence will be triggered by showing the infinite loading spinner delegate at the top of the container and calling
onInfiniteLoad
.
onInfiniteLoad()
Function - Defaults to
function(){}
. This function is called when the scroll exceedsinfiniteLoadBeginEdgeOffset
. Before this function is called, the infinite loading spinner is automatically turned on.
You can set up infinite scrolling with this function like this:
- Fetch a new page of records from the appropriate API
- When the AJAX call returns, send the new list of elements (with the items that were just fetched) back as the children of ScrollView.
- Set ScrollView's
isInfiniteLoading
prop tofalse
to hide the loading spinner display
onInfiniteLoad
relies heavily on passing props as a means of communication in the style of idiomatic React.
loadingSpinnerDelegate
React Node - Defaults to
<div/>
. The element that is provided is used to render the loading view when ScrollView'sisInfiniteLoading
property is set totrue
. A React Node is anything that satisfiesReact.PropTypes.node
.
isInfiniteLoading
Bool - Defaults to
false
. This property determines whether the infinite spinner is showing.
timeScrollStateLastsForAfterUserScrolls
Number - Defaults to
150
(in milliseconds). On Apple and some other devices, scroll is inertial. This means that the window continues to scroll for several hundred milliseconds after anonScroll
event is fired. To prevent janky behavior, we do not wantpointer-events
to reactivate before the window has finished moving. Setting this parameter causes theInfinite
component to think that the user is still scrolling for the specified number of milliseconds after the lastonScroll
event is received.
className
String - Allows a CSS class to be set on the scrollable container.
Utilities
Dimensions
Dimensions
is a utiltiy that will get the width and height (including margin and borders) of a given element. You will need to ensure that your DOM is rendered before you can get the dimensions of a react element. However, Dimensions
also supports window
and document
and their dimensions can be accessed immediately. It can also be invoked as a decorator.
Usage as Method
Dimensions([ window || document || element ]);
returns
width: number height: number
Window or Document
/** * Window / Document example */ ;; { this; } { return <View width=thisstatewindowDimensionswidth height=thisstatewindowDimensionsheight> <p>width: thisstatedocumentDimensionswidth</p> <p>height: thisstatedocumentDimensionsheight</p> </View> ; }
React DOM Component
React now exposes the DOM element of their DOM components (div
, span
, p
, a
, etc) through this refs.
/** * React DOM Component Example */ ;; { let dimensions = ; this; } { return <div ref='container'> <p>width: thisstatedimensionswidth</p> <p>height: thisstatedimensionsheight</p> </div> ; }
Custom React Component
If you want to measure a custom component you will have to use ReactDOM.findDOMNode(this.refs.yourRef)
/** * Custom Component Example */ ;;; { let dimensions = ; this; } { return <View ref='container'> <p>width: thisstatedimensionswidth</p> <p>height: thisstatedimensionsheight</p> </View> ; }
Usage as Decorator
You can decorate your custom classes with Dimensions
and it will add a width
and a height
prop to your component. It also attaches a getDimensions()
method which will return the components width
and height
. Anytime the window is resized the new dimensions will be computed and made available via props.
/** * Decorated Component Example */ ;;; @Dimensions { return <View> <p>width: thispropswidth</p> <p>height: thispropsheight</p> </View> ; } { return <DecoratorExample ref="decoratorExample" /> } { return thisrefsdecoratorExample; }