feat(api): container bookmark() — sections and containers as PDF outline targets#242
Merged
Conversation
…ine targets A PDF bookmark (outline entry) could be set only on the seven leaf builders; a structural unit — a Section, a Container, a page flow — could not be a navigable outline target, so a multi-chapter document had no bookmark panel unless every chapter pinned a leaf bookmark by hand. bookmark(DocumentBookmarkOptions) on AbstractFlowBuilder makes any container flow an outline entry pointing at its start page. It is emitted as a new non-visual BookmarkMarkerPayload fragment — gated to the container's start page, like the existing anchor marker — that rides the backend's generic bookmark-registration branch (a no-op render handler covers fragment dispatch). Because the bookmark has its own marker fragment rather than riding the background decoration, it works on an unstyled container too. A container without a bookmark emits the same fragments as before, so existing documents are byte-for-byte unchanged. Tests: ContainerBookmarkTest asserts two bookmarked sections become outline entries at their pages, an unstyled section still emits its bookmark, a multi-page page flow emits its entry exactly once at the start page, a section without a bookmark adds no entry, and the back-compat SectionNode constructor defaults to no bookmark. Example: ContainerBookmarkExample (a report whose sections are each an outline entry). Full suite green, no visual baselines changed.
Threading the container bookmark through ModuleBuilder switched its buildNode to the full SectionNode constructor, which also started honouring bleed() — a module previously ignored bleed. Pass DocumentBleed.none() explicitly so a module's bleed behaviour stays as it was; only the bookmark is threaded through.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
A PDF bookmark (outline entry) could be set only on the seven leaf builders. A structural unit — a
Section, aContainer, a page flow — could not be a navigable outline target, so a multi-chapter document had no bookmark panel unless every chapter pinned a leaf bookmark by hand.viewerPreferences()(page mode / layout / window flags, whereUSE_OUTLINESauto-opens this panel) follows as a separate PR.What changed
bookmark(DocumentBookmarkOptions)onAbstractFlowBuilder— makes any container flow (Section/Container/ page flow) a PDF outline entry pointing at its start page.BookmarkMarkerPayloadfragment, gated to the container's start page (mirroring the existingwithAnchorMarker), that rides the backend's generic bookmark-registration branch — a no-opPdfBookmarkMarkerRenderHandlercovers fragment dispatch, and registration reuses the existingregisterBookmark→PdfBookmarkOutlineWriterpath (no deferred resolution, unlike an anchor).Lane: canonical DSL (
AbstractFlowBuilder,SectionNode,ContainerNode) + a shared-engine marker emission. Purely additive → japicmp-safe (the newSectionNode13th /ContainerNode11th components ship behind re-declared back-compat constructors).Verification
./mvnw test -pl .— green, 0 changed visual baselines → a container without a bookmark emits the same fragments as before../mvnw -P japicmp verify— binary-compatible.ContainerBookmarkTest(5): two bookmarked sections become outline entries at their pages; an unstyled section still emits its bookmark; a multi-page page flow (aContainerNode) emits its entry exactly once at the start page (the split-gating edge); a section without a bookmark adds no entry; the back-compatSectionNodeconstructor defaults to no bookmark.ContainerBookmarkExample+ committed preview: a report whose four sections are each an outline entry (verified via the PDF's outline).