Whitebox Plugin API Reference

This document provides comprehensive documentation for the Whitebox Plugin API that is exposed to federated plugins via the global window.Whitebox object.

The Whitebox API provides a set of utilities, components, and services that plugins can use to integrate with the Whitebox platform. All APIs are available through the global Whitebox object.

JSX Components & Hooks

useSlots()

React hook for accessing and managing component slots within the Whitebox ecosystem.

const { useSlots } = Whitebox;
const slots = useSlots();

---

useComponentSlots()

React hook for managing component-specific slots.

const { useComponentSlots } = Whitebox;
const componentSlots = useComponentSlots();

---

importWhiteboxComponent(componentName)

Dynamically imports a Whitebox component by name.

const { importWhiteboxComponent } = Whitebox;
const MyComponent = importWhiteboxComponent('ComponentName');

---

DynamicContentRenderer

Component for rendering dynamic content within the Whitebox system.

const { DynamicContentRenderer } = Whitebox;

const MyComponent = () => (
  <DynamicContentRenderer
      className="flex flex-col self-stretch items-center gap-4 text-center"
      html={stepHtmlTemplate}
      includeSlots
    />
);

---

SlotLoader

Component for loading and rendering slot-based content.

const { SlotLoader } = Whitebox;

const MyComponent = () => (
  <SlotLoader name="my-slot" />
);

Example Usage:

const { SlotLoader } = Whitebox;

const MapComponent = () => (
  <div>
    <SlotLoader name="traffic.markers" />
  </div>
);

---

Navigation

useNavigate()

React Router navigation hook for programmatic navigation.

const { useNavigate } = Whitebox;
const navigate = useNavigate();

// Navigate to a route
navigate('/dashboard');
navigate(-1); // Go back

---

API & HTTP

api

Object for api associated with the Whitebox platform.

const { api } = Whitebox;

const baseUrl = api.baseUrl; 
// "http://localhost:8000"

const staticUrl = api.getStaticUrl();
// "http://localhost:8000/static"

// ...and other API methods

apiUrl

Base URL for the Whitebox API.

const baseUrl = apiUrl; 
// "http://localhost:8000"

---

Socket Management

sockets.getSocket(socketName, create?)

Gets or creates a WebSocket connection.

// Get existing socket or create new one
const socket = Whitebox.sockets.getSocket('flight');

// Get existing socket only (throws if not found)
const socket = Whitebox.sockets.getSocket('flight', false);

---

sockets.addEventListener(socketName, eventName, callback)

Adds an event listener to a socket with automatic cleanup.

// Listen for messages
const removeListener = Whitebox.sockets.addEventListener(
  'flight', 
  'message', 
  (event) => {
    const data = JSON.parse(event.data);
    console.log('Received:', data);
  }
);

// Remove listener when component unmounts
useEffect(() => {
  return removeListener;
}, []);

Example Usage:

useEffect(() => {
  return Whitebox.sockets.addEventListener("flight", "message", (event) => {
    const data = JSON.parse(event.data);
    if (data.type === "location_update") {
      // Do something with the location update
    }
  });
}, [setWhiteboxCoordinates]);

---

Utilities

utils.buildStaticUrl(path)

Builds a URL for static assets.

const { utils } = Whitebox;
const imageUrl = utils.buildStaticUrl('/images/logo.png');
// "http://localhost:8000/images/logo.png"

---

utils.getClasses(...classNames)

Utility for combining CSS class names.

const { utils } = Whitebox;
const className = utils.getClasses('btn', null, 'btn-primary', false, '  active  ')
// "btn btn-primary active"

---

utils.getGenericClassNames(config)

Gets generic class names based on configuration.

const { utils } = Whitebox;

const config = {
  style: {
    color: 'red',
    size: 'lg',
    font_weight: 'bold',
    font_height: 'tight',
    classes: ['custom-class', 'another-class']
  }
};
const props = { className: 'external-class' };

const result = utils.getGenericClassNames({ config, props });
// [
//   'c_generic_element',
//   'text-red',
//   'text-lg',
//   'font-bold',
//   'leading-tight',
//   'custom-class',
//   'another-class',
//   'external-class'
// ]

---

utils.generateDynamicElement(config)

Generates a dynamic React element based on configuration.

const { utils } = Whitebox;

const config = {
  type: "Button",
  config: {
    children: [
      { type: "Icon", config: { /* ... */ } }
    ]
  }
};
utils.generateDynamicElement({ config, index: 0, someProp: "value" });

---

utils.registerComponentMap(componentMap)

Registers a component mapping for dynamic element generation.

const { utils } = Whitebox;

utils.registerComponentMap({
  'custom-button': CustomButtonComponent,
  'custom-input': CustomInputComponent
});

---

Toast Notifications

toasts

Zustand store hook for managing toast state.

const { toasts } = Whitebox;

// Get toast state and actions
const { state, actions } = toasts.useToastsStore();

// toast example
toasts.info({ message: `Info message visible for 5 seconds`, timeout: 5 });
toasts.success({ message: "User decided to skip device setup at " + Date.now() });
toasts.error({ message: "User decided to skip device setup at " + Date.now() });

---

Testing Utilities

utils.renderWithRouter(component, options?)

Renders a React component with router context for testing.

const { utils } = WhiteboxTest;

// In your test
utils.renderWithRouter(<MyComponent />);

expect(screen.getByText('My Component')).toBeInTheDocument();