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

## 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>" %}


---

# 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.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.