Zotero.Syllabus.api

const syllabusApi: object;

Defined in: api.ts:696

Public JavaScript API for other Zotero plugins and scripts (for example Actions & Tags). At runtime the facade is attached as Zotero.Syllabus.api on the Syllabus addon instance.

Always wait until Syllabus (and Zotero’s UI) are ready before calling anything else:

await Zotero.Syllabus.api.whenReady();

const collection = ZoteroPane.getSelectedCollection();
if (collection && Zotero.Syllabus.api.syllabus.has(collection)) {
  const metadata = Zotero.Syllabus.api.syllabus.getMetadata(collection.id);
  Zotero.Syllabus.api.view.openSyllabus(collection.id);
}

Namespaces below: syllabus, class, assignment, view, pinned, personal. Top-level helpers: version, isReady(), whenReady().

Type Declaration

version

version: string;

Installed plugin version (from package.json).

isReady

isReady: () => boolean;

Whether the Syllabus addon has finished initializing. Prefer whenReady for callers that need caches loaded.

Returns

boolean

whenReady

whenReady: () => Promise<void>;

Resolve when Zotero’s UI is ready and Syllabus has loaded its note / personal-order caches. Call this before any other API method.

Returns

Promise<void>

syllabus

syllabus: object;

Syllabus document for a collection: metadata, lock, priorities, CSL, external links, and the full JSON document / snapshot.

A collection “is a syllabus” when it has a Syllabus note (syllabus.has / syllabus.ensure).

syllabus.has

has: (collectionId) => boolean;

True if the collection already has a Syllabus note (is a syllabus).

Parameters

Parameter	Type
`collectionId`	\| `Collection` \| `CollectionId`

Returns

boolean

syllabus.ensure

ensure: (collectionId) => Promise<boolean>;

Create a Syllabus note for the collection if missing (same as “Turn into Syllabus” in the UI). Returns whether a note exists afterward.

Parameters

Parameter	Type
`collectionId`	\| `Collection` \| `CollectionId`

Returns

Promise<boolean>

syllabus.getMetadata

getMetadata: (collectionId) => SyllabusMetadata;

Read syllabus-level settings (priorities, nomenclature, lock, …).

Parameters

Parameter	Type
`collectionId`	`CollectionId`

Returns

SyllabusMetadata

syllabus.setMetadata

setMetadata: (collectionId, metadata) => Promise<void>;

Replace syllabus-level settings wholesale.

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`metadata`	`SyllabusMetadata`

Returns

Promise<void>

syllabus.patchMetadata

patchMetadata: (collectionId, patch) => Promise<void>;

Merge a partial patch into syllabus-level settings.

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`patch`	`Partial`<`SyllabusMetadata`>

Returns

Promise<void>

syllabus.getDocument

getDocument: (collectionId) => SyllabusDocument;

Full in-memory syllabus document (classes, items, orders). Prefer this for reads; use syllabus.getDocumentSnapshot when you need a stable string.

Parameters

Parameter	Type
`collectionId`	\| `Collection` \| `CollectionId`

Returns

SyllabusDocument

syllabus.getDocumentSnapshot

getDocumentSnapshot: (collectionId) => string;

Serialized snapshot of the syllabus document (for export / debugging).

Parameters

Parameter	Type
`collectionId`	\| `Collection` \| `CollectionId`

Returns

string

syllabus.getDictionary

getDictionary: () => SyllabusDictionary;

Map of collection key → lightweight syllabus metadata for every syllabus in the library (for pickers / cross-collection search).

Returns

SyllabusDictionary

syllabus.getLocked

getLocked: (collectionId) => boolean;

Whether the syllabus is locked (read-only study mode).

Parameters

Parameter	Type
`collectionId`	`CollectionId`

Returns

boolean

syllabus.setLocked

setLocked: (collectionId, locked) => Promise<void>;

Lock or unlock the syllabus (UI becomes read-only when locked).

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`locked`	`boolean`

Returns

Promise<void>

syllabus.getDescription

getDescription: (collectionId) => string;

Syllabus / course description text.

Parameters

Parameter	Type
`collectionId`	`CollectionId`

Returns

string

syllabus.setDescription

setDescription: (collectionId, description) => Promise<void>;

Set the syllabus / course description text.

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`description`	`string`

Returns

Promise<void>

syllabus.getInstitution

getInstitution: (collectionId) => string;

Institution name shown on the syllabus header / exports.

Parameters

Parameter	Type
`collectionId`	`CollectionId`

Returns

string

syllabus.setInstitution

setInstitution: (collectionId, institution) => Promise<void>;

Set the institution name.

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`institution`	`string`

Returns

Promise<void>

syllabus.getCourseCode

getCourseCode: (collectionId) => string;

Course code shown on the syllabus header / exports.

Parameters

Parameter	Type
`collectionId`	`CollectionId`

Returns

string

syllabus.setCourseCode

setCourseCode: (collectionId, courseCode) => Promise<void>;

Set the course code.

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`courseCode`	`string`

Returns

Promise<void>

syllabus.getNomenclature

getNomenclature: (collectionId) => string;

Word used for a class unit (class, week, session, …) — drives UI copy.

Parameters

Parameter	Type
`collectionId`	`CollectionId`

Returns

string

syllabus.setNomenclature

setNomenclature: (collectionId, nomenclature) => Promise<void>;

Set the class-unit nomenclature word.

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`nomenclature`	`string`

Returns

Promise<void>

syllabus.getPriorities

getPriorities: (collectionId) => SyllabusPriority[];

Priority list for this syllabus (Essential / Recommended / …).

Parameters

Parameter	Type
`collectionId`	`CollectionId`

Returns

SyllabusPriority[]

syllabus.setPriorities

setPriorities: (collectionId, priorities) => Promise<void>;

Replace the priority list for this syllabus.

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`priorities`	`SyllabusPriority`[]

Returns

Promise<void>

syllabus.getCslStyle

getCslStyle: (collectionId) => string | null;

Citation style id for bibliography on print / publish, or null for default.

Parameters

Parameter	Type
`collectionId`	`CollectionId`

Returns

string | null

syllabus.setCslStyle

setCslStyle: (collectionId, cslStyle) => Promise<void>;

Set the citation style id, or null for default.

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`cslStyle`	`string` \| `null`

Returns

Promise<void>

syllabus.getCreateSubcollections

getCreateSubcollections: (collectionId) => boolean;

Whether auto-managed class subcollections are enabled. Leave off unless you need folder mirrors — do not edit those folders by hand.

Parameters

Parameter	Type
`collectionId`	`CollectionId`

Returns

boolean

syllabus.setCreateSubcollections

setCreateSubcollections: (collectionId, createSubcollections) => Promise<void>;

Enable or disable auto-managed class subcollections.

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`createSubcollections`	`boolean`

Returns

Promise<void>

syllabus.getLinks

getLinks: (collectionId) => string[];

Extra URLs shown on the syllabus (handbook, VLE, …).

Parameters

Parameter	Type
`collectionId`	`CollectionId`

Returns

string[]

syllabus.setLinks

setLinks: (collectionId, links) => Promise<void>;

Replace the list of extra URLs on the syllabus.

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`links`	`string`[]

Returns

Promise<void>

class

class: object = klass;

Classes (weeks / sessions). Access as Zotero.Syllabus.api.class.

class.ensure

ensure: (collectionId, classNumber) => Promise<string>;

Ensure a class with this number exists; create if missing. Returns the class id.

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`classNumber`	`number`

Returns

Promise<string>

class.add

add: (collectionId, classNumber) => Promise<void>;

Add a new class with the given number.

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`classNumber`	`number`

Returns

Promise<void>

class.delete

delete: (collectionId, classNumber) => Promise<void>;

Delete a class and clear assignments that pointed at it.

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`classNumber`	`number`

Returns

Promise<void>

class.getByNumber

getByNumber: (collectionId, classNumber) =>
  | StoredClass
  | undefined;

Class metadata for a class number, if present.

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`classNumber`	`number`

Returns

| StoredClass | undefined

class.getIdByNumber

getIdByNumber: (collectionId, classNumber) => string | undefined;

Stable class id string for a class number.

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`classNumber`	`number`

Returns

string | undefined

class.getNumber

getNumber: (collectionId, classId) => number | undefined;

Class number for a class id, if known.

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`classId`	`string` \| `undefined`

Returns

number | undefined

class.getMetadata

getMetadata: (collectionId, classNumber) => ClassMetadata;

Read class metadata (title, description, reading date, status, …).

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`classNumber`	`number`

Returns

ClassMetadata

class.setMetadata

setMetadata: (collectionId, classNumber, metadata) => Promise<void>;

Patch class metadata (title, description, reading date, status, …).

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`classNumber`	`number`
`metadata`	`Partial`<`ClassMetadata`>

Returns

Promise<void>

class.getTitle

getTitle: (collectionId, classNumber, includeClassNumber) => string;

Display title for a class. When includeClassNumber is true, prefixes with the syllabus nomenclature (e.g. “Class 3 …”).

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`classNumber`	`number`
`includeClassNumber`	`boolean`

Returns

string

class.setTitle

setTitle: (collectionId, classNumber, title) => Promise<void>;

Set the class title (pass null / undefined to clear).

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`classNumber`	`number`
`title`	`string` \| `null` \| `undefined`

Returns

Promise<void>

class.getDescription

getDescription: (collectionId, classNumber) => string;

Class description text.

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`classNumber`	`number`

Returns

string

class.setDescription

setDescription: (collectionId, classNumber, description) => Promise<void>;

Set the class description (pass null / undefined to clear).

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`classNumber`	`number`
`description`	`string` \| `null` \| `undefined`

Returns

Promise<void>

class.getReadingDate

getReadingDate: (collectionId, classNumber) => string | null | undefined;

ISO date string when readings for this class are due, or empty.

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`classNumber`	`number`

Returns

string | null | undefined

class.setReadingDate

setReadingDate: (collectionId, classNumber, readingDate) => Promise<void>;

Set the class reading date (ISO string), or clear it.

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`classNumber`	`number`
`readingDate`	`string` \| `null` \| `undefined`

Returns

Promise<void>

class.getStatus

getStatus: (collectionId, classNumber) => "done" | null | undefined;

Class-level done status ("done" or unset).

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`classNumber`	`number`

Returns

"done" | null | undefined

class.setStatus

setStatus: (collectionId, classNumber, status) => Promise<void>;

Mark the class done ("done") or clear done (null / undefined).

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`classNumber`	`number`
`status`	`"done"` \| `null` \| `undefined`

Returns

Promise<void>

class.getFullNumberRange

getFullNumberRange: (collectionId) => number[];

Inclusive range of class numbers that currently exist on the syllabus.

Parameters

Parameter	Type
`collectionId`	`CollectionId`

Returns

number[]

assignment

assignment: object;

Item ↔ class assignments: which class an item sits in, priority, instruction text, reading done flags, and bulk add helpers.

assignment.getForItem

getForItem: (item) =>
  | ItemAssignments
  | undefined;

All syllabus assignment data stored on an item (every collection).

Parameters

Parameter	Type
`item`	`Item`

Returns

| ItemAssignments | undefined

assignment.getForItemInCollection

getForItemInCollection: (item, collectionId) => Assignment[];

Assignments for this item within one collection / syllabus.

Parameters

Parameter	Type
`item`	`Item`
`collectionId`	`CollectionId`

Returns

Assignment[]

assignment.set

set: (item, collectionId, assignments) => Promise<void>;

Replace the assignment list for an item in a collection.

Parameters

Parameter	Type
`item`	`Item`
`collectionId`	`CollectionId`
`assignments`	`Assignment`[]

Returns

Promise<void>

assignment.add

add: (item, collectionId, classNumber, metadata) => Promise<string | undefined>;

Add (or update) an assignment on a class. Pass null / undefined classNumber for unnumbered / further-reading style placement as supported by the manager. Returns the assignment id when created/updated.

Parameters

Parameter	Type
`item`	`Item`
`collectionId`	`CollectionId`
`classNumber`	`number` \| `null` \| `undefined`
`metadata`	`Partial`<`Assignment`>

Returns

Promise<string | undefined>

assignment.setClassNumber

setClassNumber: (item, collectionId, classNumber) => Promise<void>;

Move / set the class number for the item’s primary assignment.

Parameters

Parameter	Type
`item`	`Item`
`collectionId`	`CollectionId`
`classNumber`	`number` \| `undefined`

Returns

Promise<void>

assignment.setReadingStatus

setReadingStatus: (item, collectionId, assignmentId, status) => Promise<void>;

Mark a specific assignment done ("done") or clear done (null). Prefer personal.setDone when using personal reading order.

Parameters

Parameter	Type
`item`	`Item`
`collectionId`	`CollectionId`
`assignmentId`	`string` \| `undefined`
`status`	`"done"` \| `null`

Returns

Promise<void>

assignment.isItemReadingDone

isItemReadingDone: (collectionId, itemKey) => boolean;

Whether the item is considered reading-done in this collection.

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`itemKey`	`string`

Returns

boolean

assignment.isAssignmentReadingDone

isAssignmentReadingDone: (collectionId, itemKey, assignmentId) => boolean;

Whether a specific assignment is marked reading-done.

Parameters

Parameter	Type
`collectionId`	`CollectionId`
`itemKey`	`string`
`assignmentId`	`string` \| `undefined`

Returns

boolean

assignment.addItemsToClass

addItemsToClass: (items, collectionId, classNumber) => Promise<void>;

Add items to a class (and to the collection if needed) — same as the “Add to class” UI path.

Parameters

Parameter	Type
`items`	readonly `Item`[]
`collectionId`	`number`
`classNumber`	`number`

Returns

Promise<void>

assignment.addItemsToUnnumbered

addItemsToUnnumbered: (items, collectionId) => Promise<void>;

Place items in the unnumbered / priority-only band of the syllabus.

Parameters

Parameter	Type
`items`	readonly `Item`[]
`collectionId`	`number`

Returns

Promise<void>

assignment.addItemsToFurtherReading

addItemsToFurtherReading: (items, collectionId) => Promise<void>;

Place items under Further reading.

Parameters

Parameter	Type
`items`	readonly `Item`[]
`collectionId`	`number`

Returns

Promise<void>

assignment.remove

remove: (item, collectionId, classNumber) => Promise<void>;

Remove the assignment for a given class number.

Parameters

Parameter	Type
`item`	`Item`
`collectionId`	`CollectionId`
`classNumber`	`number`

Returns

Promise<void>

assignment.removeById

removeById: (item, collectionId, assignmentId) => Promise<void>;

Remove one assignment by its stable assignment id.

Parameters

Parameter	Type
`item`	`Item`
`collectionId`	`CollectionId`
`assignmentId`	`string`

Returns

Promise<void>

assignment.removeAll

removeAll: (item, collectionId) => Promise<void>;

Remove every assignment for this item on this syllabus.

Parameters

Parameter	Type
`item`	`Item`
`collectionId`	`CollectionId`

Returns

Promise<void>

view

view: object;

Navigate the Zotero UI: open Syllabus / Reading Schedule / Annotation Feed tabs, jump to a class or assignment, and read/set collection view mode.

view.openSyllabus

openSyllabus: (collectionId) => void;

Open the Syllabus page for a collection (creates the view if needed).

Parameters

Parameter	Type
`collectionId`	`number`

Returns

void

view.openAtClass

openAtClass: (collectionId, classNumber, itemId?) => void;

Open Syllabus scrolled to a class. Pass "further-reading" or null for those bands; optional itemId focuses a card.

Parameters

Parameter	Type
`collectionId`	`number`
`classNumber`	`number` \| `"further-reading"` \| `null`
`itemId?`	`number`

Returns

void

view.openAssignment

openAssignment: (collectionId, itemId, assignmentData) => void;

Open Syllabus focused on a specific assignment card.

Parameters

Parameter	Type
`collectionId`	`number`
`itemId`	`number`
`assignmentData`	`Assignment`

Returns

void

view.openReadingSchedule

openReadingSchedule: () => void;

Open the Reading Schedule tab.

Returns

void

view.openMyAnnotations

openMyAnnotations: (libraryID) => void;

Open the Annotation Feed tab for a library.

Parameters

Parameter	Type
`libraryID`	`number`

Returns

void

view.getCollectionViewMode

getCollectionViewMode: () => CollectionViewMode;

Current items-pane mode for the selected collection (table / gallery / syllabus / …).

Returns

CollectionViewMode

view.setCollectionViewMode

setCollectionViewMode: (mode) => Promise<void>;

Set the items-pane mode for the selected collection.

Parameters

Parameter	Type
`mode`	`CollectionViewMode`

Returns

Promise<void>

pinned

pinned: object;

Pinning for Home → Pinned and the top of Reading Schedule. Distinct from Course Information priority and from “Add to Home” shelves.

pinned.isItem

isItem: (item) => boolean;

Whether the item is on the pinned list.

Parameters

Parameter	Type
`item`	`Item`

Returns

boolean

pinned.isSyllabus

isSyllabus: (collection) => boolean;

Whether the collection is pinned as a syllabus / collection pin.

Parameters

Parameter	Type
`collection`	`Collection`

Returns

boolean

pinned.setItem

setItem: (item, pinnedFlag) => Promise<void>;

Pin or unpin an item.

Parameters

Parameter	Type
`item`	`Item`
`pinnedFlag`	`boolean`

Returns

Promise<void>

pinned.setSyllabus

setSyllabus: (collection, pinnedFlag) => Promise<boolean>;

Pin or unpin a collection (prefer the syllabus collection, not a class folder).

Parameters

Parameter	Type
`collection`	`Collection`
`pinnedFlag`	`boolean`

Returns

Promise<boolean>

pinned.listItems

listItems: (libraryID?) => Promise<Item[]>;

Pinned items, optionally limited to a library.

Parameters

Parameter	Type
`libraryID?`	`number`

Returns

Promise<Item[]>

pinned.listSyllabi

listSyllabi: (libraryID?) => Promise<Collection[]>;

Pinned collections / syllabi, optionally limited to a library.

Parameters

Parameter	Type
`libraryID?`	`number`

Returns

Promise<Collection[]>

personal

personal: object;

Personal reading order — a flat item-key sequence for a collection, separate from syllabus class order. Used for Gallery sort, Next up on pins, and done checkboxes when personal order is active.

personal.getOrder

getOrder: (collection) => string[];

Current personal order (item keys), after pruning missing items.

Parameters

Parameter	Type
`collection`	`number` \| `Collection`

Returns

string[]

personal.setOrder

setOrder: (collection, orderKeys) => Promise<string[]>;

Replace the personal order list. Returns the stored order.

Parameters

Parameter	Type
`collection`	`number` \| `Collection`
`orderKeys`	`string`[]

Returns

Promise<string[]>

personal.pinItem

pinItem: (collection, itemKey) => Promise<string[]>;

Move an item to the front of the personal reading order. Returns the new order.

Parameters

Parameter	Type
`collection`	`number` \| `Collection`
`itemKey`	`string`

Returns

Promise<string[]>

personal.removeItem

removeItem: (collection, itemKey) => Promise<string[]>;

Remove an item from the personal reading order. Returns the new order.

Parameters

Parameter	Type
`collection`	`number` \| `Collection`
`itemKey`	`string`

Returns

Promise<string[]>

personal.isDone

isDone: (collection, itemKey) => boolean;

Whether the item is marked done in personal reading order.

Parameters

Parameter	Type
`collection`	`number` \| `Collection`
`itemKey`	`string`

Returns

boolean

personal.setDone

setDone: (collection, itemKey, done, siblingAssignmentIds) => Promise<void>;

Set item done. Pass sibling assignment ids when the item has multiple syllabus assignments that should stay in sync.

Parameters

Parameter	Type
`collection`	`number` \| `Collection`
`itemKey`	`string`
`done`	`boolean`
`siblingAssignmentIds`	`string`[]

Returns

Promise<void>

personal.isAssignmentDone

isAssignmentDone: (collection, itemKey, assignmentId) => boolean;

Whether a specific assignment is marked done in personal reading order.

Parameters

Parameter	Type
`collection`	`number` \| `Collection`
`itemKey`	`string`
`assignmentId`	`string` \| `null` \| `undefined`

Returns

boolean

personal.setAssignmentDone

setAssignmentDone: (collection, itemKey, assignmentId, done, siblingAssignmentIds) => Promise<void>;

Set done for a specific assignment in personal reading order.

Parameters

Parameter	Type
`collection`	`number` \| `Collection`
`itemKey`	`string`
`assignmentId`	`string`
`done`	`boolean`
`siblingAssignmentIds`	`string`[]

Returns

Promise<void>