Ciphon host API

The Ciphon add-in is a set of web pages served from the Ciphon domain. A host application embeds them and drives them through JSON messages.

• Pages
• Channel
• Lifecycle
• Messages
• Types
• Methods
• Events
• Commands
• Dialogs
• Dock
• Host requirements

Pages

Parameters combine: /taskpane.html?dock&hide=match.

Channel

Define window.ciphonHost before the main page's scripts run.

interface CiphonHost {
  postMessage(message: object): void                                                   // page → host
  addEventListener(type: 'message', listener: (event: { data: object }) => void): void // host → page
}

Messages are JSON-serialisable objects in both directions. event.data is the message object.

Lifecycle

1. The host defines window.ciphonHost and loads /taskpane.html.
2. The page sends {event: "ready"}.
3. The page sends {event: "session", signedIn}, and again on every change.
4. Signed out, the page opens the sign-in and workspace dialogs.
5. The page calls methods. The host replies to each request.
6. A reload starts again at step 2.

Messages

type MethodName =
  | 'getActiveCell' | 'getSelection' | 'readRange' | 'readUsedRange' | 'getDocumentKey'
  | 'writeRange' | 'clearRange' | 'insertColumns' | 'deleteColumns' | 'autofitColumns'
  | 'setActiveCell' | 'selectRange'

// page → host
type Request = { id: number; method: MethodName; args: unknown[] }
type PageEvent =
  | { event: 'ready' }
  | { event: 'session'; signedIn: boolean }
  | { event: 'dock'; open: boolean; expanded: boolean; url: string }

// host → page
type Reply = { id: number; result: unknown } | { id: number; error: string }
type HostEvent = { event: 'selectionChanged' }
type Command = { command: 'extract' | 'match' | 'docs' | 'signIn' }
type Hide = { hide: ('extract' | 'match' | 'docs')[] }

• args are positional, in the order shown under Methods. Trailing optional arguments may be absent.
• Reply to every request with its id. result is null for methods that return nothing.
• error text is shown to the user.
• Accept messages only from pages on the add-in origin.

Types

type SheetRef = string | null          // worksheet name; null = active sheet
type CellValue = number | string | boolean | null

interface CellAddress { row: number; col: number }                        // 0-based
interface RangeAddress extends CellAddress { rowCount: number; colCount: number }

interface LocatedCell extends CellAddress {
  sheet: string                        // worksheet name
  sheetName: string
  address: string                      // display only, e.g. 'Trial Balance'!B4
}
interface LocatedRange extends LocatedCell { rowCount: number; colCount: number }

interface RangeContents {
  values: CellValue[][]                // rowCount x colCount
  text: string[][]
  formulas: (string | null)[][]
  styles: (StylePatch | null)[][]
}

interface UsedRange extends RangeContents {
  sheet: string
  sheetName: string
  origin: CellAddress
  rowCount: number
  colCount: number
}

interface RangeWrite {
  formulas?: (string | null)[][]
  values?: (CellValue | null)[][]
  numberFormat?: (string | null)[][]
  style?: StylePatch | (StylePatch | null)[][]
}

interface StylePatch {
  backColor?: string                   // '#RRGGBB' or CSS name; '' clears the fill
  foreColor?: string                   // '' resets to automatic
  font?: string                        // CSS shorthand, e.g. 'bold 11pt Calibri'
  formatter?: string                   // number format
  hAlign?: 'left' | 'center' | 'right' | 'general'
}

interface ClearTargets { data?: boolean; style?: boolean }  // both default to true

Cell values

Methods

Errors: unknown sheet → No such sheet: <name>; unknown method → Unknown method: <name>.

getActiveCell

getActiveCell(): LocatedCell

The active cell on the active sheet.

getSelection

getSelection(): LocatedRange

The first area of the selection on the active sheet.

readRange

readRange(sheet: SheetRef, range: RangeAddress): RangeContents

Dense matrices of range.rowCount x range.colCount.

readUsedRange

readUsedRange(sheet: SheetRef): UsedRange

Bounding box of cells holding a value or formula, with the same matrices as readRange; formatting-only cells are excluded. Empty sheet: origin {row: 0, col: 0}, rowCount 0, colCount 0, empty matrices.

getDocumentKey

getDocumentKey(): string

An identifier for the open document: the same for every page on it, and across sessions. Saved match reviews are stored under <key>/<sheet>; a document whose key changes starts without them.

writeRange

writeRange(sheet: SheetRef, at: CellAddress, write: RangeWrite): null

clearRange

clearRange(sheet: SheetRef, range: RangeAddress, targets?: ClearTargets): null

data clears contents, style clears formats, both clear everything.

insertColumns

insertColumns(sheet: SheetRef, startCol: number, count: number): null

Inserts entire columns at startCol, shifting right. count <= 0: no-op.

deleteColumns

deleteColumns(sheet: SheetRef, startCol: number, count: number): null

Deletes entire columns from startCol, shifting left. count <= 0: no-op.

autofitColumns

autofitColumns(sheet: SheetRef, range: RangeAddress): null

Autofits the range's columns to its cells.

setActiveCell

setActiveCell(sheet: SheetRef, at: CellAddress): null

Activates the sheet and selects the cell.

selectRange

selectRange(sheet: SheetRef, range: RangeAddress): null

Activates the sheet and selects the range.

Events

Commands

• Queue commands and hide until ready.
• A hidden action still runs by command.
• While a Ciphon dialog is open, commands are dropped with a message in the main page.
• Signed out, only the latest command received during sign-in runs. Closing a sign-in dialog drops it.
• hide lasts until the page reloads; the URL ?hide= then applies.

Dialogs

For window.open calls to the add-in origin, the host:

• Opens a separate window, sized from the requested width and height, including when no user gesture preceded the call.
• Keeps window.opener, so the dialog and the main page can postMessage each other.
• Shares cookies and storage with the main page.
• Closes the window when the dialog calls window.close().

Open other URLs outside the host.

Dock

The match review shows in a dialog while expanded, and as a banner in the main page while collapsed. A host with a dock loads /taskpane.html?dock, and the review shows in the dock instead.

• The dock page talks to the main page directly. It needs no window.ciphonHost.

Host requirements

• Every main page, dialog and dock page shares one cookie and storage profile.
• No user edit interleaves with a method call.
• The document is marked modified only after writeRange, clearRange, insertColumns, deleteColumns, autofitColumns.
• values of a formula cell hold its calculated result.
• formulas return exactly what was written, including text literals longer than 255 characters. Ciphon stores provenance as =IF("<escaped JSON>"="", 0, <value>); IF and DATE(y,m,d) evaluate.
• Sheets the host does not expose return No such sheet.
• Date-like strings in messages stay strings.