Extension defaults

A summary of the default parameters used by the extension to make API calls to Zotero, and format items in Roam.

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

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.

Since February 15th, all API calls beyond the initial request are made in parallel. This is done to improve performance for large datasets.

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.

getItemMetadata

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

Function definition

// 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; 
}

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.

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 plugin :

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.