@planningcenter/add-ons v5.4.0

@planningcenter/add-ons

This package allows Planning Center apps to build hooks, called UI Extensions, to extend their UI. These UI Extensions are utilized by Planning Center add-ons (integrator apps) to enhance a Planning Center product with their own functionality.

Usage in Planning Center Products

To make Add-ons available in a Planning Center product, you'll need a few things:

1. Install this package:

   yarn add @planningcenter/add-ons

2. Create a UI Extension "Insertion Point" and add it to the list of valid Insertion Points here. (You'll have to make a Pull Request.)

   INSERTION_POINTS = %w[
     people.profile.custom_tab
     people.profile.info_section
   ].freeze

   Insertion points follow the format: PRODUCT_NAME.GENERAL_MODULE.SPECIFIC_PLACE

   Though there is no validation for the name, try to follow the format. :-)

3. Import add-ons styles

   import "@planningcenter/add-ons/dist/styles.css"

4. Insert a React component in your product view to render the UI Extensions for the new Insertion Point:

   import React from "react"
   import {
     UiExtensionDataContext,
     UiExtensionItems,
   } from "@planningcenter/add-ons"
   
   export default function profileTabs({ personId, openTab }) {
     return (
       <UiExtensionDataContext>
         <UiExtensionItems name="people.profile.custom_tab">
           {({ id, iconUrl, title }) => (
             <li key={id}>
               <div onClick={openTab}>
                 <img className="symbol" src={iconUrl} />
                 {title}
               </div>
             </li>
           )}
         </UiExtensionItems>
       </UiExtensionDataContext>
     )
   }

   How you render the UI Extension here is completely up to you; no third party code runs here.

5. Add another React component that renders the Add-on third-party content once it is triggered by your product:

   import React from "react"
   
   import {
     UiExtensionDataContext,
     UiExtensionThirdPartyComponent,
   } from "@planningcenter/add-ons"
   
   export default function ProfileTabContent({ extensionId }) {
     return (
       <UiExtensionDataContext currentExtensionId={extensionId}>
         <UiExtensionThirdPartyComponent />
       </UiExtensionDataContext>
     )
   }

Usage by Add-ons

This library takes care of rendering third-party React components, i.e. UI Extensions, in the remote-ui sandbox. There is a bit of boilerplate that every UI Extension will need to use to cooperate with the rendering process. Here is an example UI Extension component:

// people.profile.custom_tab.jsx

import React, { useEffect, useState } from "react"
import { render } from "@remote-ui/react"

const Text = "Text"

function App() {
  return <Text>Hello world</Text>
}

self.onRender((root, args) => {
  render(<App {...args} />, root, () => root.mount())
})

This boilerplate should be generated by add-ons-cli.

Arguments

Each UI Extension component get passed arguments, including any callbacks, from the host application. These arguments can be used to give the component additional needed context to do its job (remember that the sandboxed component runs in a Web Worker and has no access to the host environment).

On the host:

<UiExtensionThirdPartyComponent
  extensionId={extensionId}
  args={{
    hostOnClick: () => console.log("callback on host"),
  }}
/>

In the Add-on:

function App({ hostOnClick }) {
  return (
    <>
      <Button onClick={() => hostOnClick()} text="click me" />
    </>
  )
}

authenticatedFetch

A special function is made available on self inside the Add-on: authentictedFetch. The function can be used to make authenticated API calls to the Planning Center API, e.g.:

function App() {
  const [person, setPerson] = useState("")

  useEffect(async () => {
    if (!person.attributes) {
      authenticatedFetch("/people/v2/me")
        .then(({ data }) => {
          setPerson(data.attributes.first_name)
        })
        .catch((err) => {
          console.error(err)
          setPerson("error fetching person")
        })
    }
  }, [authenticatedFetch])

  return (
    <>
      <Text>person: {person}</Text>
    </>
  )
}

authenticatedIntegratorFetch

Another special function is made available on self inside the add-on: authentictedIntegratorFetch. The function can be used to make authenticated API calls to the Integrator's (the add-on author's) API, e.g.:

authenticatedIntegratorFetch("https://api.example.com/some/endpoint")
  .then(({ data }) => {
    // do something with response data
  })
  .catch((err) => {
    console.error(err)
  })
}

Development

In this directory:

yarn global add yalc
yarn run build
yalc publish

In the consuming product directory:

yalc add @planningcenter/add-ons

Automatically Updating Components

To shorten the feedback cycle when testing components in a product, you can use the following command (requires entr, which can be installed with brew or apt):

APP=people
find src -type f | entr -c -s "yarn run build && yalc publish && cd ../$APP && yalc update"

Putting Things Back

Depending on the product, it can be hard to undo what Yalc has done. The following one-liner seems to work in all cases:

# in the product directory
git checkout package.json; rm -rf node_modules; rm -rf .yalc; rm -f yalc.lock; rm -rf tmp/cache; rm -rf public/packs; yarn

Storybook

Running Storybook locally:

yarn storybook

Deploying Storybook to Github Pages:

yarn storybook:deploy

Production

To publish a new release:

1. Ensure yarn build succeeds.
2. Update the CHANGELOG.
3. Update the version in package.json. See versioning guidelines.
4. Create a new tagged release using pco make-github-release.

To publish a pre-release:

1. Check out the next branch and do a git reset --hard {your-branch}.
2. Update the version in package.json with a version like 1.4.0-rc.1.
3. Add that same version heading to the top of the changelog and commit those changes (on the next branch).
4. Force push the branch to GitHub: git push -f
5. Run pco make-github-release --prerelease --target next