@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:

``sh
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.)

`ruby
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

`jsx
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:

`jsx
import React from "react"
import {
UiExtensionDataContext,
UiExtensionItems,
} from "@planningcenter/add-ons"

export default function profileTabs({ personId, openTab }) {
return (


{({ id, iconUrl, title }) => (


{title}

`jsx
import React from "react"

import {
UiExtensionDataContext,
UiExtensionThirdPartyComponent,
} from "@planningcenter/add-ons"

export default function ProfileTabContent({ extensionId }) {
return (



)
}
`

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:

`jsx
// people.profile.custom_tab.jsx

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

const Text = "Text"

function App() {
return Hello world
}

self.onRender((root, args) => {
render(, root, () => root.mount())
})
`

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

$3

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:

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

In the Add-on:

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

)
}
`

$3

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.:

`jsx
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 (
<>
person: {person}

)
}
`

$3

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.:

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

Development

In this directory:

`sh
yarn global add yalc
yarn run build
yalc publish
`

In the consuming product directory:

`sh
yalc add @planningcenter/add-ons
`

$3

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):

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

$3

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

`sh


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:

`sh
yarn storybook
`

Deploying Storybook to Github Pages:

`sh
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`