- Install the npm package:
npm install @brandfolder-panel/sdk
. - 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. - 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.
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>
);
}
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,
});
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>;
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;
});
Removes the Panel from the anchor element. The SDK object remains valid and can be used to initiate new operations.
Example:
panel.closePanel()