# 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](https://alix-lahuec.gitbook.io/zotero-roam/customization/formatting/javascript-templates/..#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](https://alix-lahuec.gitbook.io/zotero-roam/customization/other/typemap)).

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