Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
import {
ALLOWED_PROTOCOLS, encodeBlockParameter, resolveBlockReference
} from "@triliumnext/commons";
import appContext, { type NoteCommandData } from "../components/app_context.js";
import { openInCurrentNoteContext } from "../components/note_context.js";
import linkContextMenuService from "../menus/link_context_menu.js";
import {
getBlockReferenceLabel, getCachedBlockReferenceLabel, loadBlockReferenceLabel
} from "./block_excerpts.js";
import cssClassManager from "./css_class_manager.js";
import froca from "./froca.js";
import { t } from "./i18n.js";
import { getNoteImageUrl } from "./image_urls.js";
import { showError } from "./toast.js";
import treeService from "./tree.js";
import utils, { isShare } from "./utils.js";
/** The icon a column reference uses when the link carries no `columnIcon`. */
const DEFAULT_COLUMN_REFERENCE_ICON = "bx bx-columns";
const MISSING_NOTE_TITLE = "[missing note]";
function getNotePathFromUrl(url: string) {
const notePathMatch = /#(root[A-Za-z0-9_/]*)$/.exec(url);
return notePathMatch === null ? null : notePathMatch[1];
}
async function getLinkIcon(noteId: string, viewMode: ViewMode | undefined) {
let icon;
if (!viewMode || viewMode === "default") {
const note = await froca.getNote(noteId);
icon = note?.getIcon();
} else if (viewMode === "source") {
icon = "tn-icon bx bx-code-curly";
} else if (viewMode === "attachments") {
icon = "tn-icon bx bx-file";
}
return icon;
}
export type ViewMode = "default" | "source" | "attachments" | "contextual-help" | "note-map";
export interface ViewScope {
/**
* - "source", when viewing the source code of a note.
* - "attachments", when viewing the attachments of a note.
* - "contextual-help", if the current view represents a help window that was opened to the side of the main content.
* - "default", otherwise.
*/
viewMode?: ViewMode;
attachmentId?: string;
readOnlyTemporarilyDisabled?: boolean;
/**
* If true, it indicates that the note in the view should be opened in read-only mode (for supported note types such as text or code).
*
* The reason why we store this information here is that a note can become read-only as the user types content in it, and we wouldn't want
* to immediately enter read-only mode.
*/
isReadOnly?: boolean;
/**
* If true, a text note is edited with the floating toolbar whatever the user's editor-type
* option says — the toolbar following the selection rather than standing in a bar of its own.
*
* For views too narrow to carry a full toolbar, such as the geo map's marker pane: a classic bar
* built for the width of a note either spills out of them or eats the room the note is left.
*/
floatingToolbar?: boolean;
/** When set, scrolls to a bookmark anchor within the note after navigation. */
bookmark?: string;
/**
* The blocks of a text note a reference points at, `id` or `startId:endId`, which the note
* scrolls to and flashes once it renders. Consumed once, as `bookmark` is.
*/
block?: string;
/**
* Search terms to highlight and jump to after navigating from search results; consumed once
* by the destination type widget (mirrors `bookmark` semantics).
*/
searchTerms?: string[];
/**
* The id of the board column a reference points at, which the board reveals once it has drawn
* it. Consumed once, as `bookmark` is.
*/
column?: string;
/**
* The title, icon and colour a column reference renders as, copied from the board when the
* reference was made. Carried in the link because reading them needs the board's own
* configuration; {@link column} is what the board resolves, so a rename only dates the label.
*/
columnTitle?: string;
columnIcon?: string;
columnColor?: string;
/**
* The note id of the board card a reference points at, revealed the same way {@link column}
* is.
*/
card?: string;
/**
* The PDF page a reference points at, which the PDF viewer turns to once it has opened the
* document. Consumed once, as `bookmark` is.
*/
page?: string;
/**
* The id of the PDF annotation a reference points at, which the viewer scrolls to on
* {@link page}. A reference to an annotation always carries its page too, so a deleted
* annotation still leaves the reader on the right page.
*/
annotation?: string;
}
/**
* The state of a single split pane, as carried by the `splits` hash parameter when a tab is
* moved or copied into a window of its own.
*/
export interface HashPane {
notePath?: string | null;
hoistedNoteId?: string | null;
viewScope?: ViewScope;
}
/** A note path as it may appear in a hash: slash-separated note ids. */
const NOTE_PATH_PATTERN = /^[_a-z0-9]{4,}(\/[_a-z0-9]{4,})*$/i;
/**
* How many extra panes a hash is allowed to carry. Well beyond any layout a user would build by
* hand, but low enough that a hand-written address can't ask the app to open hundreds of panes.
*/
const MAX_SPLIT_PANES_IN_HASH = 8;
/** Hash parameters that belong to a pane's view scope rather than to the window as a whole. */
const VIEW_SCOPE_PARAMS = ["viewMode", "attachmentId", "bookmark", "block", "column",
"columnTitle", "columnIcon", "columnColor", "card", "page", "annotation"];
interface CreateLinkOptions {
title?: string;
showTooltip?: boolean;
showNotePath?: boolean;
showNoteIcon?: boolean;
referenceLink?: boolean;
autoConvertToImage?: boolean;
viewScope?: ViewScope;
/**
* Inline text appended right after the link title (before the note path, which renders on its
* own line). Rendered as a `.note-link-suffix` span so it rides the title's baseline instead of
* being pushed into a column by the wider note-path block — e.g. an annotation on why the note
* is being shown.
*/
titleSuffix?: string;
}
async function createLink(notePath: string | undefined, options: CreateLinkOptions = {}) {
if (!notePath || !notePath.trim()) {
logError("Missing note path");
return $("<span>").text(MISSING_NOTE_TITLE);
}
if (!notePath.startsWith("root")) {
// all note paths should start with "root/" (except for "root" itself)
// used, e.g., to find internal links
notePath = `root/${notePath}`;
}
const showTooltip = options.showTooltip === undefined ? true : options.showTooltip;
const showNotePath = options.showNotePath === undefined ? false : options.showNotePath;
const showNoteIcon = options.showNoteIcon === undefined ? false : options.showNoteIcon;
const referenceLink = options.referenceLink === undefined ? false : options.referenceLink;
const autoConvertToImage = options.autoConvertToImage === undefined ? false : options.autoConvertToImage;
const { noteId, parentNoteId } = treeService.getNoteIdAndParentIdFromUrl(notePath);
if (!noteId) {
logError("Missing note ID");
return $("<span>").text(MISSING_NOTE_TITLE);
}
const viewScope = options.viewScope || {};
const viewMode = viewScope.viewMode || "default";
let linkTitle = options.title;
if (linkTitle === undefined) {
/* v8 ignore start -- the implicit `else` of this chain (noteId falsy) is unreachable: an empty noteId already returned at the guard above */
if (viewMode === "attachments" && viewScope.attachmentId) {
const attachment = await froca.getAttachment(viewScope.attachmentId);
linkTitle = attachment ? attachment.title : "[missing attachment]";
} else if (noteId) {
linkTitle = await treeService.getNoteTitle(noteId, parentNoteId);
}
/* v8 ignore stop */
}
const note = await froca.getNote(noteId);
if (autoConvertToImage && note?.type && ["image", "canvas", "mermaid"].includes(note.type) && viewMode === "default") {
return $("<img>")
.attr("src", getNoteImageUrl(noteId, linkTitle || "", String(Math.random())))
.attr("alt", linkTitle || "");
}
const $container = $("<span>");
if (showNoteIcon) {
const icon = await getLinkIcon(noteId, viewMode);
if (icon) {
$container.append($("<span>").addClass(`bx ${icon}`)).append(" ");
}
}
const hash = calculateHash({
notePath,
viewScope
});
const $noteLink = $("<a>", {
href: hash,
text: linkTitle
});
if (!showTooltip) {
$noteLink.addClass("no-tooltip-preview");
}
if (referenceLink) {
$noteLink.addClass("reference-link");
}
$container.append($noteLink);
if (options.titleSuffix) {
$container.append($("<span>").addClass("note-link-suffix").text(options.titleSuffix));
}
if (showNotePath) {
let pathSegments: string[];
if (notePath == "root") {
pathSegments = ["⌂"];
} else {
const resolvedPathSegments = (await treeService.resolveNotePathToSegments(notePath)) || [];
resolvedPathSegments.pop(); // Remove last element
const resolvedPath = resolvedPathSegments.join("/");
pathSegments = await treeService.getNotePathTitleComponents(resolvedPath);
}
/* v8 ignore next 2 -- defensive guards: pathSegments is always a non-empty array (getNotePathTitleComponents never returns empty, and the root case yields ["⌂"]) */
if (pathSegments) {
if (pathSegments.length) {
$container.append($("<small>").append(treeService.formatNotePath(pathSegments)));
}
}
}
return $container;
}
export function calculateHash(
{ notePath, ntxId, hoistedNoteId, viewScope = {}, splits, activeSplit }: NoteCommandData
) {
notePath = notePath || "";
const params = [
ntxId ? { ntxId } : null,
hoistedNoteId && hoistedNoteId !== "root" ? { hoistedNoteId } : null,
viewScope.viewMode && viewScope.viewMode !== "default" ? { viewMode: viewScope.viewMode } : null,
viewScope.attachmentId ? { attachmentId: viewScope.attachmentId } : null,
viewScope.block ? { block: viewScope.block } : null,
viewScope.column ? { column: viewScope.column } : null,
viewScope.columnTitle ? { columnTitle: viewScope.columnTitle } : null,
viewScope.columnIcon ? { columnIcon: viewScope.columnIcon } : null,
viewScope.columnColor ? { columnColor: viewScope.columnColor } : null,
viewScope.card ? { card: viewScope.card } : null,
viewScope.page ? { page: viewScope.page } : null,
viewScope.annotation ? { annotation: viewScope.annotation } : null,
viewScope.searchTerms?.length
? { searchTerms: viewScope.searchTerms.map(encodeURIComponent).join(",") }
: null,
splits?.length ? { splits: splits.map(encodeSplitPane).join(",") } : null,
splits?.length && activeSplit ? { activeSplit: String(activeSplit) } : null
].filter((p) => !!p);
const paramStr = params
.map((pair) => {
const name = Object.keys(pair)[0];
const value = (pair as Record<string, string | undefined>)[name];
/* v8 ignore next -- `value` is never undefined: every retained pair holds a string. It
can be empty, but only for a `splits` list whose panes are all empty. */
const encodedValue = name === "block"
? encodeBlockParameter(value || "")
: encodeURIComponent(value || "");
return `${encodeURIComponent(name)}=${encodedValue}`;
})
.join("&");
if (!notePath && !paramStr) {
return "";
}
let hash = `#${notePath}`;
if (paramStr) {
hash += `?${paramStr}`;
}
return hash;
}
/**
* Serializes one extra pane into an entry of the `splits` parameter: its own hash body, minus the
* leading `#`. Entries are joined with commas, which is unambiguous because neither a note path nor
* an encoded parameter value can contain one. A pane holding no note yields an empty entry, so that
* the pane count of the original tab survives the trip.
*/
function encodeSplitPane(pane: HashPane) {
return calculateHash(pane).slice(1);
}
/** The subset of `window.location` needed to build a URL, which a plain `URL` also satisfies. */
interface UrlParts {
protocol: string;
host: string;
pathname: string;
search: string;
}
/**
* Builds the address of a detached ("extra") window showing the given target.
*
* The current query string is carried over rather than replaced. On the server it holds nothing of
* interest, but in standalone the query *is* the environment (`?safeMode`, `?startNoteId` — see
* `QUERY_TO_ENV` in the standalone platform provider), so a window that dropped it would boot with
* different settings than the one it was opened from, and would apply those to every other window
* should it later inherit the database lock.
*/
export function calculateExtraWindowUrl(target: NoteCommandData, location: UrlParts = window.location) {
const params = new URLSearchParams(location.search);
params.set("extraWindow", "1");
return `${location.protocol}//${location.host}${location.pathname}?${params}${calculateHash(target)}`;
}
/** Whether the query string of `url` (everything before `hashIdx`) carries the `extraWindow` marker. */
function isExtraWindowUrl(url: string, hashIdx: number) {
return /[?&]extraWindow(?:[=&]|$)/.test(url.slice(0, hashIdx));
}
/**
* Parses the navigation state in the hash of `url`. A full URL is internal when it addresses the
* document at `location` or has an accepted internal form. Any other URL is external: `{}`.
*/
export function parseNavigationStateFromUrl(
url: string | undefined,
location: UrlParts = window.location
) {
if (!url) {
return {};
}
url = url.trim();
const hashIdx = url.indexOf("#");
if (hashIdx === -1) {
return {};
}
const isExtraWindow = isExtraWindowUrl(url, hashIdx);
// Exclude external links that contain #
if (
hashIdx !== 0
&& !url.includes("/#root")
&& !url.includes("/#?searchString")
&& !isExtraWindow
&& !isSameDocumentUrl(url, hashIdx, location)
) {
return {};
}
const hash = url.substr(hashIdx + 1); // strip also the initial '#'
const [notePath, paramString] = hash.split("?");
const viewScope: ViewScope = {
viewMode: "default"
};
let ntxId: string | null = null;
let hoistedNoteId: string | null = null;
let searchString: string | null = null;
let openInPopup = false;
let splits: HashPane[] | null = null;
let activeSplit = 0;
for (const [name, value] of parseHashParams(paramString)) {
if (name === "ntxId") {
ntxId = value;
} else if (name === "hoistedNoteId") {
hoistedNoteId = value;
} else if (name === "searchString") {
searchString = value; // supports triggering search from URL, e.g. #?searchString=blabla
} else if (name === "searchTerms") {
// `value` already went through one decodeURIComponent() in parseHashParams (undoing the
// generic pipeline's outer encode); each comma-separated token needs its own inner decode.
// A malformed token (corrupted URL, hand-edited link) must not break navigation for
// the rest of the link, so drop it rather than letting decodeURIComponent throw.
viewScope.searchTerms = value
.split(",")
.map((token) => {
try {
return decodeURIComponent(token);
} catch {
return null;
}
})
.filter((token): token is string => token !== null);
} else if (VIEW_SCOPE_PARAMS.includes(name)) {
(viewScope as any)[name] = value;
} else if (name === "popup") {
openInPopup = true;
} else if (name === "splits") {
// Splits lay out the whole window, so they are honoured only while booting a
// detached one. A link inside a note reaches this same parser, and no note should
// be able to rearrange the panes of the window it is read in.
splits = isExtraWindow ? parseSplitPanes(value) : null;
} else if (name === "activeSplit") {
activeSplit = Number.parseInt(value, 10) || 0;
} else {
console.warn(`Unrecognized hash parameter '${name}'.`);
}
}
if (searchString) {
return { searchString };
}
// A hash carrying splits is one we wrote ourselves, so its main pane may hold no note —
// that is how a tab whose first pane was empty keeps the rest of its panes.
const isEmptyMainPaneWithSplits = !notePath && !!splits?.length;
if (!isEmptyMainPaneWithSplits && !NOTE_PATH_PATTERN.test(notePath)) {
return {};
}
return {
notePath,
noteId: treeService.getNoteIdFromUrl(notePath),
ntxId,
hoistedNoteId,
viewScope,
searchString,
openInPopup,
splits,
activeSplit
};
}
/** Whether `url` addresses the document at `location`, query string included, hash ignored. */
function isSameDocumentUrl(url: string, hashIdx: number, location: UrlParts) {
const documentUrl = url.slice(0, hashIdx);
const { protocol, host, pathname, search } = location;
return documentUrl === `${protocol}//${host}${pathname}${search}`;
}
/** Iterates the `name=value` pairs of a hash's parameter string, decoding both sides. */
function parseHashParams(paramString: string | undefined) {
if (!paramString) {
return [];
}
return paramString.split("&").map((pair) => {
const [name, value] = pair.split("=");
return [decodeURIComponent(name), decodeURIComponent(value ?? "")] as const;
});
}
/**
* Parses the `splits` parameter — the panes that stood beside the main one, in order. Entries that
* aren't a well-formed pane are dropped rather than failing the whole hash, so a mangled address
* still opens what it can.
*/
function parseSplitPanes(value: string): HashPane[] {
return value
.split(",")
.slice(0, MAX_SPLIT_PANES_IN_HASH)
.map(parseSplitPane)
.filter((pane) => !!pane);
}
function parseSplitPane(entry: string): HashPane | null {
const [notePath, paramString] = entry.split("?");
// An empty entry is a pane that held no note; anything else has to be a real note path.
if (notePath && !NOTE_PATH_PATTERN.test(notePath)) {
return null;
}
const pane: HashPane = {
notePath: notePath || null,
hoistedNoteId: null,
viewScope: { viewMode: "default" }
};
for (const [name, paramValue] of parseHashParams(paramString)) {
if (name === "hoistedNoteId") {
pane.hoistedNoteId = paramValue;
} else if (VIEW_SCOPE_PARAMS.includes(name)) {
(pane.viewScope as any)[name] = paramValue;
}
// Everything else — `ntxId`, `searchString`, a nested `splits` — describes a window rather
// than a pane, and has no meaning this far down.
}
return pane;
}
/**
* Interactive content that handles its own clicks opts out of link navigation by carrying this class. It is
* needed where such content sits inside a link — a media player in a collection card, whose card is itself a
* `.block-link` — so that pressing play doesn't also open the note. Marking the content is what lets its
* clicks keep bubbling to the document, which the Bootstrap dropdowns inside it rely on; stopping propagation
* at the player would kill link navigation and those dropdowns alike.
*/
const NO_LINK_NAVIGATION_SELECTOR = ".no-link-navigation";
function goToLink(evt: MouseEvent | JQuery.ClickEvent | JQuery.MouseDownEvent) {
const $target = $(evt.target as any);
if ($target.closest(NO_LINK_NAVIGATION_SELECTOR).length) {
return false;
}
const $link = $target.closest("a,.block-link");
const hrefLink = $link.attr("href") || $link.attr("data-href");
return goToLinkExt(evt, hrefLink, $link);
}
/**
* Handles navigation to a link, which can be an internal note path (e.g., `#root/1234`) or an external URL (e.g., `https://example.com`).
*
* @param evt the event that triggered the link navigation, or `null` if the link was clicked programmatically. Used to determine if the link should be opened in a new tab/window, based on the button presses.
* @param hrefLink the link to navigate to, which can be a note path (e.g., `#root/1234`) or an external URL with any supported protocol (e.g., `https://example.com`).
* @param $link the jQuery element of the link that was clicked, used to determine if the link is an anchor link (e.g., `#fn1` or `#fnref1`) and to handle it accordingly.
* @returns `true` if the link was handled (i.e., the element was found and scrolled to), or a falsy value otherwise.
*/
export function goToLinkExt(evt: MouseEvent | JQuery.ClickEvent | JQuery.MouseDownEvent | React.PointerEvent<HTMLCanvasElement> | null, hrefLink: string | undefined, $link?: JQuery<HTMLElement> | null) {
if (hrefLink?.startsWith("data:")) {
return true;
}
// The preview button of the text editor's link toolbar acts on its clicks alone, and the
// editor has handled a click that jumped into the note itself.
if (evt && $link?.hasClass("ck-link-toolbar__preview")
&& (evt.type === "dblclick" || isDefaultPrevented(evt))) {
return true;
}
evt?.preventDefault();
evt?.stopPropagation();
if (hrefLink && hrefLink.startsWith("#") && !hrefLink.startsWith("#root/") && $link) {
if (handleAnchor(hrefLink, $link)) {
return true;
}
}
const { notePath, noteId, viewScope, openInPopup } = parseNavigationStateFromUrl(hrefLink);
const ctrlKey = evt && utils.isCtrlKey(evt);
const shiftKey = evt?.shiftKey;
const isLeftClick = !evt || ("which" in evt && evt.which === 1);
// Right click is handled separately.
const isMiddleClick = evt && "which" in evt && evt.which === 2;
// The preview button of the text editor's link toolbar opens a note in place, as a link does.
const isLinkToolbarPreview = !!$link?.hasClass("ck-link-toolbar__preview");
const targetIsBlank = $link?.attr("target") === "_blank" && !isLinkToolbarPreview;
const isDoubleClick = isLeftClick && evt?.type === "dblclick";
const openInNewTab = (isLeftClick && (ctrlKey || targetIsBlank)) || isDoubleClick || isMiddleClick;
const activate = (isLeftClick && ctrlKey && shiftKey) || (isMiddleClick && shiftKey);
const openInNewWindow = isLeftClick && evt?.shiftKey && !ctrlKey;
const isPlainLeftClick = isLeftClick && !ctrlKey && !shiftKey && !isDoubleClick;
if (notePath) {
if (isPlainLeftClick && $link && isInEditableText($link)) {
// The text editor shows the link toolbar, whose preview button opens the note.
return true;
}
// A link to blocks of the note it is in acts as a link within a page.
if (isPlainLeftClick && !openInPopup && !targetIsBlank && $link && viewScope?.block
&& showBlocksInPlace($link, noteId, viewScope.block)) {
return true;
}
if (isLeftClick && openInPopup) {
appContext.triggerCommand("openInPopup", { noteIdOrPath: notePath, viewScope });
} else if (openInNewWindow) {
appContext.triggerCommand("openInWindow", { notePath, viewScope });
} else if (openInNewTab) {
appContext.tabManager.openTabWithNoteWithHoisting(notePath, {
activate: activate ? true : targetIsBlank,
viewScope,
placement: "afterCurrent"
});
} else if (isLeftClick) {
openInCurrentNoteContext(evt, notePath, viewScope);
}
} else if (hrefLink) {
const outsideOfCKEditor = !$link || $link.closest("[contenteditable]").length === 0;
if (openInNewTab || openInNewWindow || (isLeftClick && (isLinkToolbarPreview || outsideOfCKEditor))) {
if (hrefLink.toLowerCase().startsWith("http") || hrefLink.startsWith("api/")) {
window.open(hrefLink, "_blank");
} else if (ALLOWED_PROTOCOLS.some((protocol) => hrefLink.toLowerCase().startsWith(`${protocol}:`))) {
// Enable protocols supported by CKEditor 5 to be clickable.
if (window.electronApi) {
const reportLinkError = (e: unknown) => {
const message = e instanceof Error ? e.message : String(e);
logError(`Failed to open link '${hrefLink}': ${message}`);
showError(t("link.failed_to_open", { href: hrefLink, message }));
};
if (hrefLink.toLowerCase().startsWith("file:")) {
// The main process resolves the URL to a path and picks the dispatch
// that works per platform; shell.openExternal alone mishandles Unicode
// file:// URLs on Windows.
window.electronApi.shell.openFileUrl(hrefLink).then((err: string) => {
if (err) reportLinkError(new Error(err));
}).catch(reportLinkError);
} else {
window.electronApi.shell.openExternal(hrefLink);
}
} else {
window.open(hrefLink, "_blank");
}
}
}
}
return true;
}
/** Whether `$link` is in the content of an editable text note, rather than in an embed in it. */
function isInEditableText($link: JQuery<HTMLElement>) {
return $link.closest(".ck-content").hasClass("note-detail-editable-text-editor");
}
/**
* Scrolls to either the footnote (if clicking on a reference such as `[1]`), or to the reference of a footnote (if clicking on the footnote `^` arrow),
* or CKEditor bookmarks.
*
* @param hrefLink the URL of the link that was clicked (it should be in the form of `#fn` or `#fnref`).
* @param $link the element of the link that was clicked.
* @returns `true` if the link was handled (i.e., the element was found and scrolled to), `false` otherwise.
*/
function handleAnchor(hrefLink: string, $link: JQuery<HTMLElement>) {
const content = $link.closest(".ck-content")[0];
const name = hrefLink.slice(1);
// Exact comparison: an anchor name can hold characters that a CSS selector does not allow.
const isFound = !!content
&& Array.from(content.querySelectorAll("[id]")).some((element) => element.id === name);
if (isFound) {
void loadBlockJump().then(({ showAnchor }) => showAnchor(content, name));
}
return isFound;
}
/**
* Scrolls to the blocks `block` of the note `noteId` and flashes them, when `$link` is in the
* content of that note that holds them. Returns whether it does.
*/
function showBlocksInPlace($link: JQuery<HTMLElement>, noteId: string | null, block: string) {
const content = $link.closest(".ck-content")[0];
const ntxId = $link.closest("[data-ntx-id]").attr("data-ntx-id");
if (!content || !ntxId || appContext.tabManager.getNoteContextById(ntxId).noteId !== noteId) {
return false;
}
// A broken range is left to the note context, which also shows the error.
const { start, end } = resolveBlockReference(content, block);
if (!start || !end) {
return false;
}
void loadBlockJump().then(({ showBlockReference }) => showBlockReference(content, block));
return true;
}
/** Whether something before `goToLinkExt()` already took the default action of `evt`. */
function isDefaultPrevented(evt: NonNullable<Parameters<typeof goToLinkExt>[0]>) {
return "isDefaultPrevented" in evt ? evt.isDefaultPrevented() : evt.defaultPrevented;
}
/** The module that scrolls to blocks and anchors and flashes them, loaded on first use. */
function loadBlockJump() {
return import("@triliumnext/ckeditor5/src/plugins/block_reference/block_reference_read_only.js");
}
function linkContextMenu(e: PointerEvent) {
const $link = $(e.target as any).closest("a");
const url = $link.attr("href") || $link.attr("data-href");
if ($link.attr("data-no-context-menu")) {
return;
}
const { notePath, viewScope } = parseNavigationStateFromUrl(url);
if (!notePath) {
return;
}
if (utils.isCtrlKey(e) && e.button === 2) {
appContext.triggerCommand("openInPopup", { noteIdOrPath: notePath, viewScope });
e.preventDefault();
return;
}
e.preventDefault();
linkContextMenuService.openContextMenu(notePath, e, viewScope, null);
}
/**
* Fills `$el` with the label of the reference link to `href`. A link to blocks of `hostNoteId`, the
* note the link is in, shows only the text of the blocks, read from `content` when it holds them,
* as an editor does. When `isExcerpt`, `content` holds only some blocks of the note, and the others
* are read from the saved note. A link to a note that does not exist shows `storedTitle`, the title
* the content holds for it.
*/
async function loadReferenceLinkTitle(
$el: JQuery<HTMLElement>,
href: string | null | undefined = null,
hostNoteId?: string,
storedTitle?: string,
content?: ParentNode | null,
isExcerpt = false
) {
const $link = $el[0].tagName === "A" ? $el : $el.find("a");
href = href || $link.attr("href");
if (!href) {
console.warn(`Empty URL for parsing: ${$el[0].outerHTML}`);
return;
}
const { noteId, viewScope } = parseNavigationStateFromUrl(href);
if (!noteId) {
// Not returned on: the editing downcast creates an empty <span> that only this call fills.
// An attachment image URL, an external link or imported HTML can carry such an href.
console.warn("Missing note ID.");
}
// A card reference holds the board in its path and the card in `card`. The link renders the
// card; the path is what it opens.
const subjectId = viewScope?.card || noteId;
const note = subjectId ? await froca.getNote(subjectId, true) : null;
if (viewScope?.block && note && (content || noteId === hostNoteId)) {
const liveLabel = content ? getBlockReferenceLabel(content, viewScope.block) : null;
const label = liveLabel && !(liveLabel.isBroken && isExcerpt)
? liveLabel
: await loadBlockReferenceLabel(note, viewScope.block) ?? liveLabel;
if (label) {
$el.text(label.text).toggleClass("block-reference-broken", label.isBroken);
if (!label.isHeading) {
$el.prepend($("<span>").addClass("tn-icon bx bx-paragraph"));
}
return;
}
}
if (!note) {
$el.text(storedTitle || MISSING_NOTE_TITLE)
.addClass("reference-link-missing no-link-navigation")
.prepend($("<span>").addClass("tn-icon bx bx-x"));
return;
}
$el.addClass(note.getColorClass());
const title = await getReferenceLinkTitle(href);
// A column reference renders as "<board>: <column>", the column in a `<small>` below.
$el.text(viewScope?.columnTitle ? `${title}:` : title);
if (viewScope?.bookmark) {
$el.append($("<small>").append(
$("<span>").addClass("bx bx-bookmark"),
document.createTextNode(viewScope.bookmark)
));
}
if (viewScope?.block) {
const label = await loadBlockReferenceLabel(note, viewScope.block);
if (label) {
$el.append($("<small>")
.toggleClass("block-reference-broken", label.isBroken)
.append(
$("<span>").addClass("bx bx-paragraph"),
document.createTextNode(label.text)
));
}
}
if (viewScope?.page) {
$el.append($("<small>").append(
$("<span>").addClass(viewScope.annotation ? "bx bx-comment-detail" : "bx bx-file"),
document.createTextNode(getPdfReferenceLabel(viewScope.page, viewScope.annotation))
));
}
if (viewScope?.columnTitle) {
$el.append($("<small>")
.addClass(cssClassManager.createClassForColor(viewScope.columnColor ?? null))
.append(
$("<span>").addClass(viewScope.columnIcon || DEFAULT_COLUMN_REFERENCE_ICON),
document.createTextNode(` ${viewScope.columnTitle}`)
));
}
const icon = await getLinkIcon(note.noteId, viewScope?.viewMode);
if (icon) {
$el.prepend($("<span>").addClass(icon));
}
}
async function getReferenceLinkTitle(href: string) {
const { noteId, viewScope } = parseNavigationStateFromUrl(href);
if (!noteId) {
return MISSING_NOTE_TITLE;
}
// A card reference is titled by the card, not by the board in its path.
const note = await froca.getNote(viewScope?.card || noteId);
if (!note) {
return MISSING_NOTE_TITLE;
}
if (viewScope?.viewMode === "attachments" && viewScope?.attachmentId) {
// `froca.getAttachmentOfNote()` reloads the attachments when the cached list lacks it.
const attachment = await froca.getAttachmentOfNote(noteId, viewScope.attachmentId);
return attachment ? attachment.title : "[missing attachment]";
}
return note.title;
}
/**
* The label of the reference link to `href`, from the notes already in froca. A link to a note that
* is not there gets `storedTitle`, the title the content holds for it. A link to blocks of
* `content`, the content the link is in, gets their text. When `isExcerpt`, `content` holds only
* some blocks of the note, and the others are read from the saved note.
*/
function getReferenceLinkTitleSync(
href: string, storedTitle?: string, content?: ParentNode | null, isExcerpt = false
) {
const { noteId, viewScope } = parseNavigationStateFromUrl(href);
if (!noteId) {
return storedTitle || MISSING_NOTE_TITLE;
}
const note = froca.getNoteFromCache(viewScope?.card || noteId);
if (content && viewScope?.block) {
const label = getBlockReferenceLabel(content, viewScope.block);
const savedLabel = label.isBroken && isExcerpt && note
? getCachedBlockReferenceLabel(note, viewScope.block)
: null;
return (savedLabel ?? label).text;
}
if (!note) {
return storedTitle || MISSING_NOTE_TITLE;
}
if (viewScope?.viewMode === "attachments" && viewScope?.attachmentId) {
if (!note.attachments) {
return "[loading title...]";
}
const attachment = note.attachments.find((att) => att.attachmentId === viewScope.attachmentId);
return attachment ? attachment.title : "[missing attachment]";
}
if (viewScope?.columnTitle) {
return `${note.title}: ${viewScope.columnTitle}`;
}
if (viewScope?.bookmark) {
return `${note.title} - ${viewScope.bookmark}`;
}
const blockLabel = viewScope?.block
? getCachedBlockReferenceLabel(note, viewScope.block)
: null;
if (blockLabel && !blockLabel.isBroken) {
return `${note.title} - ${blockLabel.text}`;
}
if (viewScope?.page) {
return `${note.title} - ${getPdfReferenceLabel(viewScope.page, viewScope.annotation)}`;
}
return note.title;
}
/** What a reference to a PDF says after the title: the page, or the annotation on it. */
function getPdfReferenceLabel(pageNumber: string, annotation: string | undefined) {
return t(annotation ? "pdf.annotation_reference" : "pdf.page_reference", { pageNumber });
}
// A shared page hosting an app view keeps its links as plain links to other shared pages.
/* v8 ignore next -- the `print` device branch is evaluated once at module load; under test glob.device is undefined, so the false arm cannot be exercised */
if (glob.device !== "print" && !isShare) {
// TODO: Check why the event is not supported.
//@ts-ignore
$(document).on("click", "a", goToLink);
// TODO: Check why the event is not supported.
//@ts-ignore
$(document).on("auxclick", "a", goToLink); // to handle the middle button
// TODO: Check why the event is not supported.
//@ts-ignore
$(document).on("contextmenu", "a", linkContextMenu);
// TODO: Check why the event is not supported.
//@ts-ignore
$(document).on("dblclick", "a", goToLink);
$(document).on("mousedown", "a", (e) => {
if (e.which === 2) {
// prevent paste on middle click
// https://github.com/zadam/trilium/issues/2995
// https://developer.mozilla.org/en-US/docs/Web/API/Element/auxclick_event#preventing_default_actions
e.preventDefault();
return false;
}
});
}
export default {
getNotePathFromUrl,
createLink,
goToLink,
goToLinkExt,
loadReferenceLinkTitle,
getReferenceLinkTitle,
getReferenceLinkTitleSync,
calculateHash,
calculateExtraWindowUrl,
parseNavigationStateFromUrl
};