# Advanced : Extension API

The extension exposes a global window object, `zoteroRoam`, which other extensions or `roam/js` code can interact with. For example, the extension has an official integration with [the Roam to LaTeX exporter](https://github.com/alixlahuec/latex-roam).

If you're looking for a specific functionality not listed here, please get in touch.

## Methods

<details>

<summary>[async] getBibEntries(citekeys)</summary>

This is the method [used by the Roam to LaTeX plugin](https://github.com/alixlahuec/latex-roam/blob/2257b03d174f47fb4d33ad3128d3a49ffc31fbdd/src/utils.js#L46).

**Args**

`citekeys` - an Array of item citekeys

**Returns**

The BibLaTeX entries for the specified items.

{% code overflow="wrap" %}

```latex
@article{blochImplementingSocialInterventions2021,
    title = {Implementing social interventions in primary care},
    volume = {193},
    rights = {© 2021 {CMA} Joule Inc. or its licensors. This is an Open Access article distributed in accordance with the terms of the Creative Commons Attribution ({CC} {BY}-{NC}-{ND} 4.0) licence, which permits use, distribution and reproduction in any medium, provided that the original publication is properly cited, the use is noncommercial (i.e., research or educational use), and no modifications or adaptations are made. See: https://creativecommons.org/licenses/by-nc-nd/4.0/},
    issn = {0820-3946, 1488-2329},
    url = {https://www.cmaj.ca/content/193/44/E1696},
    doi = {10.1503/cmaj.210229},
    abstract = {{KEY} {POINTS}
- Primary care–based social interventions offer an important means to mitigate threats to individual and community health posed by adverse social conditions.
- Effective interventions include those that target individual-level determinants, connections with community resources, community-focused partnerships and structures within health teams that affect equity.
- Accumulating evidence points to the positive impacts of social interventions on broad markers of health; however, most research in this area has focused on implementation and process measures, rather than outcomes.
- Some interventions require large, interdisciplinary health care resources to implement, but many are accessible to small group practices or individual providers.},
    pages = {E1696--E1701},
    number = {44},
    journaltitle = {{CMAJ}},
    author = {Bloch, Gary and Rozmovits, Linda},
    urldate = {2021-11-12},
    date = {2021-11-08},
    langid = {english},
    pmid = {34750179},
    keywords = {primary care, social prescribing},
}
```

{% endcode %}

**Usage**

{% code overflow="wrap" %}

```javascript
window.zoteroRoam.getBibEntries(["blochImplementingSocialInterventions2021"])
```

{% endcode %}

</details>

<details>

<summary>[async] getItemCitation(item, config)</summary>

**Args**

`item` - the targeted Zotero item

`config` (optional) - an object with additional parameters to control the citation format. Refer to [this section of the Zotero API documentation](https://www.zotero.org/support/dev/web_api/v3/basics#parameters_for_format_bib_includecontent_bib_includecontent_citation) for details.\
If none are provided, Zotero defaults will be used.

**Returns**

A reference for the item, formatted according to the parameters provided.

{% code overflow="wrap" %}

```
Agarwal, Payal, Rick Wang, Christopher Meaney, Sakina Walji, Ali Damji, Navsheer Gill Toor, Gina Yip, et al. “Sociodemographic Differences in Patient Experience with Virtual Care during COVID-19.” medRxiv, July 22, 2021. https://www.medrxiv.org/content/10.1101/2021.07.19.21260373v1.
```

{% endcode %}

**Usage**

{% code overflow="wrap" %}

```javascript
await window.zoteroRoam.getItemCitation({...})

await window.zoteroRoam.getItemCitation({...}, { linkwrap: 1, locale: "en-UK", style: "apa" })
```

{% endcode %}

</details>

<details>

<summary>getCollections(library)</summary>

**Args**

`library` - the path of the targeted Zotero library

**Returns**

The list of Zotero collections for the desired library (raw metadata). See [this gist from the Zotero team](https://gist.github.com/dstillman/0bc17ca64ee7d3bc9063) for an example.

**Usage**

```javascript
window.zoteroRoam.getCollections("users/123456")
```

</details>

<details>

<summary>getItems(select)</summary>

**Args**

`select` - the type of items to retrieve (default: `"all"`).

**Returns**

All items that match the selector, across all libraries that are currently being used (raw metadata). Each item type has its own metadata structure ; see [this gist from the Zotero team](https://gist.github.com/dstillman/f1030b9609aadc51ddec) for an example of a top-level item, for example.

**Usage**

```javascript
// All items
window.zoteroRoam.getItems()
window.zoteroRoam.getItems("all")

// Top-level items only
window.zoteroRoam.getItems("items")

// All children (annotations, notes, & PDFs)
window.zoteroRoam.getItems("children")

// All attachments (PDFs, screenshots, ...)
window.zoteroRoam.getItems("attachments")

// Annotations only
window.zoteroRoam.getItems("annotations")

// Notes only
window.zoteroRoam.getItems("notes")

// PDFs
window.zoteroRoam.getItems("pdfs")
```

</details>

<details>

<summary>getTags(library)</summary>

**Args**

`library` - the path of the targeted Zotero library

**Returns**

The transformed list of tags that exist in the specific Zotero library. Unlike most of the other methods, this is a data structure generated by the extension rather than obtained from the Zotero API directly.

It takes the form of a dictionary Object: keys are initials, values are an Array of groups of similar tags. It's best understood with an example:

{% code overflow="wrap" %}

```javascript
{
    "h": [
        {
            token: "housing",
            roam: [],
            zotero: [
                { tag: "HOUSING", links: {...}, meta: { type: 1, numItems: 13 } },
                { tag: "Housing", links: {...}, meta: { type: 1, numItems: 6 } },
                { tag: "housing", links: {...}, meta: { type: 0, numItems: 2 } }
            ]
        }
    ],
    "u": [
        {
            token: "urban design",
            roam: [],
            zotero: [
                { tag: "urban design", links: {...}, meta: { type: 0, numItems: 5 } }
            ]
        }
    ]
}
```

{% endcode %}

**Usage**

```javascript
window.zoteroRoam.getTags("users/123456")
```

</details>