Collect feedback with Was This Helpful

The DocsPress: Was This Helpful? block gives every documentation Page a small Helpful or Not helpful prompt. WordPress stores aggregate totals with the Page, while editors can review the score and hide the prompt without deleting earlier responses.

Understand the response flow

1. 1

   A reader chooses a response

   The published block sends Helpful or Not helpful to the Page-specific DocsPress REST endpoint.

2. 2

   WordPress validates the Page

   The endpoint accepts responses only for a published, public Page. Password-protected and unavailable Pages reject the request.

3. 3

   The Page totals are updated

   WordPress increments the aggregate Helpful or Not helpful metadata and returns the new counts without caching the response.

4. 4

   The browser remembers its choice

   The selected response is saved in local storage. The buttons remain selected and disabled when that browser returns to the same Page.

5. 5

   An editor reviews the signal

   The Page editor shows the helpful rate, both counts, and the total in its Page feedback panel.

Add or move the block

The bundled Page template includes the block by default, immediately before DocsPress: Adjacent Navigation.

To change its placement for every Page:

1. Open Appearance → Editor.
2. Choose Design → Templates → Page.
3. Open List View and select DocsPress: Was This Helpful?.
4. Move the block, or insert another instance from the block inserter.
5. Select Save and confirm the Page template change.

Removing the block or turning off Enabled hides the prompt everywhere that template is used. Existing Page totals are preserved.

Customize the prompt

Select the block in the Site Editor and open Settings → Page feedback. The text controls change the published prompt and its completed state.

Use the block’s Styles panel for native text, background, link, and gradient colors; typography; padding and margin; block spacing; borders and radius; minimum height; positioning; shadow; anchor; and custom CSS classes. Global Styles can set the default for every instance, while block-level changes affect only the selected template instance.

Review feedback for one Page

Open Pages, edit the documentation Page, show the editor’s Settings sidebar, and expand Page feedback. The panel displays the Helpful rate, Helpful and Not helpful counts, and total responses. Totals are read-only in the editor.

Turn off Show feedback on this Page when a particular Page should not ask for feedback. Save the Page to apply the change. Turning the setting back on restores the prompt with its earlier totals intact.

The per-Page control takes precedence over the template block: a Page with feedback disabled remains hidden even when the block itself is enabled.

Know what WordPress stores

The feature stores aggregate counts, not a visitor identity or comment. The browser separately stores docspress-feedback:<page-id> with the selected vote so it can restore the completed state.

Inspect the REST exchange

The block sends a public POST request to the Page-specific endpoint. This example remains intentionally non-runnable because it modifies Page metadata.

Accept: application/jsonContent-Type: application/json

{
  "vote": "helpful"
}

{
  "saved": true,
  "vote": "helpful",
  "counts": {
    "helpful": 8,
    "unhelpful": 2,
    "total": 10
  }
}

The request accepts only helpful or unhelpful. It returns 404 for a Page that is missing, unpublished, or not a Page; 403 for a password-protected Page; 400 for an invalid vote; and 500 when WordPress cannot update the counter. Successful responses include Cache-Control: no-store.

Extend recorded responses

DocsPress fires docspress_page_feedback_recorded after a response is saved. Use it to forward the aggregate event to an analytics or reporting integration without changing the block.

add_action(    'docspress_page_feedback_recorded',    function ( $page_id, $vote, $counts ) {        // Forward the aggregate event to your reporting system.    },    10,    3);

If the public endpoint needs stricter abuse controls, add them at the WordPress or hosting layer and test that normal anonymous readers can still submit a response.

Accessibility behavior

The response buttons form a labelled group tied to the visible question. The selected button uses aria-pressed, saving and error states are announced through a live status region, and keyboard focus remains visible. On narrow screens the prompt and actions stack vertically, and reduced-motion preferences remove nonessential transitions.