Helper functions

To help you write your own templates in JavaScript, the extension provides helper functions via a global object - zoteroRoam. You may have come across them in the Getting Started section, in the code for the default formatting function.

All available functions are described below ; note that the arguments item, pdfs, and notes correspond to the arguments your custom function receives from the extension.

// Let's say you're writing a custom function called myFunction
// It will be passed 3 arguments by the extension, in order:
// - item: the raw metadata for the Zotero item
// - pdfs: the raw metadata for the PDF(s) linked to the Zotero item
// - notes: the raw metadata for the notes/annotations linked to the Zotero item

window.myFunction = function(item, pdfs, notes){
    let metadata = [];
    
    // Inside of your function, you can use helpers like so:
    metadata.push(`Type:: ` + zoteroRoam.getItemType(item));
    if(notes.length > 0){
        metadata.push({
            string: "[[Notes]]",
            children: zoteroRoam.formatNotes(notes)
        })
    }
    
    return metadata;
}

List of functions

zoteroRoam.formatNotes(notes)

Args

notes - the notes/annotations linked to the Zotero item

Returns

The notes/annotations, formatted according to current user settings.

Usage

window.myFunction = function(item, pdfs, notes){
    let metadata = [];
    
    if(notes.length > 0){
        metadata.push({
            string: "[[Notes]]",
            children: zoteroRoam.formatNotes(notes)
        });
    }
    
    return metadata;
}

zoteroRoam.formatPDFs(pdfs)

Args

pdfs - the PDFs linked to the Zotero item

as - the format in which to return the PDFs' information. Values: string|links|identity . Default : "string".

Returns

The list of PDFs, according to the configuration provided.

Usage

window.myFunction = function(item, pdfs, notes){
    let metadata = [];
    
    if(pdfs.length > 0){
        // Default format: string
        // This will return the comma-separated list of the Markdown-style links to the PDF(s)
        // [Pdf title](URL), [Other Pdf title](URL)
        metadata.push("PDFs:: " + zoteroRoam.formatPDFs(pdfs));
        
        // If you only want the links & want the PDFs to be listed in sibling blocks, use the `links` format:
        metadata.push(...zoteroRoam.formatPDFs(pdfs, "links"));
        
        // If you want more control, use the `identity` format
        // It will return an Array of Objects, each with 3 properties:
        // title - the title of the PDF file
        // key - the Zotero key for the PDF
        // link - the link to the PDF
        const pdfList = zoteroRoam.formatPDFs(pdfs, "identity")
            .map(file => `[${file.title}](${file.link})`)
            .join(", ");
        metadata.push("PDFs:: " + pdfList);
    }
    
    return metadata;
}

zoteroRoam.getItemChildren(item)

You normally won't need to use this method, since your function will receive the item's PDFs and notes/annotations as arguments.

Args

item - the Zotero item

Returns

An Array containing the raw metadata of all the item's linked PDFs, notes, and annotations.

Usage

window.myFunction = function(item, pdfs, notes){
    let metadata = [];
    
    let children = zoteroRoam.getItemChildren(item);
    // ...
    // Do something with children
    // ...
    
    return metadata;
}

async zoteroRoam.getItemCitation(item)

Refer to the Zotero API documentation for details and accepted values.

Args

item - the Zotero item

config - additional configuration Object. Properties available :

• style - the citation style to use. Default : "chicago-note-bibliography".

• locale - the locale to use when generating the citation. Default : "en-US".

• linkwrap - whether URLs and DOIs should render as links. Values : 0|1. Default : 0.

Returns

A formatted citation for the item, according to the configuration provided.

Usage

window.myFunction = async function(item, pdfs, notes){
    let metadata = [];
    
    // By default, the function will use the Chicago Manual of Style 7th Edition (note), will not render URLs/DOIs as links, and will use en-US as the locale
    // Bloch, Gary, and Linda Rozmovits. “Implementing Social Interventions in Primary Care.” __CMAJ__ 193, no. 44 (November 8, 2021): E1696–1701. https://doi.org/10.1503/cmaj.210229.
    const citation = await zoteroRoam.getItemCitation(item);
    metadata.push("Citation:: " + citation);
    
    // You can also choose to use a different locale, if your chosen citation style supports it
    // Bloch, Gary, et Linda Rozmovits. « Implementing Social Interventions in Primary Care ». __CMAJ__ 193, n<sup>o</sup> 44 (8 novembre 2021): E1696‑1701. https://doi.org/10.1503/cmaj.210229.
    const frCitation = await zoteroRoam.getItemCitation(item, { locale: "fr-FR" });
    metadata.push("Citation:: " + frCitation);
    
    // You can also choose to use a different citation style
    // Bloch, G., & Rozmovits, L. (2021). Implementing social interventions in primary care. __CMAJ__, __193__(44), E1696–E1701. https://doi.org/10.1503/cmaj.210229
    const apaCitation = await zoteroRoam.getItemCitation(item, { style: "apa" });
    metadata.push("Citation:: " + apaCitation);
    
    return metadata;
}

zoteroRoam.getItemCollections(item)

Args

item - the Zotero item

config - additional configuration Object. Properties available:

• brackets : whether to surround the collection names in brackets. Values: true|false. Default : true.

• return_as : the format in which the collection names should be returned. Values: "string"|"array". Default: "string".

Returns

The names of the item's Zotero collections, formatted according to the configuration provided.

Usage

window.myFunc = function(item, pdfs, notes){
    let metadata = [];
    
    if(item.data.collections.length > 0){
        // By default, collection names will be in [[brackets]] and returned as a comma-separated list
        // [[Collection 1]], [[Collection 2]]
        metadata.push("Collections:: " + zoteroRoam.getItemCollections(item));
        
        // You can also choose to not use brackets
        // Collection 1, Collection 2
        metadata.push("Collections:: " + zoteroRoam.getItemCollections(item, { brackets: false }));
        
        // You can also choose to receive the collection names as an Array, for example if you want to list them in sibling blocks
        metadata.push({
            string: "Collections::",
            children: zoteroRoam.getItemCollections(item, { return_as: "array" })
        });
    }
    
    return metadata;
}

zoteroRoam.getItemCreators(item)

Args

item - the Zotero item

config - additional configuration Object. Properties available:

• brackets : whether to surround the creator names in brackets. Values: true|false|existing. Default : true.

• return_as : the format in which the creators should be returned. Values: "string"|"array"|"identity". Default: "string".

• use_type : whether to include the creator's type (author, editor, ...). Values: true|false. Default : true.

Returns

The creators of the Zotero item, formatted according to the configuration provided.

Usage

window.myFunc = function(item, pdfs, notes){
    let metadata = [];
    
    if(item.data.creators.length > 0){
        // By default, creator names will be in [[brackets]], followed by the creator's type in parentheses (if they're not an author), and returned as a comma-separated list
        // [[Some Author]], [[Some Editor]] (editor)
        metadata.push("Author(s):: " + zoteroRoam.getItemCreators(item));
        
        // You can also choose to not use brackets
        // Some Author, Some Editor (editor)
        metadata.push("Author(s):: " + zoteroRoam.getItemCreators(item, { brackets: false }));
        
        // ... or to only add brackets if the creator has a Roam page
        // Some Author, [[Some Editor]] (editor)
        metadata.push("Author(s):: " + zoteroRoam.getItemCreators(item, { brackets: "existing" }));
        
        // You can also remove creator types
        // [[Some Author]], [[Some Editor]]
        metadata.push("Author(s):: " + zoteroRoam.getItemCreators(item, { use_type: false }));
        
        // You can also choose to receive the collection names as an Array, for example if you want to list them in sibling blocks
        metadata.push({
            string: "Author(s)::",
            children: zoteroRoam.getItemCollections(item, { return_as: "array" })
        });
        
        // If you want more control, use the `identity` format
        // It will return an Array of Objects, each with 3 properties:
        // name - the creator's full name
        // type - the creator's type (e.g "author", "editor", ...)
        // inGraph - if the creator's Roam page exists, its UID ; otherwise false
        const creatorList = zoteroRoam.getItemCreators(item, { return_as: "identity" })
            .map(cre => `[[${cre.name}]]` + (cre.type == "author" ? "" : ` (${cre.type})`));
        metadata.push({
            string: "Author(s)::",
            children: creatorList
        });
        
    }
    
    return metadata;
}

zoteroRoam.getItemDateAdded(item)

Args

item - the Zotero item

config - additional configuration Object. Properties available:

• brackets : whether to surround the date with brackets. Values : true|false. Default : true.

Returns

The date on which the item was added to Zotero, in Daily Notes Page format.

Usage

window.myFunction = function(item, pdfs, notes){
    let metadata = [];
    
    // By default, the date is returned in brackets
    // [[January 1st, 2022]]
    metadata.push("Date Added:: " + zoteroRoam.getItemDateAdded(item));
    // This is the same as:
    metadata.push("Date Added:: " + zoteroRoam.getItemDateAdded(item, { brackets: true }));
    
    // You can also choose to have it returned without brackets
    // January 1st, 2022
    metadata.push("Date Added:: " + zoteroRoam.getItemDateAdded(item, { brackets: false }));
    
    return metadata;
}

zoteroRoam.getItemLink(item)

Args

item - the Zotero item

type - the type of link to generate. Values : local|web. Default : "local".

config - additional configuration Object. Properties available:

• format - the format in which the link should be returned. Values : markdown|target. Default : "markdown".

• text - if format: "markdown" , the text to use for the Markdown link. Default : "Local library" or "Web library", depending on type .

Returns

A link to the item in Zotero (local app or web version).

Usage

window.myFunction = function(item, pdfs, notes){
    let metadata = [];
    
    // By default, the function will return a local link to the item, which will open in the Zotero standalone app. It will be in Markdown format, with "Local library" as the link's text
    // [Local library](zotero://select/library/items/PPD648N6)
    metadata.push("Zotero Link:: " + zoteroRoam.getItemLink(item));
    
    // You can change the link's text
    // [some text](zotero://select/library/items/PPD648N6)
    metadata.push("Zotero Link:: " + zoteroRoam.getItemLink(item, "local", { text: "some text" }));
    
    // You can also choose to return a link that opens in the browser
    // [Web library](https://www.zotero.org/users/123456/items/PPD648N6)
    metadata.push("Zotero Link:: " + zoteroRoam.getItemLink(item, "web"));
    
    // You can also choose to return the link's target, rather than a Markdown link, then use it however you wish
    // zotero://select/library/items/PPD648N6
    metadata.push("Zotero Link:: " + zoteroRoam.getItemLink(item, "local", { format: "target" }));
    
    return metadata;
}

zoteroRoam.getItemMetadata(item, pdfs, notes)

Args

item - the Zotero item

pdfs - the Zotero item's linked PDFs

notes - the Zotero item's linked notes/annotations

Returns

The output of the extension's default metadata formatter, according to current user settings.

Usage

window.myFunction = function(item, pdfs, notes){
    let metadata = [];
    
    metadata.push({
        string: "[[Metadata]]",
        children: zoteroRoam.getItemMetadata(item, pdfs, notes)
    });
    
    return metadata;
}

zoteroRoam.getItemPublication(item)

Args

item - the Zotero item

config - additional configuration Object. Properties available :

• brackets - whether to surround the publication with brackets. Values : true|false. Default : true.

Returns

The publication details of the item. In order, the extension will look for a publicationTitle, then a bookTitle, then a university name.

Usage

window.myFunction = function(item, pdfs, notes){
    let metadata = [];
    
    // By default, the extension returns the publication details in brackets
    // [[Journal of Public Health]]
    metadata.push("Publication:: " + zoteroRoam.getItemPublication(item));
    
    // You can also choose to omit the brackets
    // Journal of Public Health
    metadata.push("Publication:: " + zoteroRoam.getItemPublication(item, { brackets: false }));
    
    return metadata;
}

zoteroRoam.getItemRelated(item)

Args

item - the Zotero item

config - additional configuration Object. Properties available :

• brackets - whether to surround the relations with brackets. Values : true|false. Default : true.

• return_as - the format in which to return the relations. Values : string|array|raw. Default : "string".

Returns

The list of Zotero items related to the given item, per Zotero metadata.

Usage

window.myFunction = function(item, pdfs, notes){
    let metadata = [];
    
    // By default, the citekeys of the relations are returned in [[brackets]], as a comma-separated list
    // [[@someCitekey]], [[@anotherCitekey]]
    metadata.push("Related Items:: " + zoteroRoam.getItemRelated(item));
    
    // You can also choose to omit the brackets
    // someCitekey, anotherCitekey
    metadata.push("Related Items:: " + zoteroRoam.getItemRelated(item, { brackets: false }));
    
    // If you want the relations to be listed in sibling blocks, you can choose to have them returned as an `array`:
    // [ "[[@someCitekey]]", "[[@anotherCitekey]]" ]
    metadata.push({
        string: "Related Items::",
        children: zoteroRoam.getItemRelated(item, { return_as: "array" })
    });
    
    // If you want more control, use the `raw` format
    // It will return an Array of Objects, each containing the raw metadata of a relation
    const relatedList = zoteroRoam.getItemRelated(item, { return_as: "raw" })
        .map(item => `[[@${item.key}]]`)
        .join(", ");
    metadata.push("Related Items:: " + relatedList);
    
    return metadata;
}

zoteroRoam.getItemTags(item)

Args

item - the Zotero item

config - additional configuration Object. Properties available:

• brackets - whether to surround the tags with brackets. Values : true|false. Default : true.

• return_as - the format in which to return the tags. Values : string|array. Default : string.

Returns

The tags of the item

Usage

window.myFunction = function(item, pdfs, notes){
    let metadata = [];
    
    if(item.data.tags.length > 0){
        // By default, the tags are returned in #[[brackets]] as a space-separated list
        // #[[tag1]] #[[tag2]]
        metadata.push("Tags:: " + zoteroRoam.getItemTags(item));
        
        // You can also choose to omit the brackets
        // tag1 tag2
        metadata.push("Tags:: " + zoteroRoam.getItemTags(item, { brackets: false }));
        
        // If you want the tags to be listed as sibling blocks, or want to manipulate them further, you can choose to have them returned as an array
        // [ "#[[tag1]]", "#[[tag2]]" ]
        metadata.push({
            string: "Tags::",
            children: zoteroRoam.getItemTags(item, { return_as: "array" })
        });
    }
    
    return metadata;
}

zoteroRoam.getItemType(item)

Args

item - the Zotero item

config - additional configuration Object. Properties available :

• brackets - whether to surround the type with brackets. Values : true|false. Default : true.

Returns

The item's type, according to current user settings (mapping provided in Typemap).

Usage

window.myFunction = function(item, pdfs, notes){
    let metadata = [];
    
    // By default, the function returns the item's type in brackets
    // [[Paper]]
    metadata.push("Type:: " + zoteroRoam.getItemType(item));
    
    // You can also choose to omit the brackets
    // "Paper"
    metadata.push("Type:: " + zoteroRoam.getItemType(item, { brackets: false }));
    
    return metadata;
}