@brandfolder-panel/sdk

panel-ui-sdk

This library was generated with Nx.

Running unit tests

Run nx test panel-ui-sdk to execute the unit tests via Jest.

Documentation

Getting started

1. Install the npm package: npm install @brandfolder-panel/sdk.
2. Import the stylesheet, found in @brandfolder-panel/sdk/styles.css, in your application. All styles are namespaced to .panel-ui-sdk so there should be no conflicts.
3. Initialize and start using the SDK.

Note: Because the Brandfolder PanelUI SDK renders the components inside of the consuming context, as opposed to within an iframe, all of its dependencies are currently included in the package. We will reassess and move libraries to become peer dependencies as needed.

Initialization

export interface PanelUISdkParameters {
  appName: string;
  anchorElement: HTMLElement; // Used to append the Iframe containing the Panel
  panelUIBaseUrl?: string; // OPTIONAL. Custom base URL if using a self-hosted version of the Panel
  headerBackgroundUrl?: string; // OPTIONAL. Custom background image url for the header
  // OPTIONAL. You can pass in a valid auth token that will be used for requests to the Brandfolder API. If this is
  // not passed in we will fallback to having the user input their API key.
  authParameters?: {
    token: string; // Valid OAuth token or API key
    refreshTokenHandler: () => Promise<string>; // Handler for fetching a new token if the initial one has become invalid. The SDK will call this function as needed.
  };
  statePersistence?: {
    enabled: boolean; // If true, the panel will persist its state in between uses
    storage?: Storage; // OPTIONAL. Allows consumer to pass in a custom storage implementation for persisting state
  };
  styles?: {
    backgroundColor?: string; // Background color for the panel,
    backgroundColorSecondary?: string; // Secondary background color for contrasted elements (i.e. hover styling)
  };
}

Example in React:

function App() {
  const ref = useRef();

  useEffect(() => {
    if (ref.current) {
      const sdk = new PanelUISdk({ appName: 'test', anchorElement: ref.current } });
      sdk.selectAttachments();
    }
  }, [])

  return (
    <div className="App">
      <div ref={ref} id='panel-root' />
    </div>
  );
}

PanelUISdk.selectAttachments

Opens the Panel on the Org landing page by default or on the show page if a Brandfolder or Collection ID is specified. Allows you to pass in a handler to listen for attachment selection events.

Arguments:

export interface SelectAttachmentProps {
  containerId?: string | null; // OPTIONAL - Navigate to specified Brandfolder or Collection, otherwise go to org landing page
  supportedMimeTypes?: string[]; // OPTIONAL - pass in a list of supported mime types
  onDragStart?: (attachment: AttachmentDto) => void; // Called when a user starts dragging an attachment
  onDragEnd?: (attachment: AttachmentDto) => void; // Called when a user stops dragging an attachment
  onSelect: (attachment: AttachmentDto) => void; // Called whenever user selects an attachment
  hideHeader?: boolean; // OPTIONAL - hides the header. Defaults to false.
  resumeSession?: boolean; // OPTIONAL - resume from persisted session
  searchParameters?: SearchParameters; // OPTIONAL - Use search parameters with Brandfolder API 
  enforcedSearchParameters?: EnforcedSearchParameters; // OPTIONAL - Enforce search parameters with Brandfolder API
};

Example:

panel.selectAttachments({
  containerId: 'VALID_BRANDFOLDER_ID',
  onSelect: (attachment) => console.log('Attachment selected: ', attachment),
  hideHeader: true,
});

Supporting drag and drop for Brandfolder attachments

The @brandfolder-panel/sdk/utilities namespace exposes utility functions that you can use to simplify how you consume drag and drop events originating from the Panel. It will take care of extracting the attachment data from the event and passing it to your handler.

Here are the available functions:

export function isAttachmentDragEvent(event: DragEvent): boolean => {...};

export function handleAttachmentDragEvent(
  event: DragEvent,
  handler: (props: AttachmentDragEventHandlerProps) => void,
): void => {...};

And here's an example of how you can use them in react:

const handleAttachmentDrag = (event: DragEvent) => {
  if (isAttachmentDragEvent(event)) {
    handleAttachmentDragEvent(event, ({ attachment }) => {
      console.log('Attachment dragged over drop zone: ', attachment);
    });
  }
};

return <div onDragOver={handleAttachmentDrag}>Drop Zone</div>;

PanelUISdk.openUpload

Opens the Panel on the Upload page. Allows you to pass in an array of objects with file blobs to be uploaded.

Arguments:

export interface ImageUploadPayload {
  file_name: string;
  file: Blob;
}

export interface OpenUploadProps {
  uploadAssets: ImageUploadPayload[]; // an array of file blobs with file names
  hideHeader?: boolean; // OPTIONAL - hides the header
}

Example:

panel.openUpload({
  uploadAssets: [{file_name: 'new-file', file: new Blob()}];
  hideHeader?: true;
});

PanelUISdk.closePanel

Removes the Panel from the anchor element. The SDK object remains valid and can be used to initiate new operations.

Example:

panel.closePanel()