Quick Start

Connection process

Connect your react app to any third party in three-step

1. Define the instantiate function
2. Define the get API function
3. Connect API to react by useAptor

---

1. Define the instantiate function.

construct.js

import Something from 'some-third-party'

export default function instantiate(node, params) {
  return new Something(node, params)
}

This function will return an instance of the third-party package. You have access to node (DOM-node*) and params.

The node is passed by react-aptor as a reference to DOM that is occasionally used as a wrapper for embedding UI. The DOM-node* will become more clear in the third step.

The params are optional parameters that are passed by react-aptor and define by you. see the third step. The params will be passed by you and will be more clear in third step.

name this file construct.js as convention ✨.

2. Define the get API function.

api.js

export default function getAPI(instance, params) {
  // return corresponding API Object
  return () => ({
    api_key: () => {
      /* api definition using instance and params */
      console.log(instance)
    },
  })
}

The react-aptor will pass the latest instance of your third-party which has been defined in the first step by instantiate function along with params to getAPI function.

The instance is returned instance of your third-party. Technically it is exactly going to be instantiate(node, params)

The params are optional parameters that are passed by react-aptor and define by you. see the third step. The params will be passed by you and will be more clear in third step.

name this file api.js as convention ✨.

3. Connect API to react by useAptor

connector.jsx

import useAptor from 'react-aptor'
import getAPI from './api'
import instantiate from './construct'

const Connector = (props, ref) => {
  const aptorRef = useAptor(ref, {
    getAPI,
    instantiate,
    /* params: anything */
  })

  return <div ref={aptorRef} />
}

export default React.forwardRef(Connector)

name this file connector.jsx as convention ✨ If you are using react 17 or newer version, you can also name it connector.js

hook in one look

useAptor hook in one look

const aptorRef = useAptor(ref, configuration, deps)

ref For the connection phase, you need to define a forwardRef component. The useAptor hook needs forwarded-ref as the first argument, this is necessary to bind all your defined api to this ref.

configuration As the configuration argument you need to pass defined instantiate (defined in the first step ☝️), getAPI (defined in the second step ☝️) and your custom params argument. The useAptor hook will return you a ref (aptorRef) which you can bind to your DOM node.

The params doesn't have any limitation, it can be any arbitrary type e.g. undefined, number, string or an object containing all of them. The params will be then passed to your instantiate and getAPI function, as you saw in the first and second steps. Params is the best place to connect props to your low-level api it means ”No Need” for extra function generation 🥳

deps Is the same as Dependencies array default value is [] but you can override it as the third and lat argument of useAptor. It maybe needed in situation which you want to force re-instantiate by some prop change. It will use shallow comparison (as react do) for deps array and will call your instantiate & getApI in a row.

API usage

consumer.jsx

const Main = () => {
  const ref = createRef()

  const apiKeyHandler = () => {
    if (ref.current) {
      ref.current.api_key()
    }
  }

  return (
    <div>
      <Connector ref={ref} />
      <Button onClick={apiKeyHandler}>api call</Button>
    </div>
  )
}