Calendar Widget Documentation

Quick Start

The easiest way to use the calendar widget is via the global calendar_listing function:

// Get a reference to a DOM element
const root = document.getElementById('calendar-listing')

// Initialize the widget
const widget = calendar_listing(root, {
  api_url: 'https://example.com',
  criteria: {
    occurs_from: '2025-12-18T00:00:00.000Z',
    occurs_to: '2025-12-18T23:59:59.999Z'
  }
})

// Later, to clean up:
widget.cleanup()

Live Demo

You must be signed in with the view role to use the live demo.

Installation

Option 1: ES Module Import

import { calendar_listing } from 'https://example.com/widget.es.js'

const root = document.getElementById('calendar-root')
calendar_listing(root, {
  criteria: {
    occurs_from: '2025-12-18T00:00:00.000Z',
    occurs_to: '2025-12-18T23:59:59.999Z'
  }
})

Option 2: SolidJS Integration

For SolidJS applications, import the component directly:

import { CalendarView, CalendarCriteria } from 'https://example.com/widget.es.js'

function MyComponent() {
  const criteria: CalendarCriteria = {
    occurs_from: '2025-12-18T00:00:00.000Z',
    occurs_to: '2025-12-18T23:59:59.999Z'
  }

  return (
    <div>
      <CalendarView criteria={criteria} />
    </div>
  )
}

API Reference

calendar_listing(root, props)

Render a calendar widget into the specified DOM element.

Parameter	Type	Required	Description
`root`	HTMLElement	Required	The DOM element to render the widget into
`props`	CalendarViewProps	Optional	Configuration options for the widget

Returns: `WidgetInstance`

Property	Type	Description
`cleanup()`	function	Removes the widget and cleans up resources

CalendarViewProps

Configuration options for the calendar widget.

Property	Type	Default	Description
`api_url`	string	BASE_URL	Base URL for the calendar API
`criteria`	CalendarCriteria	{}	Filters and search criteria for events
`show_header`	boolean	false	Show the calendar header with date picker and controls
`chart`	'mini'	off	Render a sparkline of the last 5 years of `actual` values to the right of each data row's figure. One batched history request per listing (`GET /api/calendar/entries/data`); hidden on narrow screens.
`get_token`	() => Promise<string \| null>	OIDC session	Token provider for machine (non-sign-in) users. Called before every request so short-lived client-credentials tokens can be refreshed. Overrides OIDC session auth when provided. See Machine Users below.

CalendarCriteria

Filter criteria for calendar events. All fields are optional.

Property	Type	Description
`by_category`	number \| null	Filter by category ID
`by_location`	string \| null	Filter by location code (e.g., 'US', 'UK', 'EU')
`text_query`	string \| null	Search events by text content
`by_classification`	Classification	Filter by event type: 'data', 'holiday', 'ad_hoc', 'expiry', 'speaker', 'supply', 'earning'
`occurs_from`	string \| null	Start date for date range filter (ISO format)
`occurs_to`	string \| null	End date for date range filter (ISO format)

Examples

Filter by Date Range

const widget = calendar_listing(root, {
  criteria: {
    occurs_from: '2025-12-18T00:00:00.000Z',
    occurs_to: '2025-12-18T23:59:59.999Z'
  }
})

Filter by Category

// Show only events from category ID 5
const widget = calendar_listing(root, {
  criteria: { by_category: 5 }
})

Filter by Location

// Show only US events
const widget = calendar_listing(root, {
  criteria: { by_location: 'US' }
})

// Show G20 major economies
const g20 = ['US', 'GB', 'EU', 'JP', 'DE', 'CN', 'FR', 'IT', 'CA', 'AU']
// Note: Use multiple widget instances or broader criteria for multiple locations

Search by Text

// Search for events containing "GDP"
const widget = calendar_listing(root, {
  criteria: { text_query: 'GDP' }
})

Filter by Event Type

// Show only economic data releases
const widget = calendar_listing(root, {
  criteria: { by_classification: 'data' }
})

// Show only holidays
const widget = calendar_listing(root, {
  criteria: { by_classification: 'holiday' }
})

Combined Filters

// Show US economic data for today
const widget = calendar_listing(root, {
  criteria: {
    occurs_from: '2025-12-18T00:00:00.000Z',
    occurs_to: '2025-12-18T23:59:59.999Z',
    by_location: 'US',
    by_classification: 'data'
  }
})

Custom API Endpoint

const widget = calendar_listing(root, {
  api_url: 'https://example.com/api',
  criteria: {
    occurs_from: '2025-12-18T00:00:00.000Z',
    occurs_to: '2025-12-18T23:59:59.999Z'
  }
})

Machine Users (No Sign-In)

For server-to-server or embedded integrations where no user signs in, the widget accepts a get_token callback instead of an OIDC session. Access is controlled by a dedicated Keycloak service-account client (OAuth2 client credentials grant), which your backend uses to mint short-lived access tokens.

Keycloak Setup (one per integration)

Step	Setting	Value
1. Create client	Client ID (example)	`calendar-widget-<customer>`
	Client authentication	On (confidential)
	Authentication flow	Service accounts roles only (client credentials grant)
2. Audience mapper	Client → Mappers → Add mapper → Audience	Included Client Audience = `calendar-client` (the API rejects tokens whose `aud`/`azp` does not match)
3. Grant access	Client → Service accounts roles → Assign role	`calendar-client` → `external-newsquawk-user` (maps to the `view` role)
4. Credentials	Client → Credentials tab	Client Secret — goes in your backend only, never in browser code

Token Flow

# Your backend mints tokens (client secret stays server-side)
POST https://<keycloak>/auth/realms/<realm>/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=calendar-widget-<customer>
&client_secret=<secret>

Embedding the Widget

Expose the short-lived token to your page via your backend (e.g. a small endpoint that returns the current token), then pass a callback. The widget calls it before every request, so expired tokens are refreshed transparently:

const widget = calendar_listing(root, {
  api_url: 'https://calendar.example.com',
  get_token: async () => {
    const response = await fetch('/api/calendar-token') // your backend
    const data = await response.json()
    return data.access_token
  },
  criteria: {
    occurs_from: '2025-12-18T00:00:00.000Z',
    occurs_to: '2025-12-18T23:59:59.999Z'
  }
})

Note: get_token is called on every listing request and on SSE (re)connects — have your backend cache the token and only re-mint near expiry.

SolidJS Integration

For SolidJS applications, you can import the component and types directly:

import {
  CalendarView,
  CalendarCriteria,
  CalendarViewProps,
  CalendarEvent,
  Classification
} from 'https://example.com/widget.es.js'

// Use in your component
function App() {
  const criteria: CalendarCriteria = {
    occurs_from: '2025-12-18T00:00:00.000Z',
    occurs_to: '2025-12-18T23:59:59.999Z',
    by_classification: 'data'
  }

  const props: CalendarViewProps = {
    api_url: 'https://example.com',
    criteria
  }

  return <CalendarView {...props} />
}

Available Exports

Export	Type	Description
`calendar_listing`	function	Framework-agnostic widget initializer
`CalendarView`	Component	SolidJS component for direct use
`CalendarViewProps`	interface	TypeScript interface for component props
`CalendarCriteria`	interface	TypeScript interface for filter criteria
`CalendarEvent`	type	Type for calendar event objects
`Classification`	type	Union type for event classifications
`create_calendar_store`	function	Low-level store for custom integrations