Headline Widget Documentation

Authentication

All connections require a valid access token. The application uses OpenID Connect (OIDC) via Keycloak. When a user signs in through the main application, the access token is stored in sessionStorage and is automatically included in API and SSE requests by the widget.

SSE Connections

SSE connections are authenticated with an Authorization: Bearer <jwt> header. The widget handles this automatically when a token is stored in sessionStorage.

import { fetchEventSource } from '@microsoft/fetch-event-source'

fetchEventSource('/api/headlines/stream', {
  headers: { Authorization: 'Bearer ' + token },
  onmessage(event) { console.log(event.data); },
});

HTTP API Requests

Include an Authorization: Bearer <jwt> header. The built-in API client handles this automatically when a token is stored in sessionStorage.

Sign In / Sign Out

Quick Start

The easiest way to use the headline widget is via the global headline_listing function:

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

// Store token for automatic auth (optional)
sessionStorage.setItem('headlines_token', token)

// Initialize the widget
const widget = headline_listing(root, {
  criteria: { text_search: 'Fed' },
  audio_notifications: true
})

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

Installation

Option 1: ES Module Import

import { headline_listing } from '/lib/headline_listing.js'

const root = document.getElementById('headline-root')
headline_listing(root, { criteria: { text_search: 'Fed' } })

Option 2: SolidJS Integration

For SolidJS applications, import the component directly:

import { HeadlineListing, HeadlineCriteria } from '/lib/headline_listing.js'

function MyComponent() {
  const criteria = () => ({ text_search: 'Fed' })

  return (
    <div>
      <HeadlineListing criteria={criteria} audio_notifications={false} />
    </div>
  )
}

API Reference

headline_listing(root, props)

Render a headline widget into the specified DOM element.

Returns: WidgetInstance

HeadlineListingProps

Configuration options for the headline widget.

HeadlineCriteria

Filter criteria for headline listings. All fields are optional.

Examples

Basic Listing

const widget = headline_listing(root)

Search by Text

// Show only headlines containing "Fed"
const widget = headline_listing(root, {
  criteria: { text_search: 'Fed' }
})

With Audio Notifications

// Play a sound when new headlines arrive
const widget = headline_listing(root, {
  criteria: { text_search: 'ECB' },
  audio_notifications: true
})

SolidJS Integration

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

import { HeadlineListing, HeadlineCriteria, HeadlineListingWidgetProps } from '/lib/headline_listing.js'

// Use in your component
function App() {
  const criteria = () => ({ text_search: 'Fed' })
  const props = { criteria, audio_notifications: true }
  return <HeadlineListing {...props} />
}

Available Exports

Live Demo

This demo loads the headline_listing widget. Authentication is required — sign in above to load the demo.