Comment actions

Turn on the optionsCopy Anchor Link

Add visibility, reports and update to the comment type in src/content/comment.ts. This is an excerpt; keep the rest of the file:

  publication: true,
  visibility: true, 
  reports: { titleField: "body", snapshotFields: ["body"] }, 

  publicWrite: {
    ownership: { field: "author" },
    create: { fields: ["body", "article", "parent"], status: "published" },
    update: { fields: ["body"] }, 
  },

• visibility adds POST /{id}/hide and /unhide, and the columns that remember who hid a comment and why.
• reports adds reporting. titleField: "body" gives moderators the first line of the comment as the report's title, so comments need no title field of their own. snapshotFields keeps a copy of the text as it was when reported.
• update adds GET /{id}/edit and PATCH /{id}. Only body is editable; a comment never moves to another article or parent.
• GET /permissions, which the menu asks, already exists, because publicWrite mounts it.

Add the moderation labels next to the other newsroom:comment labels in src/locales/en.json:

{
  "newsroom:comment:can_view_reports": "View comment reports",
  "newsroom:comment:can_manage_reports": "Claim, assign and resolve comment reports",
  "newsroom:comment:can_view_hidden": "Open hidden comments"
}

Then build and migrate from the workspace root:

bun run build:plugins
bun run db:migrate

Ask who may do whatCopy Anchor Link

Add permissions to the useContentComments call in src/pages/article-comments.tsx. This is an excerpt; the following steps add to the same call:

  const comments = useContentComments({
    ...articleCommentsThread(articleId),
    create: async ({ body, parentId }) => /* unchanged */,
    permissions: async ids =>
      await fetcher({
        plugin: manifest.id,
        method: "get",
        module: "content/article-comments",
        path: "/permissions",
        args: { query: { ids: ids.join(",") } },
      }),
  });

The section asks once for every comment on screen, in batches of 50, and again for the comments Load more comments adds. A comment whose answer has not arrived, or whose batch failed, shows no actions. The answers belong to the signed-in visitor, so signing in or out asks again.

The server answers from settings, not from your code:

• Authors edit their own comments while their role's Time to edit runs, if Allow editing own content is on (it is, by default). Allow deleting own content and Allow hiding own content are off by default. Turning on visibility does not turn them on. Roles explains all three.
• Moderators act on anyone's comments, at any age, with the comment type's permissions in AdminCP → Staff → Moderators: Edit comments, Delete comments and Hide and unhide comments.
• Reporting is open to every signed-in visitor on other people's comments. Add selfReport: true to reports to let authors report their own.

Connect editCopy Anchor Link

    edit: {
      load: async id =>
        await fetcher({
          plugin: manifest.id,
          method: "get",
          module: "content/article-comments",
          path: "/{id}/edit",
          args: { params: { id } },
        }),
      // Comments have no editorial revisions, so the last save wins.
      save: async (id, { body }) =>
        await fetcher({
          plugin: manifest.id,
          method: "patch",
          module: "content/article-comments",
          path: "/{id}",
          args: { params: { id }, body: { values: { body } } },
        }),
    },

Edit loads the editable text first and opens the editor in place of the comment. After Save, the thread and the form's defaults refresh. If the author's edit waits for a moderator, the editor opens on that proposed text, and saving says it is waiting rather than live.

Newsroom comments have no editorial, so two saves of the same comment both succeed and the last one wins. To refuse a stale save instead, add editorial: true to the comment type, migrate, and send the version:

save: async (id, { body, expectedVersion }) =>
  await fetcher({
    plugin: manifest.id,
    method: "patch",
    module: "content/article-comments",
    path: "/{id}",
    args: { params: { id }, body: { values: { body }, expectedVersion } },
  }),

A stale save then answers 409, and the editor shows Someone else saved in the meantime with Keep my version and Load latest version. The Blog plugin's comments work this way.

Connect deleteCopy Anchor Link

    delete: async id =>
      await fetcher({
        plugin: manifest.id,
        method: "post",
        module: "content/article-comments",
        path: "/{id}/delete",
        args: { params: { id } },
      }),

Delete asks for confirmation first. A comment nobody answered is removed. A comment with replies stays in the thread as an anonymous [deleted] placeholder with no text and no author, so its replies keep their place. The placeholder reads "Comment deleted by user" or "Comment removed by a moderator". Deleting the last reply under a placeholder removes the placeholder too. A deleted comment cannot be restored.

Connect hide and restoreCopy Anchor Link

    visibility: {
      hide: async (id, { reason }) =>
        await fetcher({
          plugin: manifest.id,
          method: "post",
          module: "content/article-comments",
          path: "/{id}/hide",
          args: { params: { id }, body: reason ? { reason } : {} },
        }),
      unhide: async id =>
        await fetcher({
          plugin: manifest.id,
          method: "post",
          module: "content/article-comments",
          path: "/{id}/unhide",
          args: { params: { id } },
        }),
    },

Hide asks for an optional reason of up to 500 characters. A hidden comment disappears for everyone else, but stays visible, marked Hidden with its reason, to its author and to moderators, who get Unhide. Readers who can't see it get the same placeholder as a deleted comment when it has replies, and nothing when it has none. Hiding is not deleting. Unhide brings the comment back unchanged. It is also not unpublishing, which is a staff action in the AdminCP.

Connect reportingCopy Anchor Link

import { contentTarget } from "@vitnode/core/content"; 

import { commentContentType } from "@/content/comment"; 

    report: id => contentTarget(manifest.id, commentContentType, id), 

Report opens the core report dialog, where the visitor picks a reason. A guest who reaches it is asked to sign in first and comes back to the article. Reports land in ModCP with the comment's first line as their title.

Link reports to the commentCopy Anchor Link

ModCP links each report to its content's public URL, and a comment has none yet. Give it a permalink that redirects to the comment under its article.

Add delivery to the comment type. This is an excerpt:

  delivery: { path: "/news/comments/:slug" }, 

  thread: { parent: "parent", root: "article", maxDepth: 1 },

Delivery claims the type's publicApi.path across the whole site. That's why this guide picked article-comments. The Blog plugin already delivers comments, and two plugins can't share a path.

The redirect needs the article's slug, and a comment only knows its article's id. Add a small public route that answers it. Create src/api/modules/articles/articles.module.ts:

import { z } from "@hono/zod-openapi";
import { setPageCacheTags } from "@vitnode/core/api/lib/page-cache";
import { contentPublicListTag } from "@vitnode/core/content";
import { HTTPException } from "hono/http-exception";

import { buildModule, buildRoute } from "@/api/builders";
import { articleContent } from "@/database/articles";

const articleSlugRoute = buildRoute({
  route: {
    method: "get",
    path: "/{id}/slug",
    description:
      "The slug of one public article, for turning a comment permalink into the comment under its article",
    request: {
      params: z.object({
        id: z.coerce.number().int().positive().openapi({ example: 1 }),
      }),
    },
    responses: {
      200: {
        content: {
          "application/json": {
            schema: z.object({ id: z.number(), slug: z.string() }),
          },
        },
        description: "The article's slug",
      },
      404: { description: "No public article with this id" },
    },
  },
  handler: async c => {
    const { id } = c.req.valid("param");
    const service = articleContent.publicService?.(c);
    if (!service) {
      throw new HTTPException(500, { message: "Articles have no public API." });
    }

    const article = await service.findById(id);
    if (!article) throw new HTTPException(404, { message: "Article not found." });

    setPageCacheTags(c, [contentPublicListTag(articleContent.definition.id)]);

    return c.json({ id: article.id, slug: article.slug }, 200);
  },
});

export const articlesModule = buildModule({
  name: "articles",
  routes: [articleSlugRoute],
});

Register it in src/config.api.ts. This is an excerpt:

import { articlesModule } from "./api/modules/articles/articles.module"; 

    modules: [
      helloModule,
      adminModule,
      articlesModule, 

The redirect page uses TanStack Query and TanStack Router. Skip this if the plugin already has both; otherwise run this from the workspace root:

bun add @tanstack/react-query @tanstack/react-router --cwd plugins/newsroom

Create src/pages/comment-redirect-page.tsx:

import { queryOptions } from "@tanstack/react-query";
import { redirect } from "@tanstack/react-router";
import { LOADER_DATA_QUERY_META } from "@vitnode/core/lib/query-client";
import { CONTENT_COMMENT_ANCHOR_PREFIX } from "@vitnode/core/tanstack/comments";
import { contentPageItem } from "@vitnode/core/tanstack/content";
import { fetcher } from "@vitnode/core/tanstack/fetcher";
import { localizeHref } from "@vitnode/core/tanstack/i18n";
import { defineRoute } from "@vitnode/core/tanstack/plugin-routes";
import { z } from "zod";

import { manifest } from "@/manifest.gen";

const zodCommentLink = z.object({
  article: z.object({ id: z.number() }),
  id: z.number(),
});

/** Where a comment's permalink leads: its article's slug and the comment's id. */
const commentLinkQueryOptions = (slug: string) =>
  queryOptions({
    meta: LOADER_DATA_QUERY_META,
    queryFn: async () => {
      const comment = await fetcher({
        plugin: manifest.id,
        method: "get",
        module: "content/article-comments",
        path: "/{slug}",
        args: { params: { slug: encodeURIComponent(slug) } },
      });
      if (comment.status === 404) return null;
      if (comment.status !== 200) {
        throw new Error(`Resolving the comment "${slug}" failed.`);
      }

      const record = zodCommentLink.parse(await comment.json());
      const article = await fetcher({
        plugin: manifest.id,
        method: "get",
        module: "articles",
        path: "/{id}/slug",
        args: { params: { id: record.article.id } },
      });
      if (article.status === 404) return null;
      if (article.status !== 200) {
        throw new Error(`Resolving the article of the comment "${slug}" failed.`);
      }

      return { article: (await article.json()).slug, comment: record.id };
    },
    queryKey: [manifest.id, "comment-link", slug],
  });

export const route = defineRoute({
  load: async ({ context, params }) => {
    const { article, comment } = contentPageItem(
      await context.queryClient.query(commentLinkQueryOptions(params.slug)),
    );

    // oxlint-disable-next-line typescript/only-throw-error
    throw redirect({
      href: `${localizeHref(`/news/${article}`, context.locale)}#${CONTENT_COMMENT_ANCHOR_PREFIX}${comment}`,
      statusCode: 302,
    });
  },

  head: () => ({ robots: "noindex, nofollow" }),
});

const CommentRedirectPage = () => null;

export default CommentRedirectPage;

• contentPageItem turns a null into the not-found page, for a comment or article that is gone or not public.
• #comment-{id} is the element id the section gives every comment. The section scrolls to it, loading more pages until it appears, focuses it and rings it.

Declare the page in src/routes.ts:

  page("/news/comments/:slug", {
    component: lazy(() => import("./pages/comment-redirect-page")),
  }),

Build again, so the new route's types and the delivery URL exist:

bun run build:plugins