ENH: Add page-level actions

pypdf/_page.py

@@ -74,6 +74,7 @@
 from .generic import (
     ArrayObject,
     ContentStream,
+    DecodedStreamObject,
     DictionaryObject,
     EncodedStreamObject,
     FloatObject,
@@ -84,6 +85,7 @@
     PdfObject,
     RectangleObject,
     StreamObject,
+    TextStringObject,
     is_null_or_none,
 )
 
@@ -2156,6 +2158,39 @@ def annotations(self, value: Optional[ArrayObject]) -> None:
         else:
             self[NameObject("/Annots")] = value
 
+    def add_js(self, javascript: str, /, action_type: str = "O") -> None:
+        r"""
+        Add JavaScript which will launch on the open or close action of this
+        page.
+
+        Args:
+            javascript: Your JavaScript.
+            action_type: "/O" or "/C", for open or close action respectively.
+
+        >>> output.add_js('app.alert("This is page " + this.pageNum);', "/O")
+        # Example: This will display the page number when the page is opened.
+        >>> output.add_js('app.alert("This is page " + this.pageNum);', "/C")
+        # Example: This will display the page number when the page is closed.
+
+        Note that this will replace any existing open or close action on this page.
+        Currently only an open or close action can be added, not both.
+        """
+        if action_type not in {"/O", "/C"}:
+            raise ValueError('action_type must be "/O" or "/C"')
+
+        action = DictionaryObject()
+        self[NameObject("/AA")] = action
+        action[NameObject(action_type)] = DictionaryObject(
+            {
+                NameObject("/Type"): NameObject("/Action"),
+                NameObject("/S"): NameObject("/JavaScript"),
+                NameObject("/JS"): TextStringObject(f"{javascript}"),
+            }
+        )
+
+        javascript_object = DecodedStreamObject()
+        javascript_object.set_data(javascript.encode())
+
 
 class _VirtualList(Sequence[PageObject]):
     def __init__(

tests/test_javascript.py

@@ -5,6 +5,7 @@
 import pytest
 
 from pypdf import PdfReader, PdfWriter
+from pypdf.generic import NameObject
 
 # Configure path environment
 TESTS_ROOT = Path(__file__).parent.resolve()
@@ -49,3 +50,21 @@ def get_javascript_name() -> Any:
     assert (
         first_js != second_js
     ), "add_js should add to the previous script in the catalog."
+
+
+def test_page_add_js(pdf_file_writer):
+    page = pdf_file_writer.pages[0]
+
+    with pytest.raises(ValueError) as exc:
+        page.add_js('app.alert("This is page " + this.pageNum);', "/xyzzy")
+    assert (
+        exc.value.args[0] == 'action_type must be "/O" or "/C"'
+    )
+
+    page.add_js('app.alert("This is page " + this.pageNum);', "/O")
+    expected = {"/O": {"/Type": "/Action", "/S": "/JavaScript", "/JS": 'app.alert("This is page " + this.pageNum);'}}
+    assert page[NameObject("/AA")] == expected
+
+    page.add_js('app.alert("This is page " + this.pageNum);', "/C")
+    expected = {"/C": {"/Type": "/Action", "/S": "/JavaScript", "/JS": 'app.alert("This is page " + this.pageNum);'}}
+    assert page[NameObject("/AA")] == expected