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.

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

Methods

[async] getBibEntries(citekeys)

This is the method used by the Roam to LaTeX plugin.

Args

citekeys - an Array of item citekeys

Returns

The BibLaTeX entries for the specified items.

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

Usage

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

[async] getItemCitation(item, config)

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 for details. If none are provided, Zotero defaults will be used.

Returns

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

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.

Usage

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

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

getCollections(library)

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 for an example.

Usage

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

getItems(select)

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 for an example of a top-level item, for example.

Usage

// 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")

getTags(library)

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:

{
    "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 } }
            ]
        }
    ]
}

Usage

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