You're Invited:Meet the Socket Team at BlackHat and DEF CON in Las Vegas, Aug 7-8.RSVP
Socket
Socket
Sign inDemoInstall

@planningcenter/add-ons

Package Overview
Dependencies
Maintainers
0
Versions
112
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

@planningcenter/add-ons

Allow integrators to extend the UI of Planning Center products


Version published
Maintainers
0
Created

Readme

Source

@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

FAQs

Package last updated on 27 Jun 2024

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc