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
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
}
}