Skip to content

Commit dfbb75d

Browse files
vursenclaude
andauthored
feat: add read-only page and page count API to PDF Viewer (#10523)
## Description Exposes the current page and the page count of PDF Viewer to the server. Both values come from the client, so the Javadoc says not to trust them for security decisions. The API is read-only for now. A `scrollToPage` method will be added later to scroll to a page, with options such as alignment (top, center, bottom). - Added `getPage()` and a read-only `pageSignal()` with the current page - Added `getPageCount()` and a read-only `pageCountSignal()` with the number of pages in the loaded document - Added `addPageChangeListener` and `PageChangeEvent`, fired when the current page changes - Added unit tests for the new API ## Type of change - Feature --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 94c170b commit dfbb75d

3 files changed

Lines changed: 383 additions & 23 deletions

File tree

‎vaadin-pdf-viewer-flow-parent/vaadin-pdf-viewer-flow/src/main/java/com/vaadin/flow/component/pdfviewer/PdfViewer.java‎

Lines changed: 127 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,12 +18,16 @@
1818
import com.vaadin.flow.component.DomEvent;
1919
import com.vaadin.flow.component.EventData;
2020
import com.vaadin.flow.component.HasSize;
21+
import com.vaadin.flow.component.Synchronize;
2122
import com.vaadin.flow.component.Tag;
2223
import com.vaadin.flow.component.UI;
2324
import com.vaadin.flow.component.dependency.JsModule;
2425
import com.vaadin.flow.component.dependency.NpmPackage;
26+
import com.vaadin.flow.dom.DisabledUpdateMode;
2527
import com.vaadin.flow.server.streams.DownloadHandler;
2628
import com.vaadin.flow.shared.Registration;
29+
import com.vaadin.flow.signals.Signal;
30+
import com.vaadin.flow.signals.local.ValueSignal;
2731

2832
/**
2933
* PDF Viewer is a component for showing PDF documents. Give the document as a
@@ -53,10 +57,21 @@
5357
@JsModule("@vaadin/pdf-viewer/src/vaadin-pdf-viewer.js")
5458
public class PdfViewer extends Component implements HasSize {
5559

60+
private final ValueSignal<Integer> pageSignal = new ValueSignal<>(1);
61+
private final ValueSignal<Integer> pageCountSignal = new ValueSignal<>(0);
62+
5663
/**
5764
* Creates a PDF viewer without a document.
5865
*/
5966
public PdfViewer() {
67+
getElement().addPropertyChangeListener("page", event -> {
68+
pageSignal.set(getPage());
69+
fireEvent(new PageChangeEvent(this, event.isUserOriginated(),
70+
getPage()));
71+
});
72+
addDocumentLoadListener(
73+
event -> pageCountSignal.set(event.getPageCount()));
74+
addDocumentErrorListener(event -> resetDocumentState());
6075
}
6176

6277
/**
@@ -67,6 +82,7 @@ public PdfViewer() {
6782
* @see #setSrc(String)
6883
*/
6984
public PdfViewer(String src) {
85+
this();
7086
setSrc(src);
7187
}
7288

@@ -80,6 +96,7 @@ public PdfViewer(String src) {
8096
* @see #setSrc(DownloadHandler)
8197
*/
8298
public PdfViewer(DownloadHandler downloadHandler) {
99+
this();
83100
setSrc(downloadHandler);
84101
}
85102

@@ -93,9 +110,10 @@ public String getSrc() {
93110
}
94111

95112
/**
96-
* Sets the URL of the document to show. The current document is replaced.
97-
* {@link DocumentLoadEvent} fires when the document has loaded,
98-
* {@link DocumentErrorEvent} if it could not be loaded.
113+
* Sets the URL of the document to show. The current document is replaced,
114+
* and the new one opens on the first page. {@link DocumentLoadEvent} fires
115+
* when the document has loaded, {@link DocumentErrorEvent} if it could not
116+
* be loaded.
99117
* <p>
100118
* The browser fetches the document, so the URL must be on the same origin
101119
* as the application, or the server must allow it with CORS headers. To
@@ -111,6 +129,7 @@ public void setSrc(String src) {
111129
} else {
112130
getElement().setAttribute("src", src);
113131
}
132+
resetDocumentState();
114133
}
115134

116135
/**
@@ -128,6 +147,78 @@ public void setSrc(DownloadHandler downloadHandler) {
128147
Objects.requireNonNull(downloadHandler,
129148
"The download handler should not be null");
130149
getElement().setAttribute("src", downloadHandler.allowDisabled());
150+
resetDocumentState();
151+
}
152+
153+
private void resetDocumentState() {
154+
if (getPage() != 1) {
155+
getElement().setProperty("page", 1);
156+
}
157+
pageCountSignal.set(0);
158+
}
159+
160+
/**
161+
* Gets the current page, which is the page that takes up most of the
162+
* visible area. The default value is {@code 1}.
163+
* <p>
164+
* The value comes from the browser and must not be trusted for security
165+
* decisions.
166+
*
167+
* @return the current page, starting from {@code 1}
168+
*/
169+
@Synchronize(property = "page", value = "page-changed", allowUpdates = DisabledUpdateMode.ALWAYS)
170+
public int getPage() {
171+
return getElement().getProperty("page", 1);
172+
}
173+
174+
/**
175+
* Gets a read-only signal with the current page, which is the page that
176+
* takes up most of the visible area.
177+
* <p>
178+
* The value comes from the browser and must not be trusted for security
179+
* decisions.
180+
*
181+
* @return a read-only signal with the current page, starting from {@code 1}
182+
*/
183+
public Signal<Integer> pageSignal() {
184+
return pageSignal.asReadonly();
185+
}
186+
187+
/**
188+
* Gets the number of pages in the document.
189+
* <p>
190+
* The value comes from the browser and must not be trusted for security
191+
* decisions.
192+
*
193+
* @return the number of pages, or {@code 0} if no document is loaded
194+
*/
195+
public int getPageCount() {
196+
return pageCountSignal.peek();
197+
}
198+
199+
/**
200+
* Gets a read-only signal with the number of pages in the document, or
201+
* {@code 0} if no document is loaded.
202+
* <p>
203+
* The value comes from the browser and must not be trusted for security
204+
* decisions.
205+
*
206+
* @return a read-only signal with the number of pages
207+
*/
208+
public Signal<Integer> pageCountSignal() {
209+
return pageCountSignal.asReadonly();
210+
}
211+
212+
/**
213+
* Adds a listener that is called when the current page changes.
214+
*
215+
* @param listener
216+
* the listener to add, not {@code null}
217+
* @return a registration for removing the listener
218+
*/
219+
public Registration addPageChangeListener(
220+
ComponentEventListener<PageChangeEvent> listener) {
221+
return addListener(PageChangeEvent.class, listener);
131222
}
132223

133224
/**
@@ -169,10 +260,41 @@ private void checkFeatureFlag(UI ui) {
169260
}
170261
}
171262

263+
/**
264+
* Event fired when the current page changes.
265+
*/
266+
public static class PageChangeEvent extends ComponentEvent<PdfViewer> {
267+
private final int page;
268+
269+
/**
270+
* Creates a new event.
271+
*
272+
* @param source
273+
* the source component
274+
* @param fromClient
275+
* {@code true} if the event originated from the client
276+
* @param page
277+
* the new current page, starting from {@code 1}
278+
*/
279+
public PageChangeEvent(PdfViewer source, boolean fromClient, int page) {
280+
super(source, fromClient);
281+
this.page = page;
282+
}
283+
284+
/**
285+
* Gets the new current page.
286+
*
287+
* @return the new current page, starting from {@code 1}
288+
*/
289+
public int getPage() {
290+
return page;
291+
}
292+
}
293+
172294
/**
173295
* Event fired when a document has been loaded, before its pages are shown.
174296
*/
175-
@DomEvent("document-load")
297+
@DomEvent(value = "document-load", allowUpdates = DisabledUpdateMode.ALWAYS)
176298
public static class DocumentLoadEvent extends ComponentEvent<PdfViewer> {
177299
private final int pageCount;
178300
private final String title;
@@ -220,7 +342,7 @@ public String getTitle() {
220342
/**
221343
* Event fired when a document could not be loaded.
222344
*/
223-
@DomEvent("document-error")
345+
@DomEvent(value = "document-error", allowUpdates = DisabledUpdateMode.ALWAYS)
224346
public static class DocumentErrorEvent extends ComponentEvent<PdfViewer> {
225347
private final DocumentErrorReason reason;
226348

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
/**
2+
* Copyright 2000-2026 Vaadin Ltd.
3+
*
4+
* This program is available under Vaadin Commercial License and Service Terms.
5+
*
6+
* See {@literal <https://vaadin.com/commercial-license-and-service-terms>} for the full
7+
* license.
8+
*/
9+
package com.vaadin.flow.component.pdfviewer.tests;
10+
11+
import java.io.Serializable;
12+
13+
import org.junit.jupiter.api.Assertions;
14+
import org.junit.jupiter.api.Test;
15+
import org.junit.jupiter.api.extension.RegisterExtension;
16+
17+
import com.vaadin.flow.component.ComponentUtil;
18+
import com.vaadin.flow.component.pdfviewer.PdfViewer;
19+
import com.vaadin.flow.component.pdfviewer.PdfViewer.DocumentLoadEvent;
20+
import com.vaadin.flow.component.pdfviewer.PdfViewerFeatureFlagProvider;
21+
import com.vaadin.flow.internal.nodefeature.ElementPropertyMap;
22+
import com.vaadin.flow.internal.nodefeature.PropertyChangeDeniedException;
23+
import com.vaadin.flow.signals.local.ValueSignal;
24+
import com.vaadin.tests.AbstractSignalsTest;
25+
import com.vaadin.tests.EnableFeatureFlagExtension;
26+
27+
class PdfViewerSignalTest extends AbstractSignalsTest {
28+
29+
@RegisterExtension
30+
EnableFeatureFlagExtension featureFlagExtension = new EnableFeatureFlagExtension(
31+
PdfViewerFeatureFlagProvider.PDF_VIEWER_COMPONENT);
32+
33+
private final PdfViewer viewer = new PdfViewer();
34+
35+
@Test
36+
void pageSignal_defaultValue() {
37+
Assertions.assertEquals(1, viewer.pageSignal().peek());
38+
}
39+
40+
@Test
41+
void pageSignal_pageChangedOnClient_signalUpdated() {
42+
fakeClientPropertyChange("page", 4.0);
43+
Assertions.assertEquals(4, viewer.pageSignal().peek());
44+
}
45+
46+
@Test
47+
void pageSignal_isReadOnly() {
48+
Assertions.assertFalse(viewer.pageSignal() instanceof ValueSignal<?>);
49+
}
50+
51+
@Test
52+
void pageCountSignal_defaultValue() {
53+
Assertions.assertEquals(0, viewer.pageCountSignal().peek());
54+
}
55+
56+
@Test
57+
void pageCountSignal_documentLoaded_signalUpdated() {
58+
ComponentUtil.fireEvent(viewer,
59+
new DocumentLoadEvent(viewer, true, 6, ""));
60+
Assertions.assertEquals(6, viewer.pageCountSignal().peek());
61+
}
62+
63+
@Test
64+
void pageCountSignal_isReadOnly() {
65+
Assertions.assertFalse(
66+
viewer.pageCountSignal() instanceof ValueSignal<?>);
67+
}
68+
69+
private void fakeClientPropertyChange(String property, Serializable value) {
70+
try {
71+
viewer.getElement().getNode().getFeature(ElementPropertyMap.class)
72+
.deferredUpdateFromClient(property, value).run();
73+
} catch (PropertyChangeDeniedException e) {
74+
throw new RuntimeException(e);
75+
}
76+
}
77+
}

0 commit comments

Comments
 (0)