Problem/Motivation

When an editor uploads an inaccessible PDF through CKEditor's "Add or select media" modal, PDFa11y surfaces a warning that contains the "PDF Accessibility Help" link from pdfa11y.settings:editor_instructions. Clicking that link navigates the current tab away from the upload modal. Pressing the browser's Back button returns to the parent page but does not reopen the upload modal — the editor loses the warning message and, depending on form state, may end up with an orphaned File entity attached to a media item that was never saved.

The link is doing exactly what an in-tab anchor does. The problem is that this particular link sits inside a modal flow where the editor's full context (their just-uploaded file, the list of issues, any partially filled metadata) is non-persistent. Losing it is frustrating and is a small upload-orphan risk.

Repro steps

  1. In CKEditor, open "Add or select media" and upload a PDF that fails one or more accessibility checks.
  2. In the PDFa11y warning, click "PDF Accessibility Help".
  3. Click the browser's Back button.
  4. Observed: the modal is closed, the warning is gone, and the just-uploaded File entity may be orphaned.
  5. Expected: the modal stays in place; the help link opens in a new tab.

Proposed resolution

The default editor_instructions string contains a link to the PDF Accessibility Help page. The minimal, lowest-risk fix is to add target="_blank" to that anchor in the default config so fresh installs get the correct behavior:

editor_instructions: 'For guidance on creating accessible PDF documents, see the <a href="/admin/config/media/pdf-accessibility/help" target="_blank">PDF Accessibility Help</a> page.'

Remaining tasks

  • Apply the two-file change.
  • Release note entry telling existing sites how to update their configured editor_instructions if they want the new-tab behavior.
  • Review.
  • Merge.

User interface changes

On fresh installs, the default "PDF Accessibility Help" link in editor warnings and on the media report opens in a new browser tab. Existing sites with a configured editor_instructions value see no change until they update their config per the release notes.

API changes

None.

Data model changes

None — the schema for editor_instructions is unchanged (still a free-form HTML string).

Environment observed

  • pdfa11y current 1.0.x on Drupal 10
  • Chrome on macOS (per QA report)

Issue fork pdfa11y-3590981

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

Comments

joshuami created an issue. See original summary.

  • joshuami committed 5a57f7a2 on 1.0.x
    Issue #3590981 by joshuami: Default editor_instructions help link should...
joshuami’s picture

Status: Active » Fixed

Now that this issue is closed, review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, credit people who helped resolve this issue.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.