@optro/ui-react NPM

Optro UI for Trello

npm

The Optro UI library makes creating new Trello Power-Ups with React easier than ever, with useful hooks, components and types such as:

Use React Hooks or JSX components using a Higher Order Component to access the Trello API (t).
Check the Optro License Status of a particular Member or Board using the Optro License API and automatically enable/disable features based on their subscription plan in Optro.

If you're looking for a way to build Trello Power-Ups with best practice built-in, check out our Power-Up Generator which will create you a new Power-Up from your command line.

Alternatively, an example of using the Trello Provider and Hooks can be found in the trello-powerup-full-sample repository

Installation

Before you can use the Optro UI, you need to install it:

# Using Yarn
yarn add @optro/ui-react

# Using NPM
npm install @optro/ui-react

Access the Trello API with React

Find out how to access the Trello API throughout your Power-Up using the TrelloProvider at the root level and then calling the useTrelloApi hook to access the client.

First, place the following code at the root of your project:

import {TrelloProvider} from '@optro/ui-react';
const t = window.TrelloPowerUp.iframe();

function ReactRoot() {
  return (
    <TrelloProvider t={t}>
      ...
    </TrelloProvider>
  );
}

Next, use the following React Hook which provides access to the Trello API in a component that is lower down the hierarchy:

import {useProvidedTrello} from '@optro/ui-react';

function ReactComponent() {
  const t = useProvidedTrello();
  // Use the Trello API
  t.showCard(item.card.id);
}

Adding monetization to your Power-up

Optro Market is the first central marketplace for Trello users to purchase paid features in Trello Power-Ups.

It is available for new and existing Power-Up vendors, but the steps will differ slightly as detailed below:

New Power-Up Vendor – we recommend building a Power-Up using the Generator which will integrate the monetization features. You can then use the Optro API Client to customize the implementation in your Power-Up and allow/disallow features and content based on the customer’s subscription status.
Existing Power-Up Vendor – you can easily integrate monetization into your Power-Up by registering with Optro Vendor , getting your API key, and making code-level changes as described below. These steps will enable you to seamlessly integrate your Power-Up into Optro.

Provide access to the Optro License status

Using the same pattern as the Trello API Provider, you can access the license status of members or boards from Optro.

First of all, add the LicenseProvider higher-order component (HOC) to the root of your React project (e.g. router):

import {LicenseProvider, TrelloProvider} from '@optro/ui-react';  
import {OptroLicenseApi} from '@optro/api-client';

// Create a caching Optro License API client
const optroClient = new OptroLicenseApi(
  OPTRO_API_KEY,
  POWERUP_ID
);

function ReactRoot() {
  return ( 
    <LicenseProvider
      apiKey={OPTRO_API_KEY}    // get it from vendor.optro.cloud
      powerupId={POWERUP_ID}     // get it from trello.com/power-ups/admin
      optroClient={optroClient}    // Optro API Client (see above)
      licenseType={'board'}     // License by 'board' or 'member' (less common)
    >
      ...
    </LicenseProvider>
  );
}

You can then access the license status of the board or member using the useLicense hook in any component further down the hierarchy:

import {useLicense} from '@optro/ui-react';

function ReactComponent() {
  const lic = useLicense();
  if(lic.licensed) {
    // we have a licensed user
  }
}

Conditionally Allow/Deny Features (Paywalling)

If you are making certain features subscription-only, you may want to hide, or render alternative content when the user does not have a valid subscription.

Using the LicenseConditional component, you can display different content based on the LicenseProvider data:

import {LicenseConditional} from '@optro/ui-react';

<LicenseConditional
  unlicensed={<div>This is rendered when the user is not licensed</div>}
>
  This is rendered when the user has a valid subscription
</LicenseConditional>

Display Licence Status

This component helps you indicate what level of subscription a customer has and provide an easy way for users to start a subscription, or manage their existing subscription.

LicenseStatus shows on screen the status of the current board or member license with a link to subscribe or manage their existing subscription:

import {LicenseStatus} from '@optro/ui-react';
import '@optro/ui-react/bundle.css';

// use the JSX element in your components
<LicenseStatus
    isPro={lic.licensed} // You can get this boolean from the useLicense() hook
    onGetPro={functionToCallOnUpsell} // You can call a function when the user wants to upgrade (e.g. direct to Optro Listing page)
    powerupId={yourPowerupId}
    locale={one of "en" | "de" | "fr" | "es"} // Trello provides window.locale for this
/>

Testing

Overriding the license status during development

During development you might wish to quickly switch between a licensed and unlicensed state to ensure correct functionality. This can be done using the overrideLicense property for the LicenseProvider component.

The overrideLicense property accepts the following values

'free' Any pro license returned from the API will be overridden.
'pro' The LicenseProvider component will behave as if there is currently an active pro license regardless of the API's response.
undefined when no value is defined the override will not be active