Widget Framework

A comprehensive framework for building OpenLearning widgets with reusable UI components, parent-window messaging, and configuration management.

Features

• Reusable UI Components: Pre-built, accessible components following the OpenLearning design system
• Parent Messaging: Secure two-way communication between widgets and parent applications
• Configuration Management: Type-safe widget configuration and setup
• TypeScript Support: Full TypeScript support with comprehensive type definitions
• Consistent Styling: CSS-based theming with customizable color variables

Installation

npm install @openlearning/widget-framework

Quick Start

1. Create Your Widget Component

import React from "react";
import { Button } from "@openlearning/widget-framework";
import "@openlearning/widget-framework/styles/button.css";

export function MyWidget() {
  return (
    <div>
      <h1>My First Widget</h1>
      <Button variant="round-filled">Get Started</Button>
    </div>
  );
}

2. Set Up the Learner View

import { createLearnerEntry } from "@openlearning/widget-framework";
import MyWidget from "./MyWidget";

createLearnerEntry(MyWidget);

3. Set Up the Setup View

import { createSetupEntry } from "@openlearning/widget-framework";
import MyWidgetSetup from "./MyWidgetSetup";

createSetupEntry(MyWidgetSetup, {
  // your default setup config
});

Core Features

UI Components

See COMPONENTS.md for full component documentation.

Development Tools

Use DevApp for development and testing:

import { DevApp } from "@openlearning/widget-framework";

export default function App() {
  return (
    <DevApp
      LearnerViewComponent={MyLearnerWidget}
      SetupViewComponent={MySetupWidget}
      defaultConfig={{}}
    />
  );
}

Project Setup

Define your widget project configuration:

import { defineWidgetProject } from "@openlearning/widget-framework";

export const widgetConfig = defineWidgetProject({
  id: "my-widget", 
  name: "My Widget",
  version: "1.0.0",
  /* ... more config ... */
});

Integration Guide

See INTEGRATION_GUIDE.md for practical examples and common patterns.

API Reference

createLearnerEntry(Component, defaultConfig?)

Renders a component as the learner view of your widget.

Parameters:

• Component - Your LearnerView React component
• defaultConfig (optional) - Default configuration to use when no config exists

Example:

createLearnerEntry(LearnerView, { /* your default config */ });

createSetupEntry(Component, defaultConfig)

Renders a component as the setup/configuration view of your widget.

Parameters:

• Component - Your SetupView React component
• defaultConfig - Default configuration to use when no config exists

Internal APIs

useParentApi(defaultConfig?)

Unified helper for setup data + parent messaging actions.

Parameters:

• defaultConfig (optional) - Used when init data has no config.

Returns:

• setupData - Current setup payload (or null until init)
• sendReady()
• sendSet(name, value)
• sendResize(height)
• sendShare(attachments, thumbnail)
• sendComplete()

useParentMessaging()

Hook for parent-window communication.

Signature:

useParentMessaging(onMessage: (message: ParentMessage) => void)

Returns: { sendMessage }

DevApp(props)

Development wrapper component for testing widget views.

defineWidgetProject(config)

Defines widget project configuration.

UI Components

Button

import { Button } from "@openlearning/widget-framework";
import "@openlearning/widget-framework/styles/button.css";

<Button 
  variant="round-filled"
  size="medium"
  icon={<MyIcon />}
  iconPosition="left"
  isLoading={false}
  fullWidth={false}
  onClick={handleClick}
>
  Click Me
</Button>

TypeScript Support

Full TypeScript support with type definitions:

import { 
  Button,
  type ButtonProps,
  type LearnerViewProps,
  type WidgetConfigBase 
} from "@openlearning/widget-framework";

Browser Support

• Chrome/Edge (latest 2 versions)
• Firefox (latest 2 versions)
• Safari (latest 2 versions)
• iOS Safari 12+
• Android 5+

Contributing

Contributions are welcome! Please follow these guidelines:

1. Create a feature branch
2. Make your changes
3. Write tests for new functionality
4. Submit a pull request

License

MIT

Support

For issues, questions, or feature requests, please contact the OpenLearning team.