# 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](/zotero-roam/customization/formatting/javascript-templates.md#getting-started), 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.

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

<details>

<summary>zoteroRoam.formatNotes(notes)</summary>

**Args**

`notes` - the notes/annotations linked to the Zotero item

**Returns**

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

**Usage**

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

</details>

<details>

<summary>zoteroRoam.formatPDFs(pdfs)</summary>

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

{% code overflow="wrap" %}

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

{% endcode %}

</details>

<details>

<summary>zoteroRoam.getItemChildren(item)</summary>

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

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

</details>

<details>

<summary>async zoteroRoam.getItemCitation(item)</summary>

*Refer to* [*the Zotero API documentation*](https://www.zotero.org/support/dev/web_api/v3/basics#parameters_for_format_bib_includecontent_bib_includecontent_citation) *for details and accepted values.*

**Args**

`item` - the Zotero item

`config` - additional configuration Object. Properties available :&#x20;

* `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**

{% code overflow="wrap" %}

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

{% endcode %}

</details>

<details>

<summary>zoteroRoam.getItemCollections(item)</summary>

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

{% code overflow="wrap" %}

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

{% endcode %}

</details>

<details>

<summary>zoteroRoam.getItemCreators(item)</summary>

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

{% code overflow="wrap" %}

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

{% endcode %}

</details>

<details>

<summary>zoteroRoam.getItemDateAdded(item)</summary>

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

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

</details>

<details>

<summary>zoteroRoam.getItemLink(item)</summary>

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

{% code overflow="wrap" %}

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

{% endcode %}

</details>

<details>

<summary>zoteroRoam.getItemMetadata(item, pdfs, notes)</summary>

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

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

</details>

<details>

<summary>zoteroRoam.getItemPublication(item)</summary>

**Args**

`item` - the Zotero item

`config` - additional configuration Object. Properties available :&#x20;

* `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**

{% code overflow="wrap" %}

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

{% endcode %}

</details>

<details>

<summary>zoteroRoam.getItemRelated(item)</summary>

**Args**

`item` - the Zotero item

`config` - additional configuration Object. Properties available :&#x20;

* `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**

{% code overflow="wrap" %}

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

{% endcode %}

</details>

<details>

<summary>zoteroRoam.getItemTags(item)</summary>

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

{% code overflow="wrap" %}

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

{% endcode %}

</details>

<details>

<summary>zoteroRoam.getItemType(item)</summary>

Args

`item` - the Zotero item

`config` - additional configuration Object. Properties available :&#x20;

* `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](/zotero-roam/customization/other/typemap.md)).

**Usage**

{% code overflow="wrap" %}

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

{% endcode %}

</details>


---

# 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/customization/formatting/javascript-templates/helper-functions.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.