Skip to content

Build your personal knowledge base with Trilium Notes

feat(web-clipper): preview the page before saving it from the popup

Elian Doranfaff46b923d1
diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Installation & Setup/Web Clipper.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Installation & Setup/Web Clipper.html
index fa253f5353..4a57050fbd 100644
--- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Installation & Setup/Web Clipper.html
+++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Installation & Setup/Web Clipper.html
@@ -34,7 +34,14 @@
dot (green when connected, amber when the versions are not compatible,
red when Trilium was not found), next to the buttons for the extension's
options and for this help page.</li>
- <li><em>Save whole page</em> is the main action. Below it are <em>Crop screenshot</em>, <em>Visible area screenshot</em>, <em>Link with a note</em> and <em>All tabs in window</em> (which
+ <li>The popup reads the current page as an article and shows a preview of
+ what will be saved: the note's title, which can be edited before saving,
+ the website and the publication date (when the page states one), and the
+ article's text and images. <em>Save page to Trilium</em> saves it. Pages
+ the extension cannot read, such as the browser's own pages, say so instead.
+ The keyboard shortcut and the context menu still save the page right away,
+ without a preview.</li>
+ <li>Below the preview are <em>Crop screenshot</em>, <em>Visible area screenshot</em>, <em>Link with a note</em> and <em>All tabs in window</em> (which
saves the links of every tab in the current window as a list). An action
that has a keyboard shortcut shows it.</li>
<li><em>Link with a note</em> opens a small editor in place of the actions.
diff --git a/apps/web-clipper/entrypoints/background/index.spec.ts b/apps/web-clipper/entrypoints/background/index.spec.ts
index 463a3af12c..961568f322 100644
--- a/apps/web-clipper/entrypoints/background/index.spec.ts
+++ b/apps/web-clipper/entrypoints/background/index.spec.ts
@@ -288,6 +288,26 @@ describe("background", () => {
await onCommand("saveWholePage");
expect(await lastToast()).toMatchObject(FAILURE_TOAST);
});
+
+ it("saves the page the popup extracted, with the user's title, without reading it again", async () => {
+ const page = {
+ title: "Edited title",
+ content: `<img src="i1">`,
+ images: [ { imageId: "i1", src: "https://example.com/a.png" } ],
+ pageUrl: PAGE_URL,
+ clipType: "page",
+ labels: {}
+ };
+
+ await sendRuntimeMessage({ name: "save-whole-page", page });
+
+ expect(tabsSendMessage).not.toHaveBeenCalledWith(7, { name: "trilium-save-page" });
+ expect(facade.callService).toHaveBeenCalledWith("POST", "notes", {
+ ...page,
+ images: [ { ...page.images[0], dataUrl: expect.stringMatching(PNG_DATA_URL) } ]
+ });
+ expect(await lastToast()).toMatchObject({ message: "Page has been saved to Trilium.", noteId: "saved" });
+ });
});
describe("screenshots", () => {
diff --git a/apps/web-clipper/entrypoints/background/index.ts b/apps/web-clipper/entrypoints/background/index.ts
index e6e2770350..0750288395 100644
--- a/apps/web-clipper/entrypoints/background/index.ts
+++ b/apps/web-clipper/entrypoints/background/index.ts
@@ -314,8 +314,9 @@ export default defineBackground(() => {
toast(savedMessage("Image", failedImages), resp.noteId);
}
- async function saveWholePage() {
- const payload = await requestFromPage({name: 'trilium-save-page'});
+ /** Saves the readable page, or the page the popup already extracted and the user edited. */
+ async function saveWholePage(page?: object) {
+ const payload = page ?? await requestFromPage({name: 'trilium-save-page'});
const failedImages = await postProcessImages(payload);
@@ -458,7 +459,7 @@ export default defineBackground(() => {
return await saveWholeScreenshot(activeTab.url);
}
else if (request.name === 'save-whole-page') {
- return await saveWholePage();
+ return await saveWholePage(request.page);
}
else if (request.name === 'save-link-with-note') {
return await saveLinkWithNote(request.title, request.content);
diff --git a/apps/web-clipper/entrypoints/popup/main.tsx b/apps/web-clipper/entrypoints/popup/main.tsx
index 24e46ed625..3f853895d0 100644
--- a/apps/web-clipper/entrypoints/popup/main.tsx
+++ b/apps/web-clipper/entrypoints/popup/main.tsx
@@ -30,6 +30,25 @@ type PopupMessage = {
/** The keyboard shortcut of each command, by command name; unbound commands are absent. */
type Shortcuts = Record<string, string>;
+/** A page as the content script extracts it, its images referenced in `content` by `imageId`. */
+interface ExtractedPage {
+ title: string;
+ content: string;
+ images: { imageId: string, src: string }[];
+ pageUrl: string;
+ clipType: "page";
+ labels: Record<string, string>;
+}
+
+const PREVIEW_STYLE = `
+ :root { color-scheme: light dark; }
+ body { margin: 8px; font: 12px/1.5 system-ui, sans-serif; overflow-wrap: anywhere; }
+ h1 { font-size: 1.3em; } h2 { font-size: 1.15em; } h3, h4, h5, h6 { font-size: 1em; }
+ img, video, svg, iframe { max-width: 100%; height: auto; }
+ pre { white-space: pre-wrap; }
+ a { pointer-events: none; }
+`;
+
const root = document.getElementById("root");
if (root) {
render(<Popup />, root);
@@ -152,11 +171,7 @@ function CaptureActions({ disabled, shortcuts, onWriteNote }: {
return (
<div className="capture-actions">
- <button className="btn btn-primary primary-action" {...actionProps} onClick={() => sendMessage({ name: "save-whole-page" })}>
- <Icon icon={Article} />
- <span className="action-label">Save whole page</span>
- <Shortcut keys={shortcuts.saveWholePage} />
- </button>
+ <PagePreview disabled={disabled} shortcut={shortcuts.saveWholePage} />
<div className="action-tiles">
<button className="btn btn-secondary action-tile" {...actionProps} onClick={() => sendAndClose("save-cropped-screenshot")}>
@@ -182,6 +197,69 @@ function CaptureActions({ disabled, shortcuts, onWriteNote }: {
);
}
+/**
+ * The readable version of the current page, with its title editable, and the button that saves it.
+ * The page's HTML comes from an arbitrary website, so it is shown only in a sandboxed frame.
+ */
+function PagePreview({ disabled, shortcut }: { disabled: boolean, shortcut: string | undefined }) {
+ /** `undefined` while the page is read, `null` when it cannot be. */
+ const [ page, setPage ] = useState<ExtractedPage | null>();
+ const [ title, setTitle ] = useState("");
+
+ useEffect(() => {
+ void extractPage().then((extracted) => {
+ setPage(extracted);
+ setTitle(extracted?.title ?? "");
+ });
+ }, []);
+
+ function save(extracted: ExtractedPage) {
+ void sendMessage({ name: "save-whole-page", page: { ...extracted, title: title.trim() || extracted.title } });
+ window.close();
+ }
+
+ const published = page?.labels.publishedDate;
+
+ return (
+ <div className="page-preview">
+ {page === undefined && <div className="page-preview-placeholder">Reading the page…</div>}
+ {page === null && <div className="page-preview-placeholder">This page cannot be saved as an article.</div>}
+ {page && (
+ <>
+ <input
+ type="text"
+ className="page-title"
+ aria-label="Note title"
+ placeholder="Note title"
+ value={title}
+ onInput={(e) => setTitle(e.currentTarget.value)}
+ />
+ <div className="page-meta">
+ {new URL(page.pageUrl).hostname}{published && ` · Published ${published}`}
+ </div>
+ <iframe
+ className="page-content"
+ title="Preview of the page"
+ sandbox=""
+ srcDoc={previewDocument(page)}
+ />
+ </>
+ )}
+
+ <button
+ className="btn btn-primary primary-action"
+ disabled={disabled || !page}
+ title={disabled ? "This action can't be performed without active connection to Trilium." : undefined}
+ onClick={page ? () => save(page) : undefined}
+ >
+ <Icon icon={Article} />
+ <span className="action-label">Save page to Trilium</span>
+ <Shortcut keys={shortcut} />
+ </button>
+ </div>
+ );
+}
+
function Shortcut({ keys }: { keys: string | undefined }) {
return keys ? <kbd>{keys}</kbd> : null;
}
@@ -276,6 +354,35 @@ function describeStatus(status: TriliumSearchStatus | undefined) {
}
}
+/**
+ * Asks the content script of the active tab for its readable page, as it extracts it for saving.
+ * Returns `null` on pages where no content script runs (browser pages, extension stores) and when
+ * the page cannot be extracted.
+ */
+async function extractPage(): Promise<ExtractedPage | null> {
+ try {
+ const [ tab ] = await browser.tabs.query({ active: true, currentWindow: true });
+ if (tab?.id === undefined) return null;
+ return await browser.tabs.sendMessage(tab.id, { name: "trilium-save-page" }) ?? null;
+ } catch {
+ return null;
+ }
+}
+
+/** A standalone document showing the page's content, its images loaded from the website. */
+export function previewDocument({ content, images }: Pick<ExtractedPage, "content" | "images">) {
+ const doc = new DOMParser().parseFromString(content, "text/html");
+ for (const img of doc.querySelectorAll("img")) {
+ const image = images.find(({ imageId }) => imageId === img.getAttribute("src"));
+ if (image) {
+ img.setAttribute("src", image.src);
+ }
+ }
+
+ return `<!DOCTYPE html><html><head><meta charset="utf-8"><style>${PREVIEW_STYLE}</style></head>`
+ + `<body>${doc.body.innerHTML}</body></html>`;
+}
+
/** Maps each bound command to its shortcut, as the browser shows it. */
export function shortcutsByCommand(commands: { name?: string, shortcut?: string }[]): Shortcuts {
const shortcuts: Shortcuts = {};
diff --git a/apps/web-clipper/entrypoints/popup/popup.css b/apps/web-clipper/entrypoints/popup/popup.css
index ec4afed125..ed0db1fcdb 100644
--- a/apps/web-clipper/entrypoints/popup/popup.css
+++ b/apps/web-clipper/entrypoints/popup/popup.css
@@ -74,7 +74,45 @@ body {
.capture-actions {
display: flex;
flex-direction: column;
- gap: 8px;
+ gap: 10px;
+ }
+
+ .page-preview {
+ display: flex;
+ flex-direction: column;
+ gap: 6px;
+
+ .page-title {
+ width: 100%;
+ font-weight: 500;
+ }
+
+ .page-meta {
+ overflow: hidden;
+ color: var(--muted-text-color);
+ font-size: 0.9em;
+ white-space: nowrap;
+ text-overflow: ellipsis;
+ }
+
+ .page-content {
+ width: 100%;
+ height: 200px;
+ border: 1px solid var(--main-border-color);
+ border-radius: 6px;
+ background: var(--main-background-color);
+ }
+
+ .page-preview-placeholder {
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ height: 120px;
+ border: 1px dashed var(--main-border-color);
+ border-radius: 6px;
+ color: var(--muted-text-color);
+ text-align: center;
+ }
}
.primary-action {
@@ -91,23 +129,21 @@ body {
.action-tiles {
display: grid;
grid-template-columns: 1fr 1fr;
- gap: 8px;
+ gap: 6px;
}
button.btn.action-tile {
- flex-direction: column;
- gap: 4px;
+ justify-content: flex-start;
min-width: 0;
- padding: 10px 8px;
-
- > svg.icon {
- width: 1.6em;
- height: 1.6em;
- margin: 0;
- }
+ padding: 4px 8px;
+ font-size: 0.95em;
- kbd {
- margin: 0;
+ .action-label {
+ overflow: hidden;
+ flex-grow: 1;
+ text-align: start;
+ white-space: nowrap;
+ text-overflow: ellipsis;
}
}
diff --git a/apps/web-clipper/entrypoints/popup/popup.spec.tsx b/apps/web-clipper/entrypoints/popup/popup.spec.tsx
index c25fbdeb5e..74f792c468 100644
--- a/apps/web-clipper/entrypoints/popup/popup.spec.tsx
+++ b/apps/web-clipper/entrypoints/popup/popup.spec.tsx
@@ -4,7 +4,7 @@ import { act } from "preact/test-utils";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { fakeBrowser } from "wxt/testing/fake-browser";
-import { basicIcon, parseLinkNote, Popup, shortcutsByCommand, textToHtml } from "./main";
+import { basicIcon, parseLinkNote, Popup, previewDocument, shortcutsByCommand, textToHtml } from "./main";
const DISCONNECTED = "This action can't be performed without active connection to Trilium.";
@@ -16,6 +16,16 @@ const getAllCommands = vi.fn(async () => [
{ name: "saveCroppedScreenshot", shortcut: "Ctrl+Shift+E" },
{ name: "saveTabs", shortcut: "" }
]);
+const PAGE = {
+ title: "An article",
+ content: `<p>Body</p><img src="i1"><img src="https://example.com/b.png">`,
+ images: [ { imageId: "i1", src: "https://example.com/a.png" } ],
+ pageUrl: "https://example.com/post?id=1",
+ clipType: "page",
+ labels: { publishedDate: "2024-05-01" }
+};
+const tabsQuery = vi.fn(async (): Promise<{ id?: number }[]> => [ { id: 7 } ]);
+const tabsSendMessage = vi.fn(async (_tabId: number, _message: object): Promise<unknown> => PAGE);
const closeWindow = vi.fn();
let container: HTMLElement;
@@ -24,6 +34,7 @@ describe("popup", () => {
fakeBrowser.reset();
Object.assign(fakeBrowser.runtime, { sendMessage, openOptionsPage });
Object.assign(fakeBrowser.commands, { getAll: getAllCommands });
+ Object.assign(fakeBrowser.tabs, { query: tabsQuery, sendMessage: tabsSendMessage });
vi.spyOn(window, "close").mockImplementation(closeWindow);
vi.spyOn(console, "log").mockImplementation(() => {});
@@ -120,16 +131,12 @@ describe("popup", () => {
});
it("sends the capture actions, closing the popup for screenshots", async () => {
- expect(container.querySelector(".primary-action .action-label")?.textContent).toBe("Save whole page");
-
await click("Crop screenshot");
expect(sendMessage).toHaveBeenCalledWith({ name: "save-cropped-screenshot" });
await click("Visible area screenshot");
expect(sendMessage).toHaveBeenCalledWith({ name: "save-whole-screenshot" });
expect(closeWindow).toHaveBeenCalledTimes(2);
- await click("Save whole page");
- expect(sendMessage).toHaveBeenCalledWith({ name: "save-whole-page" });
await click("All tabs in window");
expect(sendMessage).toHaveBeenCalledWith({ name: "save-tabs" });
await click("Check the connection again");
@@ -145,19 +152,73 @@ describe("popup", () => {
it("shows the keyboard shortcut of each action that has one", () => {
expect(getAllCommands).toHaveBeenCalledOnce();
- expect(shortcutOf("Save whole page")).toBe("Alt+Shift+S");
+ expect(shortcutOf("Save page to Trilium")).toBe("Alt+Shift+S");
expect(shortcutOf("Crop screenshot")).toBe("Ctrl+Shift+E");
expect(shortcutOf("All tabs in window")).toBeUndefined();
expect(shortcutOf("Visible area screenshot")).toBeUndefined();
expect(shortcutOf("Link with a note")).toBeUndefined();
});
+ it("previews the readable page with its title, source and date", () => {
+ expect(tabsQuery).toHaveBeenCalledWith({ active: true, currentWindow: true });
+ expect(tabsSendMessage).toHaveBeenCalledWith(7, { name: "trilium-save-page" });
+
+ expect(container.querySelector<HTMLInputElement>(".page-title")?.value).toBe("An article");
+ expect(container.querySelector(".page-meta")?.textContent).toBe("example.com · Published 2024-05-01");
+ const frame = container.querySelector<HTMLIFrameElement>("iframe.page-content");
+ expect(frame?.getAttribute("sandbox")).toBe("");
+ expect(frame?.getAttribute("srcdoc")).toBe(previewDocument(PAGE));
+ expect(button("Save page to Trilium")?.disabled).toBe(false);
+ });
+
+ it("saves the extracted page with the edited title, and closes", async () => {
+ await type(".page-title", " My title ");
+ await click("Save page to Trilium");
+ expect(sendMessage).toHaveBeenCalledWith({ name: "save-whole-page", page: { ...PAGE, title: "My title" } });
+ expect(closeWindow).toHaveBeenCalledOnce();
+
+ await type(".page-title", " ");
+ await click("Save page to Trilium");
+ expect(sendMessage).toHaveBeenLastCalledWith({ name: "save-whole-page", page: PAGE });
+ });
+
+ it("leaves out the date of a page that has none", async () => {
+ tabsSendMessage.mockResolvedValueOnce({ ...PAGE, labels: {} });
+ await rerender();
+ expect(container.querySelector(".page-meta")?.textContent).toBe("example.com");
+ });
+
+ it("says so while the page is read, and when it cannot be", async () => {
+ let resolvePage: (page: unknown) => void = () => {};
+ tabsSendMessage.mockReturnValueOnce(new Promise((resolve) => {
+ resolvePage = resolve;
+ }));
+ await rerender();
+ expect(placeholder()).toBe("Reading the page…");
+ expect(button("Save page to Trilium")?.disabled).toBe(true);
+
+ resolvePage(undefined);
+ await flush();
+ expect(placeholder()).toBe("This page cannot be saved as an article.");
+ expect(button("Save page to Trilium")?.disabled).toBe(true);
+ expect(container.querySelector("iframe")).toBeNull();
+
+ tabsSendMessage.mockRejectedValueOnce(new Error("Could not establish connection."));
+ await rerender();
+ expect(placeholder()).toBe("This page cannot be saved as an article.");
+
+ tabsQuery.mockResolvedValueOnce([ {} ]);
+ await rerender();
+ expect(placeholder()).toBe("This page cannot be saved as an article.");
+ expect(tabsSendMessage).toHaveBeenCalledTimes(3);
+ });
+
it("tells the user when the background script cannot be reached", async () => {
const alertMock = vi.fn();
vi.stubGlobal("alert", alertMock);
sendMessage.mockRejectedValueOnce(new Error("Receiving end does not exist."));
- await click("Save whole page");
+ await click("All tabs in window");
expect(alertMock).toHaveBeenCalledWith("Calling browser runtime failed. Refreshing page might help.");
});
@@ -245,6 +306,16 @@ describe("popup", () => {
});
});
+describe("previewDocument", () => {
+ it("loads the page's images from the website, and keeps the rest of its content", () => {
+ const doc = new DOMParser().parseFromString(previewDocument(PAGE), "text/html");
+ expect([ ...doc.querySelectorAll("img") ].map((img) => img.getAttribute("src")))
+ .toEqual([ "https://example.com/a.png", "https://example.com/b.png" ]);
+ expect(doc.querySelector("p")?.textContent).toBe("Body");
+ expect(doc.querySelector("style")?.textContent).toContain("max-width: 100%");
+ });
+});
+
describe("shortcutsByCommand", () => {
it("keeps only the commands that have a shortcut", () => {
expect(shortcutsByCommand([
@@ -260,6 +331,7 @@ describe("icons", () => {
it("draws each button's Boxicon inline, hidden from assistive technology", async () => {
vi.spyOn(console, "log").mockImplementation(() => {});
Object.assign(fakeBrowser.commands, { getAll: getAllCommands });
+ Object.assign(fakeBrowser.tabs, { query: tabsQuery, sendMessage: tabsSendMessage });
const container = document.createElement("div");
await act(() => render(<Popup />, container));
@@ -324,6 +396,27 @@ function button(text: string) {
return found;
}
+/** Renders the popup again, so that it extracts the page anew. */
+async function rerender() {
+ await act(() => render(null, container));
+ await act(() => render(<Popup />, container));
+ await flush();
+}
+
+async function type(selector: string, value: string) {
+ const input = container.querySelector<HTMLInputElement>(selector);
+ expect(input, selector).not.toBeNull();
+ await act(() => {
+ if (!input) return;
+ input.value = value;
+ input.dispatchEvent(new Event("input", { bubbles: true }));
+ });
+}
+
+function placeholder() {
+ return container.querySelector(".page-preview-placeholder")?.textContent;
+}
+
async function click(text: string) {
const target = button(text);
await act(() => target?.click());
diff --git a/docs/User Guide/User Guide/Installation & Setup/Web Clipper.md b/docs/User Guide/User Guide/Installation & Setup/Web Clipper.md
index c3988bbabc..e820d5d7aa 100644
--- a/docs/User Guide/User Guide/Installation & Setup/Web Clipper.md
+++ b/docs/User Guide/User Guide/Installation & Setup/Web Clipper.md
@@ -30,7 +30,8 @@ The extension is available from the official browser web stores:
Clicking the extension's button in the browser toolbar opens its popup:
* The header shows whether the extension is connected to Trilium, as a colored dot (green when connected, amber when the versions are not compatible, red when Trilium was not found), next to the buttons for the extension's options and for this help page.
-* _Save whole page_ is the main action. Below it are _Crop screenshot_, _Visible area screenshot_, _Link with a note_ and _All tabs in window_ (which saves the links of every tab in the current window as a list). An action that has a keyboard shortcut shows it.
+* The popup reads the current page as an article and shows a preview of what will be saved: the note's title, which can be edited before saving, the website and the publication date (when the page states one), and the article's text and images. _Save page to Trilium_ saves it. Pages the extension cannot read, such as the browser's own pages, say so instead. The keyboard shortcut and the context menu still save the page right away, without a preview.
+* Below the preview are _Crop screenshot_, _Visible area screenshot_, _Link with a note_ and _All tabs in window_ (which saves the links of every tab in the current window as a list). An action that has a keyboard shortcut shows it.
* _Link with a note_ opens a small editor in place of the actions. The first sentence or line of the text becomes the note's title, unless _Keep page title as note title_ is checked. Press _Save_ or <kbd>Ctrl</kbd>+<kbd>Enter</kbd> to save it, or the back arrow to return to the actions.
* If the current page was already clipped, a notice at the top offers to open the note in Trilium.
* If Trilium cannot be found, the popup explains why instead of showing the actions, with buttons to look for Trilium again and to open the options.