Advanced : using event hooks

Getting Started Custom Formatting Roadmap
Search…
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
Error
{
    success: true,
    requests: [{apikey, dataURI, params, name, library}, {...}],
    data: {
        items: [{...}],
        collections: [{...}],
        deleted: [{...}]
    }
}
{
    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
    }
}
theme
Next - Customizations
Extension defaults
Last modified 6mo ago
Copy link
Outline
Extension events
Detail of the events
zotero-roam:ready
zotero-roam:menu-ready
zotero-roam:metadata-added
zotero-roam:notes-added
zotero-roam:update
zotero-roam:write