[Item] Annotations by color → item

[fabianlatz]

Description

This template collects all annotations of the selected Zotero items and groups them by color first, and by item in second order. All other templates I could find do this grouping the other way around, hence keep the annotations of the same color separated by the item they come from.
It is designed for use with multiple items to group all yellow, green etc. annotations from all selected items together.
You can choose the name/meaning of each color and the order in which they appear by manipulating sharedObj.colors in ll. 4ff.
Within each annotation color, the annotations of each item are sub-grouped with a heading containing the citationKey (if present, or the first author and year of publication, and the title of the item.
It is capable of being refreshed to fetch annotations made since the creation of the note or the last refresh.

Screenshots

Test on Zotero version

7.0.11

Test on Better Notes version

2.2.5

Template Type

Item

Template Share Code

# This template is specifically for importing/sharing, using better 
# notes 'import from clipboard': copy the content and
# goto Zotero menu bar, click Tools->New Template from Clipboard.  
# Do not copy-paste this to better notes template editor directly.
name: "[item]Annotations by color → item"
zoteroVersion: "7.0.11"
pluginVersion: "2.2.5"
savedAt: "2025-01-20T21:20:08.061Z"
content: |-
  // @author [fabianlatz](https://github.com/fabianlatz)
  // @link [#1272](https://github.com/windingwind/zotero-better-notes/discussions/1272)
  // @use-refresh
  // @beforeloop-begin
  ${{
  	sharedObj.colors = {
  		"#ffd400": { name: "Important", annotations: [] },  // Yellow
  		"#a28ae5": { name: "Background information", annotations: [] }, // Purple
  		"#f19837": { name: "Other relevant sources", annotations: [] }, // Orange
  		"#5fb236": { name: "Advantages", annotations: [] }, // Green
  		"#ff6666": { name: "Challenges", annotations: [] }, // Red
  		"#aaaaaa": { name: "Practical application", annotations: [] }, // Grey
  		"#e56eee": { name: "Research gaps", annotations: [] }, // Magenta
  		"#2ea8e5": { name: "Other", annotations: [] } // Blue
  	};
  	return "";
  }}$
  // @beforeloop-end
  
  // @default-begin
  ${{
  	async function getAnnotationsByColor(_attachment, color) {
  		const annots = _attachment
  		.getAnnotations()
  		.filter((item) => item.annotationColor === color);
  		if (annots.length === 0) {
  			return "";
  		}
  		return Zotero.BetterNotes.api.convert.annotations2html(annots, {
  			noteItem: targetNoteItem,
  		});
  	}
  
  	const getIdentifier = () => {
  		const citationKey = topItem.getField("citationKey");
  		if (citationKey) {
  			return citationKey;
  		}
  		const creators = topItem.getCreators();
  		if (creators.length === 0) {
  			return "No author";
  		}
  		const year = topItem.getField("year");
  		return `${creators[0].lastName}, ${year}`;
  	};
  
  	const itemHeader = `<h2>${getIdentifier()} <br/>
  						<i>${topItem.getField("title")}</i></h2>`;
  
  	const attachments = Zotero.Items.get(topItem.getAttachments())
  		.filter((i) => i.isPDFAttachment() || i.isSnapshotAttachment() || i.isEPUBAttachment()
      );
  
  	await Promise.all(Object.keys(sharedObj.colors).map(async (color) => {
  		const annotationsPromises = attachments.map((attachment) => getAnnotationsByColor(attachment, color));
  		const renderedAnnotationsArray = await Promise.all(annotationsPromises);
  		const renderedAnnotations = renderedAnnotationsArray.filter(Boolean).join("");
  		if (renderedAnnotations) {
  			sharedObj.colors[color].annotations.push(itemHeader, renderedAnnotations);
  		}
  	}));
  
  	return "";
  }}$
  // @default-end
  
  // @afterloop-begin
  ${{
  	let output = `<h1>Annotations by color → item</h1>`;
  	for (const color in sharedObj.colors) {
  		const colorData = sharedObj.colors[color];
  		if (colorData.annotations.length > 0) {
  			output += `<h1><p style="background-color:${color}70;">${colorData.name}</p></h1>
  						${colorData.annotations.join("")}`;
  		}
  	}
  	return output;
  }}$
  // @afterloop-end

[mmkeefe]

Thank you for sharing this. When I tried it with only one file, I got the following result. It doesn't appear to be grouping by color; this is the order of the annotations in the document. I'm very new to this, so I'll explain what I did just to make sure I'm not making some silly newbie error.

1. I annotated a pdf.
2. Right click on the pdf and selected "Add Note from Annotations"
3. I opened the annotations item in a tab, clicked the 3 dots in top right pane, and selected "Insert Template"
4. I selected this template, then selected the annotations item and this is the result (below)

I feel like I'm missing something with how to use it. Please let me know if I'm doing something wrong. Thank you in advance!

[fabianlatz]

Sorry for the late reply!
It appears to me you didn't use the template as intended. Instead of generating a note from your annotations with the Zotero-integrated feature from the right-click menu, you should select the items for which the annotations of its attachments should be processed, then under the Note-icon in the Zotero menu bar (to the right of the magic wand icon for quick insert and the icon to add attachments to a library item), choose "New Standalone Note from Template" and then choose my template and choose to use your previously selected library items. This way, the note containing the attachments is generated by the Better Notes Plugin instead of Zotero itself and hence the PDFs are read correctly.
I hope this solves your issue. Feel free to contact me again if you have further questions.

[Hugbenny]

Hey,

I used your script to get one more suited to my use with a combination that allows for the refresh to work while keeping the title of the item in h1 (based on #1247 (comment)).

Here your template that i modified :

// @author [fabianlatz](https://github.com/fabianlatz)
// @link [#1272](https://github.com/windingwind/zotero-better-notes/discussions/1272)
// @beforeloop-begin
// @use-markdown
// @use-refresh
${{
	sharedObj.colors = {
			"#ffd400": { name: "📚 General", annotations: [] },  // Yellow
			"#a28ae5": { name: "💡 Hypotheses", annotations: [] }, // Purple
			"#2ea8e5": { name: "🛠️ Methods", annotations: [] }, // Blue
			"#5fb236": { name: "📊 Results", annotations: [] }, // Green
			"#f19837": { name: "🚧 Limitations", annotations: [] }, // Orange
			"#ff6666": { name: "⚠️ Attention", annotations: [] }, // Red
			"#e56eee": { name: "💭 Future Work", annotations: [] }, // Magenta
			"#aaaaaa": { name: "🗂️ Other", annotations: [] } // Grey
			};
		
	sharedObj.itemHeaders = new Set();

return "";
}}$

// @beforeloop-end

// @default-begin
${{
async function getAnnotationsByColor(_attachment, color) {
	const annots = _attachment
	.getAnnotations()
	.filter((item) => item.annotationColor === color);
	if (annots.length === 0) {
		return "";
	}
	return Zotero.BetterNotes.api.convert.annotations2html(annots, {
		noteItem: targetNoteItem,
	});
}

const getIdentifier = () => {
	const citationKey = topItem.getField("citationKey");
	if (citationKey) {
		return citationKey;
	}
	const creators = topItem.getCreators();
	if (creators.length === 0) {
		return "No author";
	}
	const year = topItem.getField("year");
	return `${creators[0].lastName}, ${year}`;
};

const itemHeader = `<i>${topItem.getField("title")}</i>`;

const attachments = Zotero.Items.get(topItem.getAttachments())
	.filter((i) => i.isPDFAttachment() || i.isSnapshotAttachment() || i.isEPUBAttachment()
	);

await Promise.all(Object.keys(sharedObj.colors).map(async (color) => {
	const annotationsPromises = attachments.map((attachment) => getAnnotationsByColor(attachment, color));
	const renderedAnnotationsArray = await Promise.all(annotationsPromises);
	const renderedAnnotations = renderedAnnotationsArray.filter(Boolean).join("");
	sharedObj.colors[color].annotations.push(`<h3>${itemHeader}</h3>`, renderedAnnotations);
	sharedObj.itemHeaders.add(itemHeader)
}));

return "";
}}$
// @default-end

// @afterloop-begin
${{
const uniqueItemHeaderCount = sharedObj.itemHeaders.size;
let output = "";

if (uniqueItemHeaderCount === 1) {
	const itemHeader = Array.from(sharedObj.itemHeaders)[0];
	output += `<h1>${itemHeader}</h1>`;
	for (const color in sharedObj.colors) {
		const colorData = sharedObj.colors[color];
		if (colorData.annotations.length > 0) {
			const filteredAnnotations = colorData.annotations.filter(annotation => annotation !== `<h3>${itemHeader}</h3>`);
			output += `<h2><p style="background-color:${color}70;">${colorData.name}</p></h2>
						${filteredAnnotations.join("")}`;
		}
	}
} else if (uniqueItemHeaderCount > 1) {
	//output += `<h1>Annotations</h1>`;
	for (const color in sharedObj.colors) {
		const colorData = sharedObj.colors[color];
		if (colorData.annotations.length > 0) {
			const itemHeader = Array.from(sharedObj.itemHeaders)[0];
			output += `<h2><p style="background-color:${color}70;">${colorData.name}</p></h2>
						${colorData.annotations.join("")}`;
		}
	}
}

return output;
}}$
// @afterloop-end

And here's the template i use to call onto the previous template and allows the refresh + the h1 title :

// @beforeloop-begin
// @beforeloop-end
// @default-begin
${{
const lastName = topItem.getCreators()[0].lastName;
const date = topItem.getField('date');
const heading = `<h1>${lastName}, ${date}</h1>`;

return heading;
}}$
// @default-end
// @afterloop-begin
${await Zotero.BetterNotes.api.template.runItemTemplate("[item]Annotations by Color and Item", {
	itemIds: items.map(item=>item.id),
	targetNoteId: targetNoteItem?.id,
	dryRun: _env.dryRun
})}
// @afterloop-end

I still have one issu though. Right now, with this template, when several items are selected i get this :

But i'd rather have an array in h1 with all the heading one after the other. Right know, i see this :

And i'd like to be
Pellestor,2018;Schuy,2024 and so on

Do you have an idea on how to do that ?

Thx !

[Hugbenny]

Here's the code with the template import :

# This template is specifically for importing/sharing, using better 
# notes 'import from clipboard': copy the content and
# goto Zotero menu bar, click Tools->New Template from Clipboard.  
# Do not copy-paste this to better notes template editor directly.
name: "[item]Annotations by Color and Item"
zoteroVersion: "7.0.15"
pluginVersion: "2.4.0"
savedAt: "2025-03-30T10:21:48.160Z"
content: |-
  // @beforeloop-begin
  // @use-markdown
  // @use-refresh
  ${{
  	sharedObj.colors = {
  			"#ffd400": { name: "📚 General", annotations: [] },  // Yellow
  			"#a28ae5": { name: "💡 Hypotheses", annotations: [] }, // Purple
  			"#2ea8e5": { name: "🛠️ Methods", annotations: [] }, // Blue
  			"#5fb236": { name: "📊 Results", annotations: [] }, // Green
  			"#f19837": { name: "🚧 Limitations", annotations: [] }, // Orange
  			"#ff6666": { name: "⚠️ Attention", annotations: [] }, // Red
  			"#e56eee": { name: "💭 Future Work", annotations: [] }, // Magenta
  			"#aaaaaa": { name: "🗂️ Other", annotations: [] } // Grey
  			};
  		
  	sharedObj.itemHeaders = new Set();
  
  return "";
  }}$
  
  // @beforeloop-end
  
  // @default-begin
  ${{
  async function getAnnotationsByColor(_attachment, color) {
  	const annots = _attachment
  	.getAnnotations()
  	.filter((item) => item.annotationColor === color);
  	if (annots.length === 0) {
  		return "";
  	}
  	return Zotero.BetterNotes.api.convert.annotations2html(annots, {
  		noteItem: targetNoteItem,
  	});
  }
  
  const getIdentifier = () => {
  	const citationKey = topItem.getField("citationKey");
  	if (citationKey) {
  		return citationKey;
  	}
  	const creators = topItem.getCreators();
  	if (creators.length === 0) {
  		return "No author";
  	}
  	const year = topItem.getField("year");
  	return `${creators[0].lastName}, ${year}`;
  };
  
  const itemHeader = `<i>${topItem.getField("title")}</i>`;
  
  const attachments = Zotero.Items.get(topItem.getAttachments())
  	.filter((i) => i.isPDFAttachment() || i.isSnapshotAttachment() || i.isEPUBAttachment()
  	);
  
  await Promise.all(Object.keys(sharedObj.colors).map(async (color) => {
  	const annotationsPromises = attachments.map((attachment) => getAnnotationsByColor(attachment, color));
  	const renderedAnnotationsArray = await Promise.all(annotationsPromises);
  	const renderedAnnotations = renderedAnnotationsArray.filter(Boolean).join("");
  	sharedObj.colors[color].annotations.push(`<h3>${itemHeader}</h3>`, renderedAnnotations);
  	sharedObj.itemHeaders.add(itemHeader)
  }));
  
  return "";
  }}$
  // @default-end
  
  // @afterloop-begin
  ${{
  const uniqueItemHeaderCount = sharedObj.itemHeaders.size;
  let output = "";
  
  if (uniqueItemHeaderCount === 1) {
  	const itemHeader = Array.from(sharedObj.itemHeaders)[0];
  	output += `<h1>${itemHeader}</h1>`;
  	for (const color in sharedObj.colors) {
  		const colorData = sharedObj.colors[color];
  		if (colorData.annotations.length > 0) {
  			const filteredAnnotations = colorData.annotations.filter(annotation => annotation !== `<h3>${itemHeader}</h3>`);
  			output += `<h2><p style="background-color:${color}70;">${colorData.name}</p></h2>
  						${filteredAnnotations.join("")}`;
  		}
  	}
  } else if (uniqueItemHeaderCount > 1) {
  	//output += `<h1>Annotations</h1>`;
  	for (const color in sharedObj.colors) {
  		const colorData = sharedObj.colors[color];
  		if (colorData.annotations.length > 0) {
  			const itemHeader = Array.from(sharedObj.itemHeaders)[0];
  			output += `<h2><p style="background-color:${color}70;">${colorData.name}</p></h2>
  						${colorData.annotations.join("")}`;
  		}
  	}
  }
  
  return output;
  }}$
  // @afterloop-end

# This template is specifically for importing/sharing, using better 
# notes 'import from clipboard': copy the content and
# goto Zotero menu bar, click Tools->New Template from Clipboard.  
# Do not copy-paste this to better notes template editor directly.
name: "[item]Annotations by Color and Item - Main"
zoteroVersion: "7.0.15"
pluginVersion: "2.4.0"
savedAt: "2025-03-30T10:25:00.272Z"
content: |-
  // @beforeloop-begin
  ${{
  		sharedObj.itemHeaders = new Set();
  
  return "";
  })}
  // @beforeloop-end
  // @default-begin
  ${{
  const lastName = topItem.getCreators()[0].lastName;
  const date = topItem.getField('date');
  
  const heading = `<h1>${lastName}, ${date}</h1>`;
  
  return heading;
  }}$
  // @default-end
  // @afterloop-begin
  ${await Zotero.BetterNotes.api.template.runItemTemplate("[item]Annotations by Color and Item", {
  	itemIds: items.map(item=>item.id),
  	targetNoteId: targetNoteItem?.id,
  	dryRun: _env.dryRun
  })}
  // @afterloop-end

[Hugbenny]

And here's the new one, with concatenation in H1 of the author and date of article for several items.

# This template is specifically for importing/sharing, using better 
# notes 'import from clipboard': copy the content and
# goto Zotero menu bar, click Tools->New Template from Clipboard.  
# Do not copy-paste this to better notes template editor directly.
name: "[item]Annotations by Color and Item - Main"
zoteroVersion: "7.0.15"
pluginVersion: "2.4.0"
savedAt: "2025-03-30T11:06:37.206Z"
content: |-
  // @beforeloop-begin
  ${{
  	sharedObj.colors = {
  			"#ffd400": { name: "📚 General", annotations: [] },  // Yellow
  			"#a28ae5": { name: "💡 Hypotheses", annotations: [] }, // Purple
  			"#2ea8e5": { name: "🛠️ Methods", annotations: [] }, // Blue
  			"#5fb236": { name: "📊 Results", annotations: [] }, // Green
  			"#f19837": { name: "🚧 Limitations", annotations: [] }, // Orange
  			"#ff6666": { name: "⚠️ Attention", annotations: [] }, // Red
  			"#e56eee": { name: "💭 Future Work", annotations: [] }, // Magenta
  			"#aaaaaa": { name: "🗂️ Other", annotations: [] } // Grey
  			};
  		
  	sharedObj.itemHeaders = new Set();
  
  return "";
  }}$
  // @beforeloop-end
  // @default-begin
  ${{
  const getIdentifier = () => {
  	const citationKey = topItem.getField("citationKey");
  	if (citationKey) {
  		return citationKey;
  	}
  	const creators = topItem.getCreators();
  	if (creators.length === 0) {
  		return "No author";
  	}
  	const year = topItem.getField("year");
  	return `${creators[0].lastName}, ${year}`;
  };
  
  const itemHeader = `${getIdentifier()}`;
  
  await Promise.all(Object.keys(sharedObj.colors).map(async (color) => {
  	sharedObj.itemHeaders.add(itemHeader)
  }));
  
  return "";
  }}$
  // @default-end
  // @afterloop-begin
  ${{
  const uniqueItemHeaderCount = sharedObj.itemHeaders.size;
  let output = "";
  
  if (uniqueItemHeaderCount === 1) {
  	const itemHeader = Array.from(sharedObj.itemHeaders)[0];
  	output += `<h1>${itemHeader}</h1>`;
  	for (const color in sharedObj.colors) {
  		const colorData = sharedObj.colors[color];
  		if (colorData.annotations.length > 0) {
  			const filteredAnnotations = colorData.annotations.filter(annotation => annotation !== `<h3>${itemHeader}</h3>`);
  			output += `<h2><p style="background-color:${color}70;">${colorData.name}</p></h2>
  						${filteredAnnotations.join("")}`;
  		}
  	}
  } else if (uniqueItemHeaderCount > 1) {
  	const concatenatedHeaders = Array.from(sharedObj.itemHeaders).join(" ; ");
      output += `<h1>${concatenatedHeaders}</h1>`;
  	for (const color in sharedObj.colors) {
  		const colorData = sharedObj.colors[color];
  		if (colorData.annotations.length > 0) {
  			const itemHeader = Array.from(sharedObj.itemHeaders)[0];
  			output += `<h2><p style="background-color:${color}70;">${colorData.name}</p></h2>
  						${colorData.annotations.join("")}`;
  		}
  	}
  }
  return output;	
  }}$
  ${
  	await Zotero.BetterNotes.api.template.runItemTemplate("[item]Annotations by Color and Item", {
  	itemIds: items.map(item=>item.id),
  	targetNoteId: targetNoteItem?.id,
  	dryRun: _env.dryRun
  	})
  }$
  // @afterloop-end

I could certainly be cleaner codewise, but it works !

[AbrieJV]

Thank you so so much @Hugbenny This works great!
Much appreciated 🥇

[Vicissitude-com]

Could you please add another piece of code before your notes? To be honest, my code level is very poor
#771

[Vicissitude-com]

I have achieved the effect I want, if you are interested in learning about my work, please go to my #1358

[iamfearless14]

hello there, thank you so much This works amazing however, when the note is created, the name is Blanck is it how it should be, or am I doing something wrong?

[fabianlatz]

Hi @iamfearless14 this is not directly intended but related to the first blocks of the note which serve the purpose of refreshing the contents of the note after new annotations have been made in the selected Zotero items. I'm unsure what happens to this functionality if you remove these blocks or insert a title above them – let us know if you find gain any insights on this!

[iamfearless14]

Hello there. Maybe I didn't explain well. Here is a screenshot. You can have a look, please. I am not that tech savvy, to be honest

.

[Hugbenny]

Try to use both templates i posted.
The absence of H1 title is indeed due to the refresh option. By using a template to call onto another, you can define an H1 title in the first template, and benefits from the refresh of the second.