# Extension defaults

### About the `limit` parameter

**In the Zotero API**, the `limit` parameter is the maximum number of results to return. It must be an integer from **1-100** ; the default value is **25 items**.

**Within the extension**, the `limit` parameter has a different meaning : it ends up determining the step size - i.e, the number of items that will be returned for **each** call made by the extension.

|                            | In the Zotero API                                                          | In the extension                                                                |
| -------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Context                    | A single request is made                                                   | A series of API requests are made                                               |
| Scope                      | Per-request                                                                | Per-request                                                                     |
| Effect                     | `limit` determines the maximum number of results to return for the request | `limit` determines the maximum number of results to return **for each request** |
| Number of results returned | The minimum between `nbResults` and `limit`                                | All results                                                                     |

{% hint style="warning" %}
The extension will make **as many calls as necessary** to obtain all the results that match the request, given the value of `limit`. In most cases, you'll want to use `limit=100`, to minimize the total number of requests that are made.
{% endhint %}

{% hint style="info" %}
Since February 15th, all API calls beyond the initial request are **made in parallel**. This is done to improve performance for large datasets.
{% endhint %}

## Item formatting in Roam

By default, the extension formats all items' data by calling the built-in `getItemMetadata` function. If you'd like to define item type-specific formatting, use your own formatting functions, and/or assign a different default formatting function, start with the [funcmap documentation](/zotero-roam/v0.6/customization/other/funcmap.md).

### getItemMetadata

`getItemMetadata` is the extension's default formatting function, if the user hasn't defined any.

{% tabs %}
{% tab title="Function definition" %}

```javascript
// This is taken directly from the extension's code file
zoteroRoam.formatting.getItemMetadata = function(item) {
    let metadata = [];

    if (item.data.title) { metadata.push(`Title:: ${item.data.title}`) }; // Title, if available
    if (item.data.creators.length > 0) { metadata.push(`Author(s):: ${zoteroRoam.formatting.getCreators(item)}`) }; // Creators list, if available
    if (item.data.abstractNote) { metadata.push(`Abstract:: ${item.data.abstractNote}`) }; // Abstract, if available
    if (item.data.itemType) { metadata.push(`Type:: [[${zoteroRoam.formatting.getItemType(item)}]]`) }; // Item type, from typemap or zoteroRoam.typemap (fall back on the raw value)
    metadata.push(`Publication:: ${ item.data.publicationTitle || item.data.bookTitle || "" }`)
    if (item.data.url) { metadata.push(`URL : ${item.data.url}`) };
    if (item.data.dateAdded) { metadata.push(`Date Added:: ${zoteroRoam.utils.makeDNP(item.data.dateAdded, {brackets: true})}`) }; // Date added, as Daily Notes Page reference
    metadata.push(`Zotero links:: ${zoteroRoam.formatting.getLocalLink(item)}, ${zoteroRoam.formatting.getWebLink(item)}`); // Local + Web links to the item
    if (item.data.tags.length > 0) { metadata.push(`Tags:: ${zoteroRoam.formatting.getTags(item)}`) }; // Tags, if any
    
    let children = zoteroRoam.formatting.getItemChildren(item, {pdf_as: "links", notes_as: "formatted"});
    if(children.pdfItems){
        metadata.push(`PDF links : ${children.pdfItems.join(", ")}`);
    }
    if(children.notes){
        let notesBlock = {string: `[[Notes]]`, children: []};
        notesBlock.children.push(...children.notes.flat(1));
        metadata.push(notesBlock);
    }

    return metadata; 
}
```

{% endtab %}

{% tab title="Output structure" %}
`getItemMetadata` returns a flat array of String elements, which will be added as a series of top-level blocks to the item's Roam page :

* Title::
* Author(s)::
* Abstract::
* Type::
* Publication::
* URL :
* Date Added::
* Zotero links::
* Tags::
* PDF links :
* \[\[Notes]]

It's a barebones structure, and is mostly meant to serve as backup function & starting point for users to create their own functions.
{% endtab %}
{% endtabs %}

### typemap

When using `getItemMetadata` to format an item's data, the extension creates a Roam block describing the item's type : `Type:: [[<Item type>]]`. By default, the `<Item type>` label will be determined through the extension's default mapping, which comes from the [melat0nin/zotero-roam-export](https://github.com/melat0nin/zotero-roam-export) plugin :

```javascript
zoteroRoam.typemap = {
    artwork: "Illustration",
    audioRecording: "Recording",
    bill: "Legislation",
    blogPost: "Blog post",
    book: "Book",
    bookSection: "Chapter",
    "case": "Legal case",
    computerProgram: "Data",
    conferencePaper: "Conference paper",
    document: "Document",
    email: "Letter",
    encyclopediaArticle: "Encyclopaedia article",
    film: "Film",
    forumPost: "Forum post",
    hearing: "Hearing",
    instantMessage: "Instant message",
    interview: "Interview",
    journalArticle: "Article",
    letter: "Letter",
    magazineArticle: "Magazine article",
    manuscript: "Manuscript",
    map: "Image",
    newspaperArticle: "Newspaper article",
    patent: "Patent",
    podcast: "Podcast",
    presentation: "Presentation",
    radioBroadcast: "Radio broadcast",
    report: "Report",
    statute: "Legislation",
    thesis: "Thesis",
    tvBroadcast: "TV broadcast",
    videoRecording: "Recording",
    webpage: "Webpage"
}
```

If you'd like to define your own taxonomy of item types, start with the [typemap documentation](/zotero-roam/v0.6/customization/other/typemap.md).


---

# 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/v0.6/customization/extension-defaults.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.