# Advanced : using event hooks

{% hint style="danger" %}
**This is an early-stage feature**. Use at your own risk, and only if you're familiar with JavaScript programming.
{% endhint %}

## 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        | <ul><li>The page's title</li><li>The page's UID</li><li>The Zotero item's DOI</li><li>The Zotero item's full metadata</li><li>The Zotero item's children</li><li>The Zotero item's Semantic Scholar citation data</li><li>The menu's HTML Element</li><li>The menu context (main view or sidebar)</li></ul> |
| **`zotero-roam:metadata-added`** | Metadata has been added to an item's page | <ul><li>The outcome of the operation (success ?)</li><li>The page's UID</li><li>The page's title</li><li>The Zotero item's full metadata</li><li>The blocks that the extension attempted to add</li></ul>                                                                                                   |
| **`zotero-roam:notes-added`**    | Notes have been added to an item's page   | <ul><li>The outcome of the operation (success ?)</li><li>The page's UID</li><li>The page's title</li><li>The Zotero item's full metadata</li><li>The notes that the extension attempted to add</li></ul>                                                                                                    |
| **`zotero-roam:update`**         | A data update request has completed       | <ul><li>The outcome of the update (success ?)</li><li>The requests that were sent</li><li>The data returned</li></ul>                                                                                                                                                                                       |
| **`zotero-roam:write`**          | A write request to Zotero has completed   | <ul><li>The target library</li><li>The target collection(s)</li><li>The item(s)' identifier(s)</li><li>The tags</li><li>The outcome of the operation (success ?)</li><li>The context of the import (cited/citing paper)</li></ul>                                                                           |

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

```javascript
{
    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

```javascript
{
    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

```javascript
{
    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

```javascript
{
    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

{% tabs %}
{% tab title="Success" %}

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

{% endtab %}

{% tab title="Error" %}

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

{% endtab %}
{% endtabs %}

### zotero-roam:write

```javascript
{
    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
    }
}
```