Advanced : using event hooks

Attaching listeners to these events can allow automation of operations/workflows

This is an early-stage feature. Use at your own risk, and only if you're familiar with JavaScript programming.

Extension events

Event name	Triggered when...	Returns
zotero-roam:ready	Extension setup has completed	The extension's data store
zotero-roam:menu-ready	A page menu has finished rendering	The page's title The page's UID The Zotero item's DOI The Zotero item's full metadata The Zotero item's children The Zotero item's Semantic Scholar citation data The menu's HTML Element The menu context (main view or sidebar)
zotero-roam:metadata-added	Metadata has been added to an item's page	The outcome of the operation (success ?) The page's UID The page's title The Zotero item's full metadata The blocks that the extension attempted to add
zotero-roam:notes-added	Notes have been added to an item's page	The outcome of the operation (success ?) The page's UID The page's title The Zotero item's full metadata The notes that the extension attempted to add
zotero-roam:update	A data update request has completed	The outcome of the update (success ?) The requests that were sent The data returned
zotero-roam:write	A write request to Zotero has completed	The target library The target collection(s) The item(s)' identifier(s) The tags The outcome of the operation (success ?) The context of the import (cited/citing paper)

Detail of the events

The data returned for an event ev can be accessed through ev.detail.

See below for what is returned under different scenarios :

zotero-roam:ready

{
    items: [{...}], // The Zotero items requested
    libraries: [{...}], // The Zotero libraries requested
    keys: [{...}], // The Zotero API key(s) indicated, with their permissions
    collections: [{...}], // The collections for the Zotero libraries requested
    semantic: [],
    roamPages: []
}

zotero-roam:menu-ready

{
    title: '@citekey', // The Roam page title 
    item: {...}, // The item's full Zotero metadata
    doi: '10.xxx/xxxxx.xxxx', // The item's parsed DOI
    uid: 'aBCd123eF', // The Roam page UID
    children: {
        pdfItems: [{...}] | false, // Full metadata for the item's PDF files, if any
        notes: [{...}] | false // Full metadata for the item's notes, if any
    },
    // Data obtained for the item through the Semantic Scholar API
    semantic: {
        doi: '10.xxx/xxxxx.xxxx',
        data: {...}, // Semantic Scholar full metadata for the item
        citations: [{...}], // Processed metadata for citing papers, if any
        references: [{...}] // Processed metadata for references, if any
    },
    div: <Element>, // The DOM Element for the menu
    context: 'main' | 'sidebar'
}

zotero-roam:metadata-added

{
    success: true | false,
    title: '@citekey', // The Roam page title
    uid: 'aBCd123eF', // The Roam page UID
    meta: [...], // The metadata blocks to add
    item: {...} // The item's full Zotero metadata
}

zotero-roam:notes-added

{
    success: true | false,
    title: '@citekey', // The Roam page title
    uid: 'aBCd123eF', // The Roam page UID
    notes: [...], // The notes blocks to add
    item: {...} // The item's full Zotero metadata
}

zotero-roam:update

Success

{
    success: true,
    requests: [{apikey, dataURI, params, name, library}, {...}],
    data: {
        items: [{...}],
        collections: [{...}],
        deleted: [{...}]
    }
}

Error

{
    success: false,
    requests: [{apikey, dataURI, params, name, library}],
    data: null
}

zotero-roam:write

{
    library: {...},
    collections: [],
    tags: ['...'], // Array of tags to give the items
    identifiers: ['...'], // Array of identifiers (DOI/URL) to import
    outcome: {
        harvest: [{...}], // Wikimedia Citoids, for each identifier
        write: {
            success: true | false | null,
            data:      [{...}]   | undefined | undefined,
            response:  undefined | {...}     | undefined,
            error:     undefined | undefined | {...},
            identifiers: [...]
        }
    },
    context: {
        doi: '10.xxx/xxxxx.xxxx',
        key: 'citekey',
        type: 'citations' | 'references' // Type of panel where import triggered
    }
}