Skip to content

Latest commit

 

History

History
495 lines (365 loc) · 8.57 KB

TemplateDoc.md

File metadata and controls

495 lines (365 loc) · 8.57 KB

How to Write Your Own Template

This documentation is like a dictionary. For beginners, see How to Use Templates.

Use Ctrl+F to look up what you need and make your own template!

Stages

Some type of templates(Item) support stages.

Code wrapped inside the stage will be called at a specific time.

For example, the beforeloop stage code:

// @beforeloop-begin
code;
// @beforeloop-end
stage calling time
beforeloop before entering the loop of items
default loop of items
afterloop after leaving the loop of items

In other type of templates, the default stage is called.

Variables

QuickInsert

variables: link: string, subNoteItem, noteItem

QuickBackLink

variables: subNoteItem, noteItem

QuickImport

variables: subNoteLines: string[], subNoteItem, noteItem

QuickNoteV3

variables: annotationItem, topItem

ExportMDFileName

variables: noteItem

ExportMDFileHeader

variables: noteItem

The return value must be a JSON string.

Text

variables: -

Item

beforeloop stage: items, copyNoteImage, editor, sharedObj(for temporary variables, shared by all stages)
default stage: topItem, itemNotes, copyNoteImage, editor, sharedObj
afterloop stage: items, copyNoteImage, editor, sharedObj

Note

Removed after v0.7.15+

Formats

Line

Description: Normal line.
Template Type: None.
Required Variable: None.

<p>Your Line Here</p>

Heading

Description: From h1 to h6.
Template Type: None.
Required Variable: None.

<h1>Your Heding 1 Here</h1>
<h2>Your Heding 2 Here</h2>

Highlight

Description: Highlight.
Template Type: None.
Required Variable: None.

<p style="background-color:#dbeedd;">Text</p>

Strong

Description: Strong text. Put it in a p.
Template Type: None.
Required Variable: None.

<strong>Your Text</strong>

Underline

Description: Underline text. Put it in a p.
Template Type: None.
Required Variable: None.

<u>Your Text</u>

Deleteline

Description: Deleteline text. Put it in a p.
Template Type: None.
Required Variable: None.

<span style="text-decoration: line-through">Your Text</span>

Link

Description: Link. Put it in a p.
Template Type: None.
Required Variable: None.

<a href="zotero://replace/this/link">Link Text</a>

Number List

Description: Number List.
Template Type: None.
Required Variable: None.

<ol>
  <li>First</li>
  <li>Second</li>
  <li>...</li>
</ol>

Bullet List

Description: Bullet List.
Template Type: None.
Required Variable: None.

<ul>
  <li>First</li>
  <li>Second</li>
  <li>...</li>
</ul>

Sup & Sub Text

Description: $\text{The}^{sup} \ and \ \text{the}_{sub}$ text.
Template Type: None.
Required Variable: None.

<p>The<sup>sup</sup>and the<sub>sub</sub> text</p>

Block Quote

Description:

Block Quote

Template Type: None.
Required Variable: None.

<blockquote>
  <p>Text</p>
</blockquote>

Monospaced

Description: Monospaced
Template Type: None.
Required Variable: None.

<pre>Text</pre>

Table

Description:

Table Column1 Column2
00 01 02
10 11 12

Template Type: None.
Required Variable: None.

<table>
  <tr>
    <th style="background-color:#dbeedd;">
      <p style="text-align: right">Table</p>
    </th>
    <th style="background-color:#dbeedd;">Column1</th>
    <th style="background-color:#dbeedd;">Column2</th>
  </tr>
  <tr>
    <td>00</td>
    <td>01</td>
    <td>02</td>
  </tr>
  <tr>
    <td>10</td>
    <td>11</td>
    <td>12</td>
  </tr>
</table>

General Fields

Current Date

Description: Current Date.
Required Variable: None.

<p>${new Date().toLocaleDateString()}</p>

Tags

Description: item.getTags() returns tags in list. Usually use tags.includes("YourTag") ? do sth : do sth else.
Required Variable: any item/note/annotation.

<p>${topItem.getTags()}</p>

Note Fields

Note Title

Description: Note Title. First line of note.
Template Type: Note.
Required Variable: noteItem/subNoteItem.

<p>${noteItem.getNoteTitle()}</p>

Note Content

Description: Note Content.
Template Type: Note.
Required Variable: noteItem/subNoteItem.

<p>${noteItem.getNote()}</p>

Note Link

Description: Note Link.
Template Type: Note.
Required Variable: noteItem/subNoteItem.

<p>
  <a href="${Zotero.BetterNotes.knowledge.getNoteLink(noteItem)}">
    ${noteItem.key}
  </a>
</p>

Item Fields

Title

Description: Item title.
Template Type: Item.
Required Variable: topItem.

<p>${topItem.getField("title")}</p>

Publisher/Journal

Description: Publisher/Journal.
Template Type: Item.
Required Variable: topItem.

<p>
  $
  {(() => {
    if (topItem.itemType === "conferencePaper") {
      return;
      topItem.getField("conferenceName") ||
        topItem.getField("proceedingsTitle");
    }
    if (topItem.itemType === "journalArticle")
      return topItem.getField("publicationTitle");
    if (topItem.itemType === "report") return topItem.getField("institution");
    return topItem.getField("publicationTitle");
  })()}
</p>

Authors

Description: Authors.
Template Type: Item.
Required Variable: topItem.

<p>
  $
  {topItem
    .getCreators()
    .map((v) => v.firstName + " " + v.lastName)
    .join("; ")}
</p>

Pub. date

Description: Pub. date.
Template Type: Item.
Required Variable: topItem.

<p>${topItem.getField("date")}</p>

Pub. date

Description: Publication date/time.
Template Type: Item.
Required Variable: topItem.

<p>${topItem.getField("date")}</p>

DOI

Description: DOI.
Template Type: Item.
Required Variable: topItem.

<p>
  <a href="https://doi.org/${topItem.getField('DOI')}">
    ${topItem.getField("DOI")}
  </a>
</p>

URL

Description: URL.
Template Type: Item.
Required Variable: topItem.

<p>
  <a href="${topItem.getField('url')}">${topItem.getField("url")}</a>
</p>

CitationKey

Description: CitationKey.
Template Type: Item.
Required Variable: topItem.

<p>${topItem.citationKey ? topItem.citationKey : ""}</p>

PDF Link

Description: URL.
Template Type: Item.
Required Variable: topItem.

<p>
  $
  {((topItem) => {
    const getPDFLink = (_item) => {
      let libraryID = _item.libraryID;
      let library = Zotero.Libraries.get(libraryID);
      let itemKey = _item.key;
      let itemLink = "";
      if (library.libraryType === "user") {
        itemLink = `zotero://open-pdf/library/items/${itemKey}`;
      } else if (library.libraryType === "group") {
        itemLink = `zotero://open-pdf/groups/${library.id}/items/${itemKey}`;
      }
      return `<a href="${itemLink}">${_item.getFilename()}</a>`;
    };
    return Zotero.Items.get(topItem.getAttachments())
      .filter((i) => i.isPDFAttachment())
      .map((i) => getPDFLink(i))
      .join("\n");
  })(topItem)}
</p>

Item Notes

Description: Walk all sub notes under an item. You can add your code inside the loop.
Template Type: Item.
Required Variable: topItem.

${itemNotes.map((noteItem)=>{
    // process each item note
    const noteLine = `<blockquote>
    ${noteItem.getNote()}
    </blockquote>`;
    copyNoteImage(noteItem);
    return noteLine;
}).join("\n")}

About Item Fields

The noteItem and topItem is a Zotero Item object. The general data can be accessed using the getField() method.

For example: topItem.getField('title') will return the title of the topItem.

// Get Item Fields
getField: (void)=>string;

// Get Authors
getCreators: (void)=>{
        fieldMode: number,
        firstName: string, // may be empty
        lastName: string,
        creatorTypeID: number,
    }[];

Find available fields of the selected item with the code below:

const item = ZoteroPane.getSelectedItems().shift();
const usedFields = item.getUsedFields();
Zotero.ItemFields.getAll()
  .filter((e) => usedFields.indexOf(e.id) >= 0)
  .map((e) => e.name);

The result is like this (depending on the item you select):

[
    "0": "title"
    "1": "date"
    "2": "language"
    "3": "shortTitle"
    "4": "libraryCatalog"
    "5": "url"
    "6": "accessDate"
    "7": "pages"
    "8": "conferenceName"
]

or see https://aurimasv.github.io/z2csl/typeMap.xml for the detailed Zotero fields documentation.