ONES.getExtensionContext

Read the current extension entry context or subscribe to changes. The extension defines its context shape; Wiki macros use WikiMacroContext. The generic provides TypeScript checking, not runtime conversion or validation.

Requirements

Usage	ONES	Web SDK
General extension context	6.101.0+	Use the SDK matching the environment
Wiki macro context described here	7.45.0+	@ones-open/web-sdk@0.0.20+

Signature

type SetState<T> = (context: T) => void
type Cleanup = () => void

interface ContextAPI {
  getExtensionContext<ExtensionContext = any>(): Promise<ExtensionContext>
  getExtensionContext<ExtensionContext = any>(setState: SetState<ExtensionContext>): Cleanup
}

SetState, Cleanup and ContextAPI illustrate the signature; they are not named SDK exports. Call ONES.getExtensionContext in your app.

Parameters and callback

Parameter	Type	Required	Description
ExtensionContext	Generic, defaults to any	No	The extension context type, such as WikiMacroContext
setState	(context: ExtensionContext) => void	No	Supplying it subscribes; omitting it reads once
Callback argument context	ExtensionContext	Supplied for every callback	The complete current context, not a patch or DOM event
Callback return value	void	—	Not consumed by the host; callbacks do not save data

Wiki macro callback fields include identity, document version, scene, platform, writable, customData, resources and toolbarState. See WikiMacroContext for every field and union type. No previous-value, error or other event arguments are supplied.

Returns

Invocation	Return type	Description
Without callback	Promise<ExtensionContext>	Reads once, without subscribing
With callback	Cleanup, or () => void	Synchronously returns a cleanup function, not a Promise
Calling cleanup	void	Removes this subscription; does not save, close or cancel editing

After subscription starts, the callback asynchronously receives current context, then receives updates when the host changes that entry's context. Do not assume a fixed frequency, count or one notification per save. Configuration, edit state, permissions and collaboration may trigger updates. App database changes do not automatically trigger them.

Call cleanup on component or page destruction. Do not use await on the subscription to obtain context; read it in the callback. Handle errors from any asynchronous business requests in your app.

Read context once

import { ONES } from '@ones-open/web-sdk'
import type { WikiMacroContext } from '@ones-open/web-sdk'

async function readContext() {
  const context = await ONES.getExtensionContext<WikiMacroContext>()
  console.log(context.customData, context.scene, context.writable)
  if (context.toolbarState.state === 'editing') {
    console.log(context.toolbarState.actionId, context.toolbarState.customParams)
  }
}

Subscribe to context

import { ONES } from '@ones-open/web-sdk'
import type { WikiMacroContext } from '@ones-open/web-sdk'

function onContextChange(context: WikiMacroContext): void {
  const canConfigure =
    context.scene === 'edit' && context.writable && context.toolbarState.state === 'init'
  console.log({ canConfigure, customData: context.customData, resources: context.resources })
}

const unsubscribe: () => void = ONES.getExtensionContext<WikiMacroContext>(onContextChange)
window.addEventListener('pagehide', unsubscribe, { once: true })
// In a single-page app, also call unsubscribe() when this component or entry is destroyed.

Use via external script

<script src="https://unpkg.com/@ones-open/web-sdk@0.0.20/dist/index.iife.js"></script>
<script>
  const unsubscribe = window.SDK.ONES.getExtensionContext(function (context) {
    console.log(context.scene, context.writable, context.customData)
  })
  window.addEventListener('pagehide', unsubscribe, { once: true })
</script>

Wiki macro scene notes

Reading and subscribing do not save the document or return card exportSpec. Render and edit entries can each subscribe to their instance. Public sharing, mobile and search do not run macros or emit callbacks. History supplies historical document configuration; disable configuration and business writes there. In normal viewing, writable: false does not by itself prohibit business operations; the app backend validates business permissions.