# 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](https://alix-lahuec.gitbook.io/zotero-roam/v0.5/customization/other/funcmap).

### 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", split_char: "\n"});
    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](https://alix-lahuec.gitbook.io/zotero-roam/v0.5/customization/other/typemap).