GithubHelp home page GithubHelp logo

gnoff / react-tunnel Goto Github PK

View Code? Open in Web Editor NEW
99.0 5.0 9.0 31 KB

React components and decorators for putting context-like values into context and pulling them out as props

License: MIT License

JavaScript 100.00%

react-tunnel's Introduction

react-tunnel

React components and decorators for putting context-like values into context and pulling them out as props

Heavily copied/modeled off the code used in react-redux by @gaearon

build status npm version npm downloads

Table of Contents

installation

npm install --save react-tunnel.

React Native

for React: require/import from react-tunnel.
For React Native: require/import from react-tunnel/native.

Quick Start

react-tunnel helps you provide injectable props to child components to help avoid deep chains of prop passing

  • install with npm install react-tunnel
  • import or require Provider and inject by
//es5
var Provider = require('react-tunnel').Provider;
var inject = require('react-tunnel').inject;

//es6
import { Provider, inject } from 'react-tunnel'
  • wrap a Component tree with <Provider provide={fn|object}> like
//using object provide
render() {
    return (
        <Provider provide={{thing: "one", anotherThing: 2}}>
          <Anything>
        </Provider>
    )
}

//or as a function
function provider () {
  return {
    thing: "one",
    anotherThing: 2g
  }
}

render() {
    return (
        <Provider provide={provider}>
          <Anything>
        </Provider>
    )
}
  • decorate a child component with inject and provide a mapping function determine which provided props to inject into the decorated component
var SomeChild = require('./SomeChildOfAnything') //a react Component

function mapProvidedToProps(provided) {
    return {
        that: provided.thing
    }
}

//notice that inject returns a wrapping function
var InjectedChild = inject(mapProvidedToProps)(SomeChild); 

// now in InjectedChild props will have `that`
...
render() {
    var injectedProp = this.props.that;
    return <span>{injectedProp}</span>;
    //will render as <span>one</span>
}

Best Practices

react-tunnel uses React's context feature to make provided props available to children regardless of how deep they are. While this is powerful it also can be abused and make for a nightmare to manage.

It is reccommended that this functionality be used to provide generally static properties that don't change much if at all based on the local conditions of the injecting component. Examples might include

  • Providing viewport dimensions to arbitrarily deep Components
  • Providing redux action creators from a parent connected Component to deep children

Also please consider that the context api for React has PropType checking for a reason and that by using this library and opting out of that stronger contract has costs and you may want to utilize the base context features rather than this library

API

<Provider provide>

makes provide available via context.provided to children of Provider. use inject to access them easily

Props

  • provide {fn | object}:
    • provide: function(parentProvided) { return provided{object} }: will provide the return value of provide prop. Function takes in any provided values from parent providers if any. If none, an empty object is passed.
    • provide: object: provides any parent provided values if nested along with provide object properties. if there is a key collision the properties of the provide prop are used and mask similarly named properties from any parent provided objects

Nesting

Providers are nestable and if using the object version of provide will automatically reprovide any values provided in the immediate parent Provider. Use this if you want to say Provide some truly global props at the root of your App but also use Providers for Redux action creators produced via connect to the local render tree.

If you nest Providers but use the function form of provide you will need to forward any desired parent provided values using the function forms argument parentProvided.

inject([mapProvidedToProps])

Creates a decorator which injects props from Provider into the decorated component according to the mapProvidedToProps function.

Arguments

  • mapProvidedToProps(provided)? returns object: called when decorated Component mounts and when it receives new context. the return object of this call is added to the underlying Component as props
  • default: if mapProvidedToProps is not passed to inject then all Provider values are passed to underlying component.

Thanks

License

MIT

react-tunnel's People

Contributors

gnoff avatar natew avatar nd0ut avatar rt2zz avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar

react-tunnel's Issues

New Provider Api

remove configuration props {forwardProvided, allowOverload}
Stop auto-providing arbitrary props on Provider

add new Provider prop: provide: (parentProvided) => provided | plainObject

if provide is a function it receives the the provided in context (only makes sense if this Provider is nested) and returns an object to be provided. It would be up to the caller to forward some/all/no parent provided values.

if the Provider is top level then parentProvided will be undefined

if provide is an object then that object will be provided in this provider. This means that to forward props from parent providers you must do so explicitly

Questions

  1. should provided forwarding happen by default?

shouldComponentUpdate issue

My injected component was not rerendering. I believe based on cursory review that inject should be using shallowEqualScalar on both provided and props (instead of shallow equal on just provided)

prop-types warning

Get this when using react-tunnel:

Warning: Accessing PropTypes via the main React package is deprecated. Use the prop-types package from npm instead.

from:

function createProvider(React) {
  var Component = React.Component;
  var PropTypes = React.PropTypes;

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.