3.3 Creating your own formatting functions

How to define custom functions & assign them to item types

Step 1 : Define a global function

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.

Step 2 : Construct your metadata template within the function

All formatting functions must do the following :

• The function must take a single argument - the item's data object, as returned by the Zotero Web API. See here for an official gist from the Zotero API docs, showing an example object returned for a single item.

• The function must return a single array - specifying the contents of the blocks that should be added to the item's page in Roam.

  • Each element of the array will be processed as a top-level Roam block to be added to the item's Roam page. If the element is a String of text, the block will be childless. If the element is an Object, it can have children blocks (see Nesting metadata).

    • String elements will be added as top-level, childless blocks.

    • Object elements will be processed recursively and support nested blocks.

  • The ordering of the blocks in Roam will reflect the ordering of the array.

To help you with writing your own functions, I've made an Observable interactive notebook, where you can try your hand at writing functions & using them to process your own Zotero data :

zoteroRoam : Metadata formatting 🛠

Getting Started

// You can use the following code to start customizing the output
// It replicates exactly what the default formatting function does :
window.customMetadata = function(item){
    // Initialization of the array of blocks :
    let metadata = [];
    
    // Title of the item
    if (item.data.title) {
        metadata.push(`Title:: ${item.data.title}`)
    };
    // Creators of the item
    if (item.data.creators.length > 0) {
        metadata.push(`Author(s):: ${zoteroRoam.formatting.getCreators(item, {creators_as: "string", brackets: true, use_type: true})}`) 
    };
    // Abstract for the item
    if (item.data.abstractNote) { 
        metadata.push(`Abstract:: ${item.data.abstractNote}`) 
    };
    // Type of the item
    if (item.data.itemType) {
        metadata.push(`Type:: [[${zoteroRoam.formatting.getItemType(item)}]]`) 
    };
    // Publication/Book title
    metadata.push(`Publication:: ${ item.data.publicationTitle || item.data.bookTitle || "" }`)
    // URL
    if (item.data.url) {
        metadata.push(`URL : ${item.data.url}`) 
    };
    // Date the item was added to Zotero
    if (item.data.dateAdded) {
        metadata.push(`Date Added:: ${zoteroRoam.utils.makeDNP(item.data.dateAdded, {brackets: true})}`) 
    };
    // Links to the item in Zotero (local + web links)
    metadata.push(`Zotero links:: ${zoteroRoam.formatting.getLocalLink(item, {format: "markdown", text: "Local library"})}, ${zoteroRoam.formatting.getWebLink(item, {format: "markdown", text: "Local library"})}`); // Local + Web links to the item
    // Tags attached to the item
    if (item.data.tags.length > 0) {
        metadata.push(`Tags:: ${zoteroRoam.formatting.getTags(item)}`)
    };
    
    // Requesting the item's PDF files + notes
    let children = zoteroRoam.formatting.getItemChildren(item, {pdf_as: "links", notes_as: "formatted"});
    // Links to the PDF files
    if(children.pdfItems){
        metadata.push(`PDF links : ${children.pdfItems.join(", ")}`);
    }
    // Contents of notes
    if(children.notes){
        let notesBlock = {string: `[[Notes]]`, children: []};
        notesBlock.children.push(...children.notes.flat(1));
        metadata.push(notesBlock);
    }

    return metadata; 
}

Step 3 : Assign the function to item types

Custom functions can be assigned to item types using funcmap. You can assign a function to specific item types, or set it as the default formatting function.

Assigning the customMetadata function to be used for conference papers and journal articles, and letting the extension handle other item types with its own defaults.

zoteroRoam_settings = {
    // dataRequests: {...},
    funcmap: {
        conferencePaper: "customMetadata",
        journalArticle: "customMetadata"
    }
}

// ---

window.customMetadata = function(item){
    // your code for the formatting function
}

Using the customPaperFormat function for all item types

zoteroRoam_settings = {
    // dataRequests: {...},
    funcmap: {
        DEFAULT: "customMetadata"
    }
}

// ---

window.customMetadata = function(item){
    // your code for the formatting function
}

The function's code is located outside of the zoteroRoam_settings object. To avoid confusion or typos, you can place it in a separate Roam code block. Select JavaScript as language & make sure it's nested under an active roam/jsblock.

Examples

Head over to the Academia Roamana graph page for templates shared by the community, with code, screenshots, etc !