ENH: Add page-level actions #3382

j-t-1 · 2025-07-16T11:12:08Z

Sets entries in a page object’s additional-actions dictionary.

j-t-1 · 2025-07-16T11:20:40Z

Ideally want to be able to add open and close actions. To avoid a future deprecation, can we add this as _add_js for now?

stefan6419846 · 2025-07-16T11:45:51Z

To avoid a future deprecation, can we add this as _add_js for now?

I do not understand what you are referring to. Could you please elaborate?

j-t-1 · 2025-07-16T11:58:43Z

I could have described better...

def add_js(self, javascript: str, /, *, open_action: bool = True) -> None:

Currently adds either open or close page action. To be able to add both will require modifying the function signature. Or maybe change it so that if given an open action keeps any close action and vice versa.

stefan6419846 · 2025-07-16T12:17:31Z

We shouldn't have public API that is internal as it might break in the future.

Do you have an actual use case for implementing this? Or is this just because the implementation allows this? I have to be honest that I personally never actively used Javascript in PDF files.

j-t-1 · 2025-07-16T12:49:59Z

Let me know if you have a good way to modify this, or the functionality requirements needed.

Currently use the catalog OpenAction but the JavaScript at page-level is more flexible to only run the JavaScript once opening or closing a page.

Will also do a new PR for these tests, as could be in same function?

pypdf/tests/test_javascript.py

Lines 23 to 51 in 5252c2f

    
           def test_add_js(pdf_file_writer): 
        
               pdf_file_writer.add_js("this.print({bUI:true,bSilent:false,bShrinkToFit:true});") 
        
               assert ( 
        
                   "/Names" in pdf_file_writer._root_object 
        
               ), "add_js should add a name catalog in the root object." 
        
               assert ( 
        
                   "/JavaScript" in pdf_file_writer._root_object["/Names"] 
        
               ), "add_js should add a JavaScript name tree under the name catalog." 
        
           def test_added_js(pdf_file_writer): 
        
               def get_javascript_name() -> Any: 
        
                   assert "/Names" in pdf_file_writer._root_object 
        
                   assert "/JavaScript" in pdf_file_writer._root_object["/Names"] 
        
                   assert "/Names" in pdf_file_writer._root_object["/Names"]["/JavaScript"] 
        
                   return pdf_file_writer._root_object["/Names"]["/JavaScript"]["/Names"][ 
        
                       -2 
        
                   ]  # return -2 in order to get the latest javascript 
        
               pdf_file_writer.add_js("this.print({bUI:true,bSilent:false,bShrinkToFit:true});") 
        
               first_js = get_javascript_name() 
        
               pdf_file_writer.add_js("this.print({bUI:true,bSilent:false,bShrinkToFit:true});") 
        
               second_js = get_javascript_name() 
        
               assert ( 
        
                   first_js != second_js 
        
               ), "add_js should add to the previous script in the catalog."

stefan6419846 · 2025-07-16T12:54:21Z

Let me know if you have a good way to modify this, or the functionality requirements needed.

I am not completely sure if I can follow you here, but I would just let the user pass the NameObject and document the basics.

Will also do a new PR for these tests, as could be in same function?

Sorry, but I am rather confused what you want to say/ask with this.

j-t-1 · 2025-07-16T13:31:07Z

Modified. Is easier to pass a str.

Ignore the comment on tests.

@stefan6419846 can this PR be merged?

codecov · 2025-07-16T16:43:28Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.99%. Comparing base (0ceb8a4) to head (925f68e).
⚠️ Report is 9 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3382      +/-   ##
==========================================
+ Coverage   96.97%   96.99%   +0.01%     
==========================================
  Files          54       56       +2     
  Lines        9337     9394      +57     
  Branches     1711     1716       +5     
==========================================
+ Hits         9055     9112      +57     
  Misses        168      168              
  Partials      114      114

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

pypdf/_page.py

stefan6419846 · 2025-09-08T09:52:51Z

pypdf/_page.py

        else:
            self[NameObject("/Annots")] = value

+    def add_js(self, javascript: str, /, action_type: Literal["O", "C"] = "O") -> None:


If this is always tied to an action, why use the generic add_js name?

It is at the page level, either opening or closing a page, so although generic is somewhat self-documenting with code completion on a page object.

Sorry, but how does "self-documenting" and using a specific name correlate here? add_js sounds rather generic, but this only provides the option to execute JavaScript on opening the page (regardless of whether the PDF standard allows for more JavaScript-related functionality or not).

A page object’s additional-actions dictionary only has two trigger events (when the page is opened or closed) but you are correct there are multiple action types (listed in Table 201 — Action types), and it would be better to have a generalized interface.

add_js is now add_action. Because there are many actions this PR will just add a JavaScript action, while providing future extensibility.

@stefan6419846 thanks for the reviews, the previous attempts were not using the correct terminology. Because this function will need to be extensible for future action types, very much welcome your feedback. I could also put this as a discussion.

stefan6419846 · 2025-09-17T18:03:44Z

pypdf/_page.py

+        >>> output.add_action("/C", "JavaScript", 'app.alert("This is page " + this.pageNum);')
+        # Example: This will display the page number when the page is closed.
+
+        Note that this will replace any existing open or close event on this page.


These limitations still sound like we should further refine the public API. add_action should add the new action in a defined manner, not overwrite existing ones - especially when the specification supports having both events defined on the page, but our API design only allows one.

Yes, this needs to be robust; and extensible to the many action types. May be worth posting as a discussion to get ideas.

You can of course open a discussion, but with JavaScript being ignored by many PDF readers and (at least from my experience) limited adoption, I guess there will not be much feedback.

This is one of the reasons why we usually ask to open issues first to discuss new APIs, although we might have missed this there as well and additional feedback would most likely have been sparse as well.

Yes, feedback and demand may be limited. Although this is initially for JavaScript, it will be extensible and generic for other action types. The many and varied action types means this is a route to upgrading the interactive features that pypdf can provide.

j-t-1 added 6 commits July 16, 2025 10:37

ENH: Add page-level actions

25550a1

Sets entries in a page object’s additional-actions dictionary.

Fix errors.

98608ae

Fix more errors.

19a527a

Fix some more errors.

769ccc4

Add trailing newline

ac16b2b

Fix incompatible type "str", expected "bytes" error

d90407c

j-t-1 added 3 commits July 16, 2025 15:50

Update to use NameObject directly

f7679e7

Fix errors.

06b31d2

Fix error

2f5b28a

Merge branch 'main' into javascript

884de23

stefan6419846 reviewed Aug 26, 2025

View reviewed changes

pypdf/_page.py Outdated Show resolved Hide resolved

j-t-1 and others added 3 commits August 26, 2025 17:14

Use a Literal type

0ce99e7

Use double quotes

bcd4ae3

Merge branch 'main' into javascript

3bdf63b

stefan6419846 reviewed Sep 8, 2025

View reviewed changes

j-t-1 added 4 commits September 17, 2025 08:42

Change function name, to make it generalizable

6512658

Make function extensible for future action types

533e4f5

Fix errors

444ea7e

Increase readability

925f68e

stefan6419846 reviewed Sep 17, 2025

View reviewed changes

stefan6419846 added needs-discussion The PR/issue needs more discussion before we can continue on-hold PR requests that need clarification before they can be merged.A comment must give details labels Sep 20, 2025

ENH: Add page-level actions #3382

Are you sure you want to change the base?

ENH: Add page-level actions #3382

Uh oh!

Conversation

j-t-1 commented Jul 16, 2025

Uh oh!

j-t-1 commented Jul 16, 2025

Uh oh!

stefan6419846 commented Jul 16, 2025

Uh oh!

j-t-1 commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stefan6419846 commented Jul 16, 2025

Uh oh!

j-t-1 commented Jul 16, 2025

Uh oh!

stefan6419846 commented Jul 16, 2025

Uh oh!

j-t-1 commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

stefan6419846 Sep 8, 2025

Choose a reason for hiding this comment

Uh oh!

j-t-1 Sep 8, 2025

Choose a reason for hiding this comment

Uh oh!

stefan6419846 Sep 8, 2025

Choose a reason for hiding this comment

Uh oh!

j-t-1 Sep 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stefan6419846 Sep 17, 2025

Choose a reason for hiding this comment

Uh oh!

j-t-1 Sep 17, 2025

Choose a reason for hiding this comment

Uh oh!

stefan6419846 Sep 17, 2025

Choose a reason for hiding this comment

Uh oh!

j-t-1 Sep 17, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

j-t-1 commented Jul 16, 2025 •

edited

Loading

j-t-1 commented Jul 16, 2025 •

edited

Loading

codecov bot commented Jul 16, 2025 •

edited

Loading

j-t-1 Sep 17, 2025 •

edited

Loading