Collection Tags [Share]

[garth74]

Description

Add tags corresponding to an item's collection(s). This script is intended for the item or collection menu but also works when adding new items.

When triggered from the collection menu, tag(s) are added to all items in the collection. If recursive is true, tags are added for each level of nestedness in the collection/subcollections. For example, if run on a collection named music with a subcollection named rhythm, all items in rhythm would be tagged with music and rhythm, but items in music would only be tagged with music. Only the parent collection tag is added when recursive is false.

When triggered from the item menu, tags are added based on the currently selected collection. So, running this script on an item (or items) in rhythm would only add the rhythm tag.

Event

None, createItem

Operation

Script

Data

/**
 * Add tags corresponding to an item's collection(s).
 *
 * @author garth74
 * @usage collection menu, item menu
 * @link https://github.com/windingwind/zotero-actions-tags/discussions/
 * @see https://github.com/windingwind/zotero-actions-tags/discussions/
 * @update Fri, 29 Mar 2024 19:25:37 GMT (by new Date().toGMTString())
 */

// ========================================================================== //
// EDITABLE SETTINGS
// ========================================================================== //

/**
 * @type {string} Prefix tags set during this script (e.g., "coll-tagName").
 * This makes it easier to search and remove tags later.
 */
const tagPrefix = "#";

/**
 * @type {boolean} If true, trim any leading underscore characters from the
 * collection name.
 */
const trimLeadingUnderscores = true;

/**
 * @type {boolean} If true, trim any leading numbers (i.e., 0-9) from the
 * collection name.
 */
const trimLeadingNumbers = false;

/**
 * @type {boolean} When true and triggered from the collection menu, collection
 * tags are added for each level of nestedness. For example, if run on a
 * collection named `music` with a subcollection named `rhythm`, all items in
 * `rhythm` would be tagged with `music` and `rhythm`, but items in `music`
 * would only be tagged with `music`.
 */
const recursive = true;

/**
 * @type {string[]} Names of collections to exclude from tagging.
 */
const exclude = [];

/**
 * @type {'separate' | 'path'} If 'separate', each collection name is converted
 * to a tag and set on the items. If 'path', a single collection path
 * (e.g., #Collection/SubCollection) is created.
 */
const tagStyle = "path";

// ========================================================================== //
// Main
// ========================================================================== //

/**
 * Convert the collection name to a tag.
 *
 * @param {string[]} collNames
 * @returns {string[]}
 */
function CollNames2TagNames(collNames) {
  if (trimLeadingUnderscores)
    collNames = collNames.map((c) => c.replace(/^_+/, "").trim());
  if (trimLeadingNumbers)
    collNames = collNames.map((c) => c.replace(/[0-9]+/, "").trim());
  switch (tagStyle) {
    case "separate":
      return collNames.map((c) => tagPrefix + c);
    case "path":
      return [tagPrefix + collNames.join("/")];
    default:
      throw "[Tag Collections] An error occurred while processing collection names.";
  }
}

// ========================================================================== //
// TRIGGERED IN MENU

// ======================================================================== //
// TRIGGERED IN THE COLLECTION MENU

if (collection) {
  if (item) return;
  /**
   * Recursively add the tags
   * @param {any} collection
   * @param {null | string[]} tags
   * @returns
   */
  function addTags(collection, collNames) {
    if (exclude.includes(collection.name)) return;
    collNames = collNames || [];
    // Base case
    // do not use `collNames.push`
    collNames = [...collNames, collection.name];
    let tags = CollNames2TagNames(collNames);
    for (let item of collection.getChildItems()) {
      let itemTags = item.getTags().map((t) => t.tag);
      for (let tag of tags) {
        if (!itemTags.includes(tag)) item.addTag(tag);
      }
    }
    if (recursive) {
      // Recursively apply the function to sub-collections
      for (let coll of collection.getChildCollections()) {
        addTags(coll, collNames);
      }
    }
  }

  addTags(collection);
  return "[Collection Tags] Added collection tags";
} else {
  // ======================================================================== //
  // TRIGGERED IN ITEM MENU
  collection = Zotero.getActiveZoteroPane().getSelectedCollection();
  if (!collection) return "[Collection Tags] No collection is selected";
  let collName = collection.name;
  if (exclude.includes(collName)) {
    // Early exit since it's an excluded collection
    return `[Collection Tags] ${collName} is an excluded collection`;
  }
  let tagName = CollNames2TagNames([collName])[0];
  if (!item.getTags().some((t) => t.tag === tagName)) item.addTag(tagName);
  return `[Collection Tags] Added ${tagName} tag to selected items`;
}

[al9alal]

Very useful and highly needed. Thank you very much

[chliuhq]

Thank you for providing the script. I can add tags by triggering the script manually, but I can't seem to run the script when events such as opening a document or adding an item occur. Is there any way to solve this? Thank you!

[garth74]

I've updated the script so that the behavior for triggering the script via the item menu also works when creating an item in a collection. That said, it will omit a message anytime an item is created outside a collection when the createItem trigger is enabled.

[chliuhq]

I've tested it and it runs perfectly. Thank you very much!

[chliuhq]

Hello garth74. Your script was very helpful, thank you very much.
Is it possible to implement the automatic addition of the collection tag when adding a annotated notes?
This makes it easier to manage annotated notes.

[garth74]

So, the collection variable is determined by getting whatever collection is selected when the script runs, meaning the accuracy of the annotation tagging is entirely dependent on the selected collection in the main Zotero pane. In short, it's possible, but it will likely have several unfixable bugs.

An alternative would be extending the recursive tagging to include annotations. It wouldn't run every time you added an annotation, but the tags could be added as a batch operation.

[garth74]

@chliuhq I am now realizing that "annotated notes" is a bit vague. I assumed you were talking about the annotations in a PDF, but you may have meant adding notes from annotations? If you want this to run each time you add a note, that can definitely be done.

[chliuhq]

Thanks for the answer, I was talking about adding comments to the pdf. I tried some more and the current script is working. Whenever I add highlighted notes in the pdf, zotero-action-tags automatically adds the collection as tags. This is fantastic, thanks a lot!
figure: https://github.com/windingwind/zotero-actions-tags/assets/38576927/5f7d65f1-c762-42bf-9d39-e1b8831d285a

[KateNave]

This is really nice, thank you! I'd like to have nested sub-collections combined in a single tag as "#Collection/Sub-collection" rather than as separate tags for each sub-collection. I'm not much of a coder but if you have any advice on how I could modify the script to achieve this I'd really appreciate it!

[garth74]

Try the updated version.

[KateNave]

Ah that works perfectly, thanks again :)

[sheldon123z]

Hi， this command is very helpful. However, there is a little problem when I create the #tag using the collection name, since II want to keep my collection ordered in view, I put a number or letter prefix like this
0 books
a ...,
b ... ,
1 articles,
a... ,
b...,
2 .....

and this command will also add the prefix number to the tag, so any idea to handle this?

[garth74]

I've added an argument to the script that should handle it.