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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://alix-lahuec.gitbook.io/zotero-roam/v0.6/customization/custom-events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.