# JavaScript templates

## Syntax

Custom functions must be defined with the syntax \
\
`window.customMetadata = function(item) { ... }` \
\
rather than \
\
`function customMetadata(item){ ... }` \
\
otherwise an error will be thrown. This syntax is needed to make the function globally available, so that it can be found by the extension.

## Specifications

All formatting functions must have the structure described below. 

#### Arguments

The function must **take up to 3 arguments**, in order :

* The item's data object, as returned by the Zotero Web API. [See here](https://gist.github.com/dstillman/f1030b9609aadc51ddec) for an example from the Zotero API docs.
* The item's linked PDFs
* The item's linked notes/annotations

#### Return Value

The function must **return a single array**, containing the blocks to be added to the item's Roam page. **Each element** of the array will be processed as **a top-level Roam block** to be added to the item's Roam page. The array's order will be the final block order in Roam.

Blocks can be provided in two forms:

* A simple string of text, which will create a childless block
* An Object with a `string` property, and an optional `children` property: \
  `{ string: "The block's contents", children: [...] }`
  * Objects will be processed recursively, which means you can specify as much nesting levels as you'd like (see [Nesting metadata](https://alix-lahuec.gitbook.io/zotero-roam/customization/formatting/javascript-templates/nesting-metadata)).

## Getting Started

To start writing your own functions, feel free to make use of this [Observable interactive notebook](https://observablehq.com/@greenmeen/zoteroroam-metadata-formatting) , which has a few examples and demos:

{% embed url="<https://observablehq.com/@greenmeen/zoteroroam-metadata-formatting>" %}