Showcase (Public Sharing)

Relevant source files

The following files were used as context for generating this wiki page:

• packages/server/src/api/showcase.ts
• packages/web/src/pages/showcase/page.[slug].tsx
• packages/web/src/pages/showcase/folder.tsx
• packages/server/src/model/showcase.ts
• packages/web/src/components/page-card.tsx
• packages/server/src/api/pages.ts
• packages/web/src/data/page.ts
• packages/web/src/assets/locales/en/translation.json

The Showcase feature allows users to publicly share their archived web pages. Authenticated users can mark any of their saved pages to be "showcased," making them accessible via a public-facing gallery without requiring authentication. This system consists of backend APIs to manage and serve showcased content, and frontend components to display the public gallery and individual pages.

The core mechanism relies on an isShowcased flag in the pages database table. When a page is showcased, it appears in the public showcase folder and can be viewed by anyone with the link.

Database Schema

The showcase functionality is primarily controlled by a column in the pages table.

This diagram illustrates the structure of the pages table, highlighting the isShowcased column.
Sources: packages/server/src/model/showcase.ts:5-8, packages/server/src/api/pages.ts:25-39

Column	Type	Description
isShowcased	INTEGER	A boolean flag (0 or 1) indicating if the page is publicly visible.
Sources: packages/server/src/model/showcase.ts:5, packages/server/src/api/pages.ts:388

Backend API

The backend exposes a set of endpoints under /api/showcase for public access and uses an endpoint under /api/pages for managing the showcase status.

Toggling Showcase Status

This endpoint is used by authenticated users to add or remove a page from the public showcase.

PUT /api/pages/update_showcase

Updates the isShowcased status of a page.

Request Body:

Parameter	Type	Description
id	number	The ID of the page to update.
isShowcased	number	The new status (1 for showcased, 0 for not).
Sources: packages/server/src/api/pages.ts:381-393

Flow Diagram:

This diagram shows the sequence for updating a page's showcase status.
Sources: packages/server/src/api/pages.ts:394-397, packages/server/src/model/showcase.ts:31-35

Public Showcase Endpoints

Sources: packages/server/src/api/showcase.ts

These endpoints do not require authentication and serve the publicly showcased pages.

POST /api/showcase/query

Fetches a paginated list of all showcased pages.

Request Body:

Parameter	Type	Description
pageNumber	number	The page number to retrieve.
pageSize	number	The number of items per page.
Sources: packages/server/src/api/showcase.ts:11-23

Response:
Returns a JSON object with a list of page objects and the total count. Screenshots are included as base64 strings.
Sources: packages/server/src/api/showcase.ts:25-34

GET /api/showcase/content

Retrieves the raw HTML content of a single showcased page.

Query Parameters:

Parameter	Type	Description
pageId	string	The ID of the page to fetch.
Sources: packages/server/src/api/showcase.ts:41-45

Flow Diagram:

This diagram shows how the content for a single showcase page is fetched and returned.
Sources: packages/server/src/api/showcase.ts:41-61

GET /api/showcase/detail

Fetches the metadata for a single showcased page.

Query Parameters:

Parameter	Type	Description
id	number	The ID of the page to fetch.
Sources: packages/server/src/api/showcase.ts:64-70

GET /api/showcase/next_id

Gets the ID of the next showcased page in ascending order, used for navigation. If it's the last page, it loops back to the first.

Query Parameters:

Parameter	Type	Description
id	number	The ID of the current showcased page.
Sources: packages/server/src/api/showcase.ts:86-92

Server-side Data Logic

Sources: packages/server/src/model/showcase.ts

The data access logic for the showcase feature is encapsulated in the showcase.ts model file.

• queryShowcase(DB, options): Retrieves a paginated list of showcased pages.

  SELECT * FROM pages WHERE isShowcased = 1 AND isDeleted = 0 ORDER BY createdAt DESC LIMIT ? OFFSET ?
  

  Sources: packages/server/src/model/showcase.ts:6-8

• updateShowcase(DB, options): Updates the isShowcased flag for a given page ID.

  UPDATE pages SET isShowcased = ? WHERE id = ?
  

  Sources: packages/server/src/model/showcase.ts:32-34

• getShowcaseDetailById(DB, options): Fetches a single page by ID if it is showcased.

  SELECT * FROM pages WHERE isShowcased = 1 AND isDeleted = 0 AND id = ?
  

  Sources: packages/server/src/model/showcase.ts:41-45

• getNextShowcasePageId(DB, lastId): Finds the next page ID for navigation. It first tries to find the next ID greater than the current one, and if none is found, it fetches the very first showcased page ID.
  Sources: packages/server/src/model/showcase.ts:50-73

Frontend Implementation

Toggling Showcase Status

The ability to add or remove a page from the showcase is available on the page cards in the user's private folders.

Component: PageCard (packages/web/src/components/page-card.tsx)

A button with an Eye or EyeOff icon is rendered on the page card. Clicking this button triggers the updateShowcase function.

Data Flow:

This diagram outlines the flow from user interaction to state update when toggling a page's showcase status.
Sources: packages/web/src/components/page-card.tsx:135-144, packages/web/src/data/page.ts:60-66

Showcase Folder View

Component: ShowcaseFolderPage (packages/web/src/pages/showcase/folder.tsx)

This page serves as the main entry point for the public showcase. It displays a grid of all showcased pages.

• It uses the useInfiniteScroll hook from ahooks to fetch and display pages as the user scrolls.
• The queryShowcase data function is called to fetch paginated data from the /api/showcase/query endpoint.
• The CardView component renders the list of pages.

Sources: packages/web/src/pages/showcase/folder.tsx:11-28

Showcase Page View

Component: ShowcasePage (packages/web/src/pages/showcase/page.[slug].tsx)

This page displays the content of a single showcased page.

• It retrieves the page slug (ID) from the URL.
• It fetches the page's HTML content from /api/showcase/content?pageId={slug}.
• The fetched HTML is converted into a Blob and displayed in an <iframe> using an object URL. The sandbox attribute is used for security.
• Navigation controls (Home, Back, Next) are provided. The "Next" button and right arrow key press call getNextShowcasePageId to navigate to the next item.

Sources: packages/web/src/pages/showcase/page.[slug].tsx:10-21, 52-56, 81-85

Page Loading Flow:

This diagram shows the steps to load and display a single showcased page.
Sources: packages/web/src/pages/showcase/page.[slug].tsx:52-56

UI and Text

The user interface provides clear labels for showcase-related actions.

Key	English Text	Context
add-to-showcase	Add to Showcase	Tooltip for the showcase toggle button.
remove-from-showcase	Remove from Showcase	Tooltip for the showcase toggle button.
showcased	Showcased	Label for the showcase checkbox in forms.

Sources: packages/web/src/assets/locales/en/translation.json:44, 50, 60, packages/web/src/components/page-card.tsx:146-151

Conclusion

The Showcase feature is a well-integrated part of the Web Archive application, providing a simple yet powerful way to share archived content publicly. It leverages a dedicated set of APIs for serving public content, while the management of showcase status is handled through the standard page management interface. The separation of public and private APIs, combined with the use of an iframe sandbox for rendering content, provides a secure foundation for public sharing.