Enhancing Adobe Acrobat Forms with JavaScript [2 ed.] 9781484294697, 9781484294703

Citation preview

Enhancing Adobe Acrobat Forms with JavaScript Take Your Forms to the Next Level! — Second Edition — Jennifer Harder

Enhancing Adobe Acrobat Forms with JavaScript Take Your Forms to  the Next Level! Second Edition

Jennifer Harder

Enhancing Adobe Acrobat Forms with JavaScript: Take Your Forms to the Next Level! Jennifer Harder Delta, BC, Canada ISBN-13 (pbk): 978-1-4842-9469-7 https://doi.org/10.1007/978-1-4842-9470-3

ISBN-13 (electronic): 978-1-4842-9470-3

Copyright © 2023 by Jennifer Harder This work is subject to copyright. All rights are reserved by the Publisher, whether the whole or part of the material is concerned, specifically the rights of translation, reprinting, reuse of illustrations, recitation, broadcasting, reproduction on microfilms or in any other physical way, and transmission or information storage and retrieval, electronic adaptation, computer software, or by similar or dissimilar methodology now known or hereafter developed. Trademarked names, logos, and images may appear in this book. Rather than use a trademark symbol with every occurrence of a trademarked name, logo, or image we use the names, logos, and images only in an editorial fashion and to the benefit of the trademark owner, with no intention of infringement of the trademark. The use in this publication of trade names, trademarks, service marks, and similar terms, even if they are not identified as such, is not to be taken as an expression of opinion as to whether or not they are subject to proprietary rights. While the advice and information in this book are believed to be true and accurate at the date of publication, neither the authors nor the editors nor the publisher can accept any legal responsibility for any errors or omissions that may be made. The publisher makes no warranty, express or implied, with respect to the material contained herein. Managing Director, Apress Media LLC: Welmoed Spahr Acquisitions Editor: Spandana Chatterjee Development Editor: Spandana Chatterjee Editorial Assistant: Mark Powers Cover image designed by eStudioCalamar Distributed to the book trade worldwide by Springer Science+Business Media New York, 1 New York Plaza, Suite 4600, New York, NY 10004-1562, USA. Phone 1-800-SPRINGER, fax (201) 348-4505, email [email protected], or visit www.springeronline.com. Apress Media, LLC is a California LLC and the sole member (owner) is Springer Science + Business Media Finance Inc (SSBM Finance Inc). SSBM Finance Inc is a Delaware corporation. For information on translations, please e-mail [email protected]; for reprint, paperback, or audio rights, please e-mail [email protected]. Apress titles may be purchased in bulk for academic, corporate, or promotional use. eBook versions and licenses are also available for most titles. For more information, reference our Print and eBook Bulk Sales web page at http://www.apress.com/bulk-sales. Any source code or other supplementary material referenced by the author in this book is available to readers on GitHub. For more detailed information, please visit http://www.apress. com/source-code. Printed on acid-free paper

Table of Contents About the Author�������������������������������������������������������������������������������xiii About the Technical Reviewer������������������������������������������������������������xv Acknowledgments����������������������������������������������������������������������������xvii Introduction���������������������������������������������������������������������������������������xix

Part I: Basic Form Improvements������������������������������������������������1 Chapter 1: A Fundamental Forms Primer���������������������������������������������3 Forms Review�������������������������������������������������������������������������������������������������������3 Fields Refresher��������������������������������������������������������������������������������������������������15 Properties Refresher�������������������������������������������������������������������������������������������24 Text Box Field Properties and Date Field Properties Dialog Boxes����������������25 Dropdown Properties Dialog Box�������������������������������������������������������������������26 List Box Properties Dialog Box����������������������������������������������������������������������28 Check Box Properties Dialog Box������������������������������������������������������������������29 Radio Button Properties Dialog Box���������������������������������������������������������������30 Button Properties and Image Properties Dialog Box�������������������������������������31 Digital Signature Properties Dialog Box��������������������������������������������������������32 Barcode Properties Dialog Box����������������������������������������������������������������������33 Tabs Refresher����������������������������������������������������������������������������������������������������34 Editing Your Form with the More Menu and Right Pane�������������������������������������44

iii

Table of Contents

Setting the Field Tab Order Using the Menu Options�������������������������������������46 Clearing a Form While Working���������������������������������������������������������������������55 Summary������������������������������������������������������������������������������������������������������������58

Chapter 2: Introduction to Actions�����������������������������������������������������59 Getting Started����������������������������������������������������������������������������������������������������59 Rating Forms Value Averaging and Sum: Working with Text Fields��������������������61 The Validate Tab���������������������������������������������������������������������������������������������64 The Calculate Tab for the Grand Total Using Sum�����������������������������������������������69 Sum and Averaging Using Check Boxes or Radio Buttons with Text Fields��������72 Using Radio Buttons on Page 3 of the Project�����������������������������������������������74 Using Check Boxes on Page 3 of the Project�������������������������������������������������80 Turning Check Boxes into Radio Buttons�������������������������������������������������������82 Basic Action Button Triggers for Reset Buttons and Printing Buttons�����������������86 Reset Button��������������������������������������������������������������������������������������������������86 Print Form Button������������������������������������������������������������������������������������������90 Summary������������������������������������������������������������������������������������������������������������93

Chapter 3: Creating a QR Code Custom Stamp�����������������������������������95 Customizing Your QR Code Stamp����������������������������������������������������������������������97 QR Code Creation������������������������������������������������������������������������������������������������98 Using the Stamp Tool����������������������������������������������������������������������������������������104 Final Thoughts: QR Code for Professional Printing��������������������������������������������108 Summary����������������������������������������������������������������������������������������������������������110

Chapter 4: Buttons, Navigation, Form, and Nonform Actions�����������111 Creating a Button Icon��������������������������������������������������������������������������������������112 Example of a Button as a Label Only�����������������������������������������������������������116 Example of a Button Combination of Icon Only�������������������������������������������119

iv

Table of Contents

Nonform Properties Actions������������������������������������������������������������������������������121 Pages�����������������������������������������������������������������������������������������������������������121 Bookmarks��������������������������������������������������������������������������������������������������124 Web and Custom Hyperlinks������������������������������������������������������������������������128 Rich Media Nonform Navigation Buttons�����������������������������������������������������135 Layers Basic Actions�����������������������������������������������������������������������������������137 Other Nonform Actions That Can Affect Sticky Note or Markup Tools Indirectly��������������������������������������������������������������������������������������������140 Triggers for Actions�������������������������������������������������������������������������������������������140 Choose an Action That Requires No Code���������������������������������������������������������142 Newsletter Navigation with Buttons�����������������������������������������������������������������150 Form Navigation with a Button as a Helpful Hint����������������������������������������������154 Adding a Comb of Characters���������������������������������������������������������������������������157 Before Comb and After Comb����������������������������������������������������������������������158 More Action Triggers to Show and Hide������������������������������������������������������������161 Hide and Clear Fields Button�����������������������������������������������������������������������164 Set Layer Visibility���������������������������������������������������������������������������������������������167 Using Bookmarks����������������������������������������������������������������������������������������168 Using Buttons����������������������������������������������������������������������������������������������171 Summary����������������������������������������������������������������������������������������������������������173

Part II: Simplified Field Notation and Basic JavaScript�����������175 Chapter 5: Introduction to Simplified Field Notation and JavaScript����������������������������������������������������������������������������������������177 Getting Started��������������������������������������������������������������������������������������������������178 Text Field, Date, and Drop-Down List Properties�����������������������������������������������179 Actions Tab��������������������������������������������������������������������������������������������������179 Format Tab���������������������������������������������������������������������������������������������������180 v

Table of Contents

Validate Tab�������������������������������������������������������������������������������������������������182 Calculate Tab�����������������������������������������������������������������������������������������������182 Check Box, Radio Button, Image Field, and Button Properties��������������������������183 List Box Properties��������������������������������������������������������������������������������������������184 Digital Signature Properties������������������������������������������������������������������������������186 Barcode Properties�������������������������������������������������������������������������������������������187 Global Document JavaScript�����������������������������������������������������������������������������188 Web Links and References��������������������������������������������������������������������������195 Regular Forms vs. E-Signature Forms��������������������������������������������������������195 JavaScript and Acrobat on the Document Level�����������������������������������������������197 Summary����������������������������������������������������������������������������������������������������������197

Chapter 6: Basic and Complex Calculations�������������������������������������199 Getting Started��������������������������������������������������������������������������������������������������200 Sum Value���������������������������������������������������������������������������������������������������������202 Simplified Field Notation�����������������������������������������������������������������������������������204 JavaScript Custom Calculation Script���������������������������������������������������������������207 Final Thoughts on Working with the Calculate Tab�������������������������������������������211 JavaScript Script Validation for Displaying Zero�����������������������������������������������214 The Final Line of Code���������������������������������������������������������������������������������216 Drop-Down Alternatives������������������������������������������������������������������������������218 Set Field Calculation Order��������������������������������������������������������������������������219 Resetting Your Field of Focus����������������������������������������������������������������������������221 Summary����������������������������������������������������������������������������������������������������������225

Chapter 7: Format Calculations��������������������������������������������������������227 Number Formatting�������������������������������������������������������������������������������������������230 Formatting with a Percentage��������������������������������������������������������������������������233

vi

Table of Contents

A Workaround for the Percentage���������������������������������������������������������������235 Reset Fields with JavaScript�����������������������������������������������������������������������241 Date Formatting������������������������������������������������������������������������������������������������242 Date Formatting with JavaScript�����������������������������������������������������������������244 Time Formatting������������������������������������������������������������������������������������������������251 Time Formatting with JavaScript, a Custom Example���������������������������������256 Comb of Characters for Dates���������������������������������������������������������������������260 Special Formatting��������������������������������������������������������������������������������������������261 Final Thoughts���������������������������������������������������������������������������������������������������262 Drop-Down Alternatives������������������������������������������������������������������������������263 More Information on Adding Decimal Places and Leading Zeros����������������263 Summary����������������������������������������������������������������������������������������������������������264

Chapter 8: Various JavaScript Alerts, Notes, and Time Stamps�������267 Alert Types��������������������������������������������������������������������������������������������������������269 Create a Document JavaScript�������������������������������������������������������������������������270 Viewer Version and Validation Alert�������������������������������������������������������������������274 Document Actions���������������������������������������������������������������������������������������������277 Document Will Close������������������������������������������������������������������������������������278 Document Will Print�������������������������������������������������������������������������������������279 Alerts Working with Buttons�����������������������������������������������������������������������������280 Adding a Comment Note, Signature, and Time Stamp��������������������������������������283 Signature Field and Time Stamp�����������������������������������������������������������������289 Summary����������������������������������������������������������������������������������������������������������294

Chapter 9: Create Help for Clients with Rollover Text and Alerts�����295 The Rollover Method�����������������������������������������������������������������������������������������296 Mouse Enter������������������������������������������������������������������������������������������������301 Mouse Exit���������������������������������������������������������������������������������������������������302 vii

Table of Contents

Longer Array Example (Optional)�����������������������������������������������������������������302 Extra Noncustom JavaScript Check Box Example���������������������������������������303 How to Show and Hide Fields with JavaScript��������������������������������������������304 The Default Text Method�����������������������������������������������������������������������������������307 The Alert Method�����������������������������������������������������������������������������������������������311 Customer’s Full Name���������������������������������������������������������������������������������312 Date�������������������������������������������������������������������������������������������������������������316 Customer Order Code����������������������������������������������������������������������������������320 Customer’s Company Name������������������������������������������������������������������������322 How to Duplicate Text for Multiple Fields and Make Fields Read-Only�������������324 Set Fields to Read-Only with JavaScript�����������������������������������������������������328 Final Thoughts���������������������������������������������������������������������������������������������������329 Summary����������������������������������������������������������������������������������������������������������330

Chapter 10: Various Types of Formatting with JavaScript���������������331 Adding Global Formatting to Text Fields�����������������������������������������������������������332 Color Properties������������������������������������������������������������������������������������������������338 Array and Variable Examples of Formatting Properties������������������������������������339 Multiline Buttons�����������������������������������������������������������������������������������������������343 Multiline Text�����������������������������������������������������������������������������������������������������346 Complex Formatting Using Check Boxes and a Text Field��������������������������������351 Rich Text Formatting for Text Fields and Comments�����������������������������������������359 Comment Example��������������������������������������������������������������������������������������363 Final Thoughts on Formatting with Text������������������������������������������������������365 Silent Printing���������������������������������������������������������������������������������������������������367 Options for Submit Button Using Email�������������������������������������������������������������370 Summary����������������������������������������������������������������������������������������������������������375

viii

Table of Contents

Part III: Working with More Complex Forms���������������������������377 Chapter 11: Validation with Text Boxes, Alerts, and Radio Buttons�����������������������������������������������������������������������������������379 Money Transfer Example�����������������������������������������������������������������������������������380 Alternate Way to Work with Radio Buttons Without Alerts���������������������������389 Changing the Shipping Price Using Radio Buttons�������������������������������������������393 Additional Radio Button Example with JavaScript and Text Fields and How to Change Data for Time���������������������������������������������������������������������������403 Setting Up the Text Fields����������������������������������������������������������������������������407 Check Box Variation with Date Text Fields���������������������������������������������������409 Notes on Changing Formatting Options for Radio Button, Check Box, and Button Style������������������������������������������������������������������������������������������410 Text Field Validation with Regular Expressions�������������������������������������������������415 Telephone Validation������������������������������������������������������������������������������������417 Name Validation�������������������������������������������������������������������������������������������421 Account Number Validation�������������������������������������������������������������������������424 Email and URL Validation�����������������������������������������������������������������������������425 Another Phone and Date Example with Two Variables��������������������������������426 Final Thoughts on Formatting Fields�����������������������������������������������������������������429 Summary����������������������������������������������������������������������������������������������������������432

Chapter 12: Working with Dropdown Lists���������������������������������������433 Current Skills Request Form�����������������������������������������������������������������������������434 Parts Order Form����������������������������������������������������������������������������������������������443 Drop-Down Lists with Select Dates and Discounts�������������������������������������������465 Final Thoughts���������������������������������������������������������������������������������������������������470

ix

Table of Contents

Load a Lengthy Single Drop-Down or List Menu�����������������������������������������470 Tips on Changing Custom Formatting for Drop-­Down Lists with JavaScript����������������������������������������������������������������������������������������������������473 Summary����������������������������������������������������������������������������������������������������������474

Chapter 13: Working with List Boxes�����������������������������������������������475 List Box Priority List with Control Buttons��������������������������������������������������������476 The Add Button��������������������������������������������������������������������������������������������481 The Delete Button����������������������������������������������������������������������������������������482 The Clear or Reset Button����������������������������������������������������������������������������483 The Up Button����������������������������������������������������������������������������������������������483 The Down Button�����������������������������������������������������������������������������������������484 Check Box, Drop-Down, and List Box: Example 1���������������������������������������������488 Check Box, List Box, and Multi-Drop-Down: Example 2������������������������������������495 Button Slide Show Variation������������������������������������������������������������������������������505 Extra Example Priority List Improved�����������������������������������������������������������506 Final Thoughts���������������������������������������������������������������������������������������������������515 Hidden Fields�����������������������������������������������������������������������������������������������515 Using List Boxes for a Number Rating���������������������������������������������������������517 Notes on Changing Custom Formatting for List Boxes��������������������������������517 Summary����������������������������������������������������������������������������������������������������������518

Chapter 14: Advanced Navigation: The Pop-Up Menu����������������������519 The Pop-Up Menu Example�������������������������������������������������������������������������������520 Add a Pop-Up Menu Using a Bookmark������������������������������������������������������������527 Final Thoughts���������������������������������������������������������������������������������������������������532 Summary����������������������������������������������������������������������������������������������������������533

x

Table of Contents

Part IV: Beyond the Basics�������������������������������������������������������535 Chapter 15: Action Wizard and JavaScript���������������������������������������537 Working with the Action Wizard������������������������������������������������������������������������538 Reuse JavaScript from Chapter 8����������������������������������������������������������������549 Is It a Custom Action or a Custom Command?��������������������������������������������������550 Create and Manage Custom Commands�����������������������������������������������������551 Summary����������������������������������������������������������������������������������������������������������552

Chapter 16: Multistate Check Boxes�������������������������������������������������553 The Problem of Multistate Check Boxes�����������������������������������������������������������553 Bonus Star Rating Idea�������������������������������������������������������������������������������������563 Select All or Deselect All Check Boxes at Once������������������������������������������������565 Summary����������������������������������������������������������������������������������������������������������569

Chapter 17: Importing an Image into a Button���������������������������������571 Creating the Button�������������������������������������������������������������������������������������������572 Summary����������������������������������������������������������������������������������������������������������577

Chapter 18: Multiple Formatting������������������������������������������������������579 The Problem of Multiple Formatting�����������������������������������������������������������������579 Option 1: Do It Yourself��������������������������������������������������������������������������������������583 Price Script��������������������������������������������������������������������������������������������������585 No Price Script���������������������������������������������������������������������������������������������586 Adding a Degree Symbol and Formatting Range�����������������������������������������593 Option 2: Contact a Professional�����������������������������������������������������������������������598 Summary����������������������������������������������������������������������������������������������������������600

xi

Table of Contents

Chapter 19: Digital Signatures and Barcodes�����������������������������������601 Digital Signatures and Security������������������������������������������������������������������������602 Working with Digital Signatures and Other Adobe Security Tools���������������611 Create a Security Puzzle������������������������������������������������������������������������������620 Barcodes�����������������������������������������������������������������������������������������������������������625 Summary����������������������������������������������������������������������������������������������������������628

Chapter 20: What Are E-Signature Forms and Web Forms?�������������629 A Brief Look at Request E-Signatures and Resources��������������������������������������631 What Are Web Forms?���������������������������������������������������������������������������������������649 Summary����������������������������������������������������������������������������������������������������������685

Part V: Putting It into Practice�������������������������������������������������687 Chapter 21: Homework Assignments�����������������������������������������������689 Homework Assignment 1: Show and Hide��������������������������������������������������������689 Homework Assignment 2: Working with JavaScript to Create Formulas����������708 Area of a Circle A = π r 2������������������������������������������������������������������������������710 Field: CircumferenceRow1 Circumference of a Circle C = 2 π r������������������711 Field: VolumeRow1 Volume of a Sphere V = 4/3 π r3�����������������������������������711 Field: FahrenheitRow1 Celsius to Fahrenheit to Formula. (°C x 9/5) + 32 = °F.������������������������������������������������������������������������������������711 Field: CelsiusRow1_2 Fahrenheit to Celsius Formula. (°F - 32) x 5/9 = °C��������������������������������������������������������������������������������������712 Homework Assignment 3: Custom Validation and Regular Expressions�����������715 Homework Assignment 4: Personal Drop-Down List Menu and Definitions Text Box�������������������������������������������������������������������������������������������726 Summary����������������������������������������������������������������������������������������������������������735

Index�������������������������������������������������������������������������������������������������737 xii

About the Author Jennifer Harder has worked in the graphic design industry for more than 15 years. She has a degree in graphic communications and is currently teaching Adobe Acrobat and Adobe Creative Cloud courses at Langara College. She is the author of several Apress books and related videos.  

xiii

About the Technical Reviewer Sourabh Mishra is an entrepreneur, developer, speaker, author, corporate trainer, and animator. His programming experience includes C/C++, ASP. NET, C#, VB .NET, WCF, SQL Server, Entity Framework, MVC, Web API, Azure, jQuery, Highcharts, and Angular. Sourabh has been awarded MVP status. He has the zeal to learn new technologies and enjoys sharing his knowledge on several online community forums.  He is a founder of IECE Digital and Sourabh Mishra Notes—online knowledge-sharing platform where people can learn new technologies easily and comfortably. He can be reached through the following platforms: •

Email: [email protected]

•

YouTube: https://www.youtube.com/ @SourabhMishraNotes

•

Instagram: https://www.instagram.com/ sourabhmishranotes/?hl=en

•

Twitter: @sourabh_mishra1

xv

Acknowledgments Because of their patience and advice, I would like to thank the following people, for without them I could never have written this book: •

My parents, for encouraging me to read large computer textbooks that would one day inspire me to write my own books

•

My dad, for reviewing the first draft before I sent a proposal

•

My program coordinator, Raymond Chow, at Langara College, who gave me the chance to teach evening courses and allowing me to find new and creative ways to teach software

•

My various freelance clients who I have learned from and researched more about forms and form layout through working on their projects

I would also like to thank Spandana Chatterjee and Mark Powers at Apress for showing me how to lay out a professional textbook and pointing out that even when you think you’ve written it all, there’s still more to write. Also, thanks to the technical reviewer for providing encouraging comments and to the rest of the Apress team for being involved in the printing of this book and making my dream a reality again. I am truly grateful and blessed.

xvii

Introduction Welcome to the first step in an exciting journey called Enhancing Adobe Acrobat Forms with JavaScript. My journey into learning about Adobe software began more than 20 years ago when I started college. I took a two-year graphic communications course in Vancouver, BC. While learning about how to set up documents for print layout using QuarkXPress and later Adobe InDesign, I created PDF files. At that point, I saw the PDF only as a transition from one file format to the next production step, from layout to the printing press. It never crossed my mind what else could be done with PDF files in Adobe Acrobat. Several years after graduating, while doing freelance work for one of my clients, I began to investigate the features of Acrobat to discover what else the program had to offer. In 2008, I decided to learn more about web design and improve my layout skills in Adobe software. After finishing three certificates in web design at Langara College Continuing Studies, I realized that I wanted to help students learn more about Adobe software. There were times through the journey when I read different computer books and felt, “OK, I’ve finished this tutorial or project, but how does this relate to the real world and what I’m trying to accomplish?” In 2011, I became a teaching assistant at Langara College, and this gave me the opportunity to write my own course on introducing students to Adobe Acrobat. While writing it, I realized there was a lot more that could be said about Acrobat than what I could present in a three-evening course. At that point, I was looking at one icon in the Acrobat menu that perplexed me. It was called JavaScript.

xix

Introduction

JavaScript in Acrobat? What was that doing there? The only JavaScript that I knew about at that point was through building websites. Back then I had built a few basic template forms using LiveCycle Designer, MS Word, and Acrobat, but I had never used JavaScript in the Acrobat program. I began to wonder how JavaScript could improve my forms. This is when and how the idea began for developing a book for students on the topic of Acrobat and JavaScript. After years of research, looking at Adobe and Acrobat forums, and studying the questions and concerns users had when trying to add JavaScript to Acrobat, I came to the following conclusions:

xx

•

Users are looking for simple solutions to programming an Acrobat form that they will use in real-world situations. Many are looking for the same answers.

•

When documentation is not written in a simplified manner, the average user becomes intimidated. They will shy away from using the JavaScript menu and eventually give up and ignore the tool. To them, JavaScript coding is like a foreign language, and the average person who has not taken web design lessons does not have a clue what it means or where the code should be inserted, since the form field’s property dialog boxes look nothing like a web page.

•

At some point, it’s important to share with others what you have learned about Acrobat and JavaScript and not keep your thoughts to yourself. That’s what leads to innovative ideas. However, these thoughts need to be organized so that the user can find the solution quickly and be able to comprehend it. And these ideas need to be kept up-to-date.

Introduction

Shortly after compiling my notes for the first edition of this book, Adobe introduced the latest version: Acrobat DC. I saw that the layout of the program had changed and there was no book to show the user how to add JavaScript in this new format. I had completed the first draft of my Advanced Adobe course and had it approved by my program coordinator at the college. In 2016, I realized I could reach a wider audience if the book was published, so I approached Apress. They saw my vision, and that is how this book came to be in your possession. In October 2022, Acrobat has with latest releases removed the reference to Document Cloud (DC) from its name; see https://helpx. adobe.com/acrobat/using/whats-new.html. This is the reason for the removal of “DC” from the title of the second edition. Newer versions of Adobe Acrobat also rely on web forms, which is a new topic we will look at in Chapter 20.

 nderstanding How Acrobat and Its Forms U Work with JavaScript If you are currently using Adobe Acrobat Pro DC or older versions, it’s time to upgrade to the new Adobe Acrobat Pro, which we will be using throughout this book. You can either acquire Adobe Acrobat Pro as a stand-alone program through Adobe or get a Creative Cloud subscription and enjoy all the exciting Adobe programs for a monthly fee. Refer to these links and check if your computer’s operating system meets the system requirements needed for the upgrade: https://helpx.adobe.com/creative-cloud/ system-requirements.html h­ ttps://helpx.adobe.com/acrobat/system-­ requirements.html

xxi

Introduction

Make sure to follow the online instructions and tutorials for installing and working with Acrobat and Creative Cloud. If you already have Adobe Acrobat Pro installed on your machine through the Creative Cloud subscription, you may notice that Acrobat Pro in the upper-left edge of the program says “32-bit,” even if the version number is 22.0 or newer, while the most recent version is 64-bit. Even with regular updates your version may not make this switch automatically. I found that the best way to change this application’s bit from 32 to 64 is to uninstall the application from the Creative Cloud Desktop and then install the program again. Refer to Figure I-1.

Figure I-1.  Installing Acrobat again will change it to the 64-bit version The benefit of changing to the 64-bit version is if you are running a newer computer, you can ensure better performance, security, and usage of memory when opening larger files. As of January 2023, Adobe has been gradually fading out support for the 32-bit system; see https:// helpx.adobe.com/acrobat/kb/end-of-support-acrobat-reader-32bit-os.html.

xxii

Introduction

If you are new to Adobe Acrobat, I encourage you to first read Adobe Acrobat Classroom in a Book by Lisa Fridsma. Her book will give you a basic overview of the new Acrobat features as well as some form basics. However, that book does not go into detail regarding forms when working with JavaScript. I consider my book to be a sequel for intermediate and advanced users to take their forms to the next level. Adobe Acrobat Pro will allow you to add form fields to any PDF file, as I will explain further in Chapter 1. It can even work with pre-existing form fields that were created in Adobe InDesign CC when the file was exported as an interactive PDF. However, it’s important that your client views and interacts with the forms in Acrobat Pro, Standard, or Acrobat Reader. Other PDF readers, and some older browsers, have been known to corrupt the JavaScript programing when saving a document, so keep this in mind when you email the forms to clients. Make sure your clients have the latest version of Acrobat Reader, which is free, and that their browser is up-to-­ date as well. Another reason some users may not be able to interact with JavaScript is that they may have disabled the use of JavaScript in the Acrobat Application under Edit ➤ Preferences Categories JavaScript. See Figure I-2 for how your JavaScript preferences should appear in Adobe Acrobat Pro.

xxiii

Introduction

Figure I-2.  Acrobat Pro Preferences menu for enabling and disabling JavaScript and security features

xxiv

Introduction

The following is an explanation from the Adobe website on some of the settings. See https://helpx.adobe.com/acrobat/using/javascripts-­ pdfs-­security-risk.html for more information. •

Enable Acrobat JavaScript: Uncheck this to disable JavaScript completely or restrict JavaScript through APIs. This setting by default is enabled.

•

Enable menu items JavaScript execution privileges: This enables executing JavaScript by clicking menu items. When off, privileged JavaScript calls can be executed through the menu. Executing nonprivileged JavaScript calls through menu items is not blocked whether this box is checked or not. This setting by default is disabled.

•

Enable global object security policy: This allows JavaScript globally through APIs or trusts specific documents containing JavaScript. This setting by default is enabled.

Note that you will not be working with any JavaScript that could create a security risk, so you can leave the JavaScript Security area at the default settings for these chapters as you work with the files you download. However, I will show you how to enable the JavaScript Debugger in Chapter 5 using the Preferences dialog box. In most cases, Adobe Acrobat will autodetect in a PDF where most form fields can be added in a form, but it’s not a perfect science. It’s up to you as the author to edit and test your forms for errors as you build them and add your JavaScript code.

xxv

Introduction

What to Expect from This Book Enhancing Adobe Acrobat Forms with JavaScript covers up-to-date, real working examples that you can easily download, practice with, and edit to suit your own projects. Using screenshots from Adobe Acrobat Pro, users of previous versions will also be able to utilize these techniques. This book also shows work-arounds and solutions to various form issues you might encounter. JavaScript does not need to be scary. Feel empowered by it and improve your PDF documents!

What You’ll Learn You’ll learn how to do the following in this book:

xxvi

•

Create calculations, rating forms, and QR code stamps using the form elements

•

Understand simplified field notation and basic JavaScript for Acrobat

•

Use buttons for navigation

•

Create complex forms that include drop-down and list boxes in combination with other form fields such as check boxes and radio buttons

•

Use the Action Wizard and JavaScript

•

Improve form navigation and the printing of forms

Introduction

•

Implement various types of alerts and custom validations to improve client-entered data and avoid errors

•

Get new information on Adobe Sign and how it relates to Acrobat Forms online

Note  You can find the project files for the book at ­www.apress. com/9781484228920.

xxvii

PART I

Basic Form Improvements

CHAPTER 1

A Fundamental Forms Primer Chapter Goal: Creating the right form before you add JavaScript to your PDF fields takes time and careful planning. Therefore, it’s important that you become familiar with each of the form tools and the properties that are associated with them. This chapter provides a quick overview of forms, fields, properties, and tabs that will serve as the basis for future chapters. If you are already comfortable with these topics, feel free to jump ahead to Chapter 2.

Forms Review Each form field has within it properties that can be accessed by right-­ clicking the form field. The properties of that form field are organized by tabs. Each form field has slightly different properties and therefore different tabs. Throughout this book you will be working on lessons with a variety of different PDF forms and documents for a fictitious company called the Tourmaline Mining Corporation.

© Jennifer Harder 2023 J. Harder, Enhancing Adobe Acrobat Forms with JavaScript, https://doi.org/10.1007/978-1-4842-9470-3_1

3

Chapter 1

A Fundamental Forms Primer

Each chapter (except for Chapters 1 and 5) comes with JavaScript in a .txt file and PDF files that you can open and compare. You can either view the final PDF file or use the start PDF file and follow along with the notes in these chapters. You can find the link to these files in the introduction and then locate that specific Chapter Project folder.

Note  Please be aware that the PDF files used with this book should be opened only in Adobe Acrobat Pro, Acrobat Reader, or earlier versions of Acrobat DC and not in your web browser or any other PDF creation/reader program. Other PDF readers have been known to corrupt the JavaScript code within the Acrobat PDF files, and then the calculations fail to work. Upon opening Acrobat Pro, make sure to check your preferences at Edit ➤Preferences ➤ Forms. Refer to Figure 1-1. They should be set to the default settings shown in Figure 1-2.

Figure 1-1.  Open Acrobat Pro using your Creative Cloud Desktop App

4

Chapter 1

A Fundamental Forms Primer

Figure 1-2.  Default settings for the Forms tool found in the Preferences 5

Chapter 1

A Fundamental Forms Primer

In this case, all of the General check boxes are enabled. •

Automatically calculate field values

•

Automatically adjust tab order when modifying fields

•

Show focus rectangle

•

Show text field overflow indicator

•

Show field preview when creating or editing form fields

•

Automatically detect Form Fields

•

Auto-enable text editing in Prepare Form

Highlight Color’s check is enabled to show border hover color for fields. Light blue is the color for highlighted fields, and red is the highlight color for required fields. Auto-Complete is set to Off, and there is a description below it explaining what this setting means. Other options in the list are Basic or Advanced. At this point, if these are your settings, you can click Cancel and Exit or make your settings like mine and click OK. These preferences are not saved with the forms but will help you interact with the forms as you work. If you are working with Manage Barcode Parameter, refer to this topic later in the chapter and Chapter 19. The book assumes you are familiar with filling in basic forms or have used PDF forms in the past. If you are unsure of how to use the Prepare Form tool and its autodetection of fields in Acrobat Pro, this section provides a refresher. Draw your form either by hand or create the basic structure in MS Word, Adobe Illustrator, or Adobe InDesign, and then decide what steps you want the form to do and accomplish. Then plan how to execute your goals. Is what you want the form to do possible? Do you need to simplify

6

Chapter 1

A Fundamental Forms Primer

the form? Or do you need to learn more about the topic of forms to create what you want? Make sure to consult with your team or clients as you build the form before you begin to add interactivity. Except for the program of Adobe InDesign, you cannot assemble the form’s interactive fields outside of Acrobat, so you need to make a PDF to do that. Until you are ready to make the PDF, continue to assemble the form in your layout program such as MS Word until it looks the way it should. Then save the MS Word file (.doc or .docx). Then create the PDF. For example, in the case of MS Word, I can use my Acrobat tab to quickly create a PDF or use my File Print tab. Refer to Figure 1-3.

Figure 1-3.  Use the MS Word Ribbon with the Acrobat tab or the Print settings to create your PDF Once you have the final PDF, open it in Acrobat Pro and follow these steps to add interactivity: 1. Click the Tools tab and click the Prepare Form tool, which is found in the Forms & Signatures section (see Figure 1-4).

7

Chapter 1

A Fundamental Forms Primer

Figure 1-4.  Location of Prepare Form tool 2. You can use this tool whether you have a PDF Form open or not. While in the tool, choose, in this case, Single File, locate your file (you can change the files if the thumbnail is not correct), and make sure that form field autodetection is on. Do not select “This document requires signatures” as we will look at that option in Chapter 20 in more detail (Figure 1-5).

8

Chapter 1

A Fundamental Forms Primer

Figure 1-5.  The Prepare Form tool when you first create a new form 3. Click Start. Acrobat will scan the file for fields; if it detects any, it will create the field. However, it is not perfect in its detection, so you may have to add, delete, or edit some fields afterward.

9

Chapter 1

A Fundamental Forms Primer

4. Once you have added your fields, save the file as a new PDF (Ctrl/Cmd+S). Choose to save the file on your computer and then select a folder to save the file into. Make sure that the “Convert to” option is disabled. The new PDF is now an interactive form. Refer to Figure 1-6.

Figure 1-6.  Saving the new PDF form in a folder after autodetection is completed

10

Chapter 1

A Fundamental Forms Primer

Note  You can now, with the Prepare Form tools, create a PDF form in three more ways; refer to Figure 1-5: directly from your scanner, as a blank new document using the Create New option, or using the Create a Web form. We’ll look at that option in Chapter 20. You can now begin adding your formatting and actions to the properties of each field. Test it, and ask others to try it on their computer, before you email it to your clients. Always keep a backup on a disk or USB drive in case something happens to your main computer. Also, make a printout of the PDF and all code in case you need to refer to it later for another project. In this book I have placed a copy of the code in the .txt files in each chapter for reference. Once the fields are in the saved form, you can open the fields at any time with the Prepare Form tool; you do not need to run the autodetection again for that form. Refer to Figure 1-7. You can exit the Prepare Form area partially by toggling the Preview/ Edit button in the upper-right (Figure 1-7). To exit the Prepare Form tool completely, you must click the Close button in the upper-right (Figure 1-7).

11

Chapter 1

A Fundamental Forms Primer

Figure 1-7.  The Prepare Form tool and the tools for adding and working with the fields. Note the Preview/Edit toggle and Exit (Close) buttons in the upper right. Also note the view of a form while in Edit mode before switching to Preview

12

Chapter 1

A Fundamental Forms Primer

For more information on basic forms or basic form creation, check out the following links before you proceed any further in this book: •

https://helpx.adobe.com/acrobat/using/pdfforms-basics.html

•

https://helpx.adobe.com/acrobat/using/createform.html

•

https://helpx.adobe.com/acrobat/using/creatingdistributing-pdf-forms.html

•

https://helpx.adobe.com/acrobat/using/fillingpdf-forms.html

•

https://helpx.adobe.com/acrobat/using/pdf-formfield-properties.html

The Adobe HelpX area for forms has additional links as well, and we will look at some of those options later. But you can use this area as a resource when you need to work with basic forms. While working in the Prepare Form Tool area, you will come across other form tools in the right-side pane, such as the Align and Distribute options, and in the More drop-down menu (Figure 1-7). I will go into more detail about this area and the JavaScript area later in the book. However, you can also refer to the previous web links for more specific details. Refer to Figure 1-8.

13

Chapter 1

A Fundamental Forms Primer

Figure 1-8.  Additional options in the right-hand pane of the Prepare Form tool 14

Chapter 1

A Fundamental Forms Primer

Fields Refresher Fields can be blank and inactive, or they can contain a script that, upon entering or clicking a trigger, sets the action in motion. For example, they can execute a menu item or import form data. In Acrobat Pro, the Prepare Form Menu tool area contains all the field options listed next plus the Selection tool and the newer options Edit Text and Images and Add Text. Fields can be used in any form, while the Selection tool is just an arrow that allows you to select, size, and move them around. From left to right, let’s look at the tool options in this section more closely; refer to Figure 1-9.

Figure 1-9.  Editing and Field options for forms •

Selection tool: This arrow allows you select, size, and move fields. It can also be used to edit text boxes when they are added; you double-click with the arrow on them. Refer to the arrow in Figure 1-9.

•

Edit Text and Images: This is not a field option, but it allows you to edit the text or images surrounding the field while remaining in the Prepare Form tool and saves you time rather than having to close the tool and use the Edit PDF tool instead. When text is selected, the right pane’s Format area changes so that you can edit the selected text or image that is surrounded by a bounding box. Images can be scaled and rotated as well. Refer to Figure 1-10.

15

Chapter 1

A Fundamental Forms Primer

Figure 1-10.  Text change settings in the Prepare Form tool and the selected text with a bounding box •

16

Add Text: This is not a field option, but it allows you to add a new text box while remaining in the Prepare Form tool and saves you time rather than having to close the tool and use the Edit PDF tool instead.

Chapter 1

A Fundamental Forms Primer

Select the tool and click a location on the page that you want the text to appear and start typing, or when you select the tool, drag out a rectangular bounding box for a paragraph area and start typing. Again, the bounding box will appear around the text, and you can scale and rotate as well as edit the format of the text on the right. Refer to Figures 1-10 and 1-11.

Figure 1-11.  Adding text to a page while in the Prepare Form tool and tip message Click the Selection tool arrow if you want to exit the editing options. Now look at the form fields. These can be added to the form when you first select them and then click the page. Use your mouse to hover over each field to read its description and related name. 17

Chapter 1

•

A Fundamental Forms Primer

Text field: Type text, words, or numbers into the field. Refer to Figure 1-12.

Figure 1-12.  Adding a text field •

Check box: Select one or multiple options of an item. Refer to Figure 1-13.

Figure 1-13.  Adding a check box •

18

Radio button: Select one option from a group: yes or no. These options can be mutually exclusive, and you can have more than one group in a form. You must have at least two radio buttons and can add a second if prompted with the initial message. Refer to Figure 1-14.

Chapter 1

A Fundamental Forms Primer

Figure 1-14.  Adding a radio button •

List box: Select one or multiple items in a list of choices. Refer to Figure 1-15.

Figure 1-15.  Adding a list box

19

Chapter 1

•

A Fundamental Forms Primer

Dropdown list: Select an option or choice from a list. Refer to Figure 1-16.

Figure 1-16.  Adding a drop-down list •

Button: This initiates an action such as reset (Clear), submit, and print. Refer to Figure 1-17.

Figure 1-17.  Adding a button field •

20

Image field: This is the same as Button, only with some JavaScript added (more on this topic in Chapter 17). Refer to Figure 1-18.

Chapter 1

A Fundamental Forms Primer

Figure 1-18.  Adding an image field •

Date field: This is the same as a text field but is preformatted to date. It can operate as a date picker. Refer to Figure 1-19.

Figure 1-19.  Adding a date field •

Digital signature: Electronically sign with your signature. Other Acrobat Form and Signature tools can interact with this field as well. We’ll look at this field in Chapter 19 in more detail. Refer to Figure 1-20.

21

Chapter 1

A Fundamental Forms Primer

Figure 1-20.  Adding a digital signature •

Barcode: This is for a product barcode reader. You can encode the data that users type in this form. Refer to Figure 1-21. (Refer to Chapter 19 for more details on this field.)

Figure 1-21.  Adding a barcode The other two icons in this area are a push pin called “keep tool selected (off ) or (on)” so that you can keep applying the same field again, and Field Type Help, which will take you to the Adobe Help forms links we discussed earlier (https://helpx.adobe.com/acrobat/using/creatingdistributing-pdf-forms.html). Refer to Figure 1-22.

22

Chapter 1

A Fundamental Forms Primer

Figure 1-22.  Extra tools on the far right of the fields in the Prepare Form tool Remember to access these fields as shown in Figure 1-23. Select Tools ➤ Prepare Form and then choose a PDF document. Click Start, or if the Fields are already present, then the icons will appear at the top just below your navigation icons.

Figure 1-23.  Form tools available when working with a PDF form in Adobe Acrobat Pro. You can access them by going to the Tools tab and selecting the Prepare Form tool

Note If you require a custom QR code rather than a Barcode field, you can generate one in Adobe InDesign Creative Cloud. QR Codes are like barcodes, and we will look at them more closely in Chapter 3.

23

Chapter 1

A Fundamental Forms Primer

Properties Refresher Each form field contains properties that can be easily accessed while you are in form editing mode. Simply right-click the field you want to edit and choose Properties from the pop-up list (Figure 1-24). Then select the property you want to work with in the various tabs that will appear in the dialog box.

Figure 1-24.  Right-click a field to reveal its properties Various properties can be set for each field depending upon which field is chosen because the number of properties varies. The properties are organized into sections using tabs. Refer to Figures 1-25 through 1-32. Properties can be typed in, checked, or unchecked. The settings are applied as soon as you exit the field and move to another field in the Properties dialog box or when you click the Close button. However, the settings are not fully saved until you save the PDF file. To review, to work with the form fields, you must be in the Prepare Form tool in Edit mode. You will know you are in Edit mode because the Preview button toggle is in the upper right, and the name of each field will appear. You can now either edit one field at a time or multiple fields. Use the Selection tool and either click one field, Shift-click several, or drag a marquee around several and then right-click and choose Properties from the menu.

24

Chapter 1

A Fundamental Forms Primer

Note If you select several fields at once, you may not have access to all tabs depending on the type of fields selected. If you have selected several fields, what you type in the tab properties will apply to all fields selected. You will now be inside the form’s properties dialog box. Now you can change properties within each tab; when you are done, click the Close button to close the dialog box and save your PDF file to confirm the changes. The following sections provide a cursory look at the properties associated with the form fields listed earlier in the chapter.

T ext Box Field Properties and Date Field Properties Dialog Boxes The text field and date field have eight tabs to organize their properties. The only difference between a text field and a date field is that the format category for a date field is preset to Date, while the format category for a text field is preset to None. Note that the heading of the dialog box for both is “Text Field Properties.” Refer to Figure 1-25.

25

Chapter 1

A Fundamental Forms Primer

Figure 1-25.  Text field and date properties

Dropdown Properties Dialog Box The Dropdown Properties dialog box also has eight tabs to organize the properties. The tabs have the same names as the text field properties and contain many equivalent properties; however, if you compare the Options 26

Chapter 1

A Fundamental Forms Primer

tab on the Text Field Properties dialog box to the Options tab on the Dropdown Properties dialog box, it will look different because drop-down menus are meant to hold multiple items with export values, while a text field can hold only one default value. While it is an option, the Calculate tab is rarely used with the dropdown lists. Refer to Figure 1-26.

Figure 1-26.  Dropdown Properties dialog box

27

Chapter 1

A Fundamental Forms Primer

List Box Properties Dialog Box List box properties act like drop-down lists. However, there are only six tabs to organize the properties. Like drop-down lists, they can have multiple export values. Unlike drop-down lists, you can select more than one value at a time. Refer to Figure 1-27.

Figure 1-27.  List Box Properties dialog box

28

Chapter 1

A Fundamental Forms Primer

Check Box Properties Dialog Box The Check Box Properties dialog box has five tabs to organize the properties. A check box can be checked either on or off. You cannot enter text into a check box; however, you can give it a word or number value. Like all other properties, you can alter its appearance and color (via the Appearance and Option tabs). Check boxes can act separately or in groups. Refer to Figure 1-28.

Figure 1-28.  Check Box Properties dialog box

29

Chapter 1

A Fundamental Forms Primer

Radio Button Properties Dialog Box The Radio Button Properties dialog box, like the Check Box Properties dialog box, has five tabs to organize the properties. A radio button must come in pairs or groups or more than two that can be checked either on or off. While one is on, the others are off. You cannot enter text into a radio button; however, you can give it a word or number value. Like all other properties, you can alter its appearance and color (Appearance and Option tabs). You can have more than one group of radio buttons, but there must always be at least two in any group. Refer to Figure 1-29.

Figure 1-29.  Radio Button Properties dialog box 30

Chapter 1

A Fundamental Forms Primer

 utton Properties and Image Properties B Dialog Box Button properties and image properties are identical except that image properties have a small bit of code in the Actions tab to allow the importing of an image. See Chapter 17 for details. Both contain five tabs, and the tabs each have identical properties. Buttons can have more than two states; however, image buttons operate independently of regular button properties once the JavaScript is applied. Refer to Figure 1-30.

Figure 1-30.  Button Properties dialog box 31

Chapter 1

A Fundamental Forms Primer

Digital Signature Properties Dialog Box Digital signatures are used for signing electronic PDF forms with a client’s digital signature, which is stored on their computer. The digital signature field appears like the text field; however, it has only five tabs to organize its properties and is specifically designated for signatures only. Chapter 19 offers more details on digital signatures and the tools used in conjunction with it. Refer to Figure 1-31.

Figure 1-31.  Digital Signature Properties dialog box

32

Chapter 1

A Fundamental Forms Primer

Barcode Properties Dialog Box The barcode field properties are organized into five tabs. A barcode’s main purpose is to create a scannable barcode that relates to the information that is entered into the various fields around it. Chapter 19 offers more details on barcodes. Refer to Figure 1-32.

Figure 1-32.  Barcode Field Properties dialog box

33

Chapter 1

A Fundamental Forms Primer

Tabs Refresher As mentioned, all form fields have similar tabs, as listed here. These are the options on the General tab: •

Name: This is the name of the field.

•

Tooltip: This adds a type of accessibility text to the field so that people with visual impairments can scan the field and know its purpose. It is also a way to give a helpful hint for those who do not know the purpose of entering text in the field.

•

Common properties: This form field indicates whether it is visible, hidden, visible but doesn’t print, or hidden but printable. This is not available to barcodes.

•

Orientation: This setting adjusts the angle of the field to 0, 90, 180, or 270 degrees. It is not available to barcodes.

•

Read only: You can read the text within but not alter it. This is not available to barcodes; by default they are read-only.

•

Required: This field is required to complete the form. An error message may appear if the field is not filled. This is not available to buttons, list boxes, image fields, and barcodes.

These are the options on the Appearance tab (not available to barcodes): •

Border and colors: The following are the settings: •

34

Border color: This is the color of the border surrounding the field. Set this to a color or to no color.

Chapter 1

•

A Fundamental Forms Primer

•

Line thickness: This is the thickness of the border: thin, medium, or thick.

•

Fill color: This is the fill color of the field. Set it to a color or no color. A color will block the background behind the field.

•

Line style: This is the style of the line going around the field: solid, dashed, beveled, inset, or underlined.

Text: This is the font size (not available to signatures), text color, and font (not available to check boxes or radio buttons). A size of Auto will change the font size to fit the text box as the user types.

These are the options on the Position tab (available for all fields): •

Units: The following are the units of measurement of the size and position of the fields: points, picas, millimeters, centimeters, and inches.

•

Position units: The options are left, right, top, bottom, width, and height.

•

Check “Do not change height and width when changing position” if you do not want the size of the box to alter during movement while adjusting the other position settings in the properties dialog box. Entering numbers in the width and height in the dialog box is disabled. Unchecking that box may cause the form field to scale during movement with the other position settings.

35

Chapter 1

A Fundamental Forms Primer

These are the options on the Options tab (not available to digital signatures; these options are only for text and date fields):

36

•

Alignment: This aligns text left, center, or right.

•

Default value: This provides temporary or default text for the field before the user types in the field.

•

Field is used for file selection: This allows the user to enter a file’s text link info. It is not available for the date field. It is available when “Check spelling” and Multiline are disabled and “Scroll long text” is enabled.

•

Password: This creates *** to mask the actual text. It is not available for the date field. It is available when “Check spelling” and Multi-line are disabled.

•

Check spelling: This indicates if there is a spelling error in the user-entered data when checked.

•

Multi-line: This allows you to enter more than one line of text in the field. It is not available for the date field.

•

Scroll long text: If there is more text than the field can handle, a scroll bar appears.

•

Allow rich text formatting: This allows users to make the text bold or italic. It is not available for the date field.

•

Limit of characters: When enabled, this limits the number of characters allowed in a field, by a set number.

•

Comb of characters: When enabled, this creates a divider between characters so they are easier to read later and compare (see Chapter 4). The characters are spread out. This is good when entering numbers. However, other settings in this tab need to be disabled first before you can set the comb at its amount.

Chapter 1

A Fundamental Forms Primer

These are the options for list boxes and drop-down lists only: •

Item: Enter the item name or option you want to appear in the list.

•

Export value: Enter its export value letter or numbers. It can be filled or left blank.

•

Item List: This lists all the items. The highlighted item is selected by default in the list.

•

Add, Delete, Up, Down buttons: Add, remove, or alter an item’s order in the list when the sort items option is not selected.

•

Sort items: Sort alphabetically or numerically.

•

Allow user to enter custom text: Allow the user to enter their own text. This is not available for list boxes.

•

Check spelling: This indicates if there is a spelling error when a user enters text. This is not available for list boxes.

•

Commit selected value immediately: When selected, the value may interact with another field’s value. Otherwise, the user must wait until they tab out of the field and click another form field. It will not operate with multiple list box selections.

•

Multiple selection: This lets you select multiple items in a list box only.

These are the options for check boxes and radio buttons only: •

Style: The styles are check, circle, cross, diamond, square, and star. The size is determined in the Appearance panel by the text area.

37

Chapter 1

A Fundamental Forms Primer

•

Export value: This is the value of the field. It is for check boxes only.

•

Radio button choice: This is the same as the export value. Radio buttons in a group must have the same name on the General tab but can have a different export value on the Options tab.

•

Check box is checked by default: This sets the box to be checked when the form opens.

•

(Radio) button is checked by default: The box appears filled when the form opens.

•

(Radio) buttons with the same name and choice are selected in unison: This is the only way to make two or more radio buttons within the same group appear selected.

These are the options for buttons and image fields:

38

•

Layout: This adds a layout for the icon and label (see Chapter 4).

•

Advanced button: This creates a more advanced layout for the Icon button (see Chapter 4).

•

Behavior alters the states of the button: The options are none, push, outline, and invert (see Chapter 4).

•

Icon and label state: •

State: This sets how the button appears in up, down, and rollover states.

•

Label: This sets the text name on the button.

Chapter 1

•

A Fundamental Forms Primer

Icon: This is a thumbnail of the chosen icon. •

Choose icon: This allows you to choose an icon.

•

Clear: This clears the icon from the field.

These are the options for barcodes only: •

Symbology: There are distinct types of barcodes available.

•

Compress data encoding barcode: Data is compressed before it is encoded.

•

Decode condition: These are custom and manage barcode parameters (see Preferences in Figure 1-2), such as how the barcode will be decoded by some device such as a scanner.

•

Settings: This is the settings for that barcode.

These are the options on the Actions tab (for all form fields; more info in Chapters 4 and 5), •

Add an action: Select what triggers the action when the field is entered.

•

Select action: Select what kind of action or event is triggered.

•

Add button: This adds the action and opens various dialog boxes to edit actions that upon committing will then display in the Actions area.

•

Up button: This moves the action in its order.

•

Down button: This moves the action in its order.

39

Chapter 1

A Fundamental Forms Primer

•

Edit button: This edits the action in the original dialog box or JavaScript Editor.

•

Delete button: This deletes the selected action or multiple actions under the trigger.

These are the options on the Format tab (the Text, Date Field, and Dropdown lists; refer to Chapters 6 and 7 for a detailed explanation): •

None: This is for text and numbers with no true numeric value.

•

Number: This formats the numbers with or without decimal places, separator style, currency symbol, symbol location, and negative number style using parentheses and red text.

•

Percentage: This formats the percentage with decimal places and separator style.

•

Date: This formats the type of date options.

•

Time: This formats the type of time options.

•

Special: This formats the ZIP code, phone number, Social Security number, and arbitrary mask options.

•

Custom: This creates custom option scripts called Format and Key Stroke that you can edit.

These are the options on the Validate tab (Text, Date Field, and Dropdown lists):

40

•

Field value is not validated: The field does not require validation.

•

Field value is in range: The options are From a Number, To a Number such as Numbers 1–5.

•

Run a custom validation script. The JavaScript script can be edited.

Chapter 1

A Fundamental Forms Primer

These are the options on the Calculate tab (Text, Date Field, and Dropdown lists): •

Value is not calculated. Use this if you only want the user to enter default text.

•

Value is the (sum, product, average, minimum, maximum) for the following fields: Use the Pick button to choose the fields.

•

Simplified field notation: The Edit button allows you to enter a script in the JavaScript Editor.

•

Custom calculation script: The Edit button allows you to enter it in the JavaScript Editor.

These are the options on the Selection Change tab (list box only): •

Do nothing (if no action is required). This allows doing nothing. No script is triggered and only selections are made.

•

Execute this script: Add a custom script. Edit allows you to enter it in the JavaScript Editor.

These are the options on the Signed tab (Digital Signature field only; refer to Chapter 19): •

Nothing happens when signed: No action happens. The following setting or option is compatible only with Acrobat 6.0 and later.

•

Mark as read-only: All fields or only certain ones can be selected to trigger or prevent certain fields from becoming read-only when the signature is filled creating further changes to the signed document. Use the Pick button to choose the fields.

•

This script executes when the field is signed: The Edit button allows you to enter in the JavaScript Editor. 41

Chapter 1

A Fundamental Forms Primer

These are the options on the Value tab (Barcode field only; refer to Chapter 19 for more info): •

Encoding using tab delimited or XML: This option is used with the pick button to choose the fields.

•

Include field names: This is available when the encoding is set to tab delimited.

•

Custom calculation script: Edit allows you to enter in the JavaScript Editor.

•

“Reference to published form” will appear as a link in the dialog box’s field: For example it may look something like this line of text “File//C/Users” pointing to a location on your computer.

These are the options found on all tabs and fields: •

Locked: When selected, this prevents any further changes to any form field properties until unlocked. This includes position and scaling.

•

Close: This button closes the form field’s Properties dialog box. If you are changing the properties of multiple fields, you can leave the Properties dialog box open. Click each field to change its properties. And then click the Close button when done.

The following are the tabs you’ll find in most of the fields. Figure 1-33 shows the tabs found in the Text Field Properties dialog box.

Figure 1-33.  The tabs that contain the properties 42

Chapter 1

A Fundamental Forms Primer

Bear in mind that the properties can differ depending upon the type of field chosen. For example, the Options tab properties are different for a text field versus a barcode or a radio button (Figures 1-34 and 1-35).

Figure 1-34.  Options tab properties for Text Field and Barcode Field dialog boxes 43

Chapter 1

A Fundamental Forms Primer

Figure 1-35.  Options tab properties for Radio Button Properties dialog box

E diting Your Form with the More Menu and Right Pane In the pane on the right are a few more settings we will take a brief look at before we conclude this chapter. To make sure you can see your field clearly, make sure that in the More menu, “Highlight Existing fields” is enabled. Refer to Figure 1-36.

44

Chapter 1

A Fundamental Forms Primer

Figure 1-36.  Prepare Form tool options in the pane on the right 45

Chapter 1

A Fundamental Forms Primer

 etting the Field Tab Order Using S the Menu Options The More drop-down menu, found in the pane on the right, works in conjunction with the fields found on the page as well as the same fields shown as a list which can each be selected to access the same field’s properties. Those fields and their selection options appear below the More menu. You can use the fields in the list to better select overlapping fields on the page. You can place or duplicate many fields across a page as well as create multiple copies of a field using the More menu and the related dialog boxes while a field is selected. Refer to Figure 1-37 and Figure 1-38.

Figure 1-37.  More menu options for duplicating a selected field

46

Chapter 1

A Fundamental Forms Primer

Figure 1-38.  Create Multiple Copies of Fields dialog box and a preview of the selected field with default settings While moving around the form, the order of those fields can become jumbled or out of order as you move from page to page. At some point, after reviewing the field properties and then previewing the form, using the Tab key to tab through the fields, as a client would do while filling out the form, you may discover that you are randomly moving from field to field not in the order you intended. At this point you need to check and edit the tab order. 47

Chapter 1

A Fundamental Forms Primer

To do this from the More drop-down menu, choose Show Tab Numbers. Refer to Figure 1-39.

Figure 1-39.  From the More menu, choose Show Tab Numbers Upon selecting this option, you will receive an information message that explains how to alter the tab order. You can do this manually by dragging and dropping the fields in this lower list on the right. Click OK. You will now be able to see the tab number on the field; it is checked as active in the menu. Refer to Figure 1-40 and Figure 1-41.

48

Chapter 1

A Fundamental Forms Primer

Figure 1-40.  Activating the Show Tab Numbers settings

49

Chapter 1

A Fundamental Forms Primer

Now look at the fields list in the right pane. This will show you how the fields are in the current order page by page. Refer to Figure 1-41.

Figure 1-41.  Setting field order by page However, here you can do several things to alter the tab order.

50

Chapter 1

A Fundamental Forms Primer

The first menu beside the field’s name lets you choose the following options: Order Tabs by Structure, by Row, by Column, Manually, Unspecified, and Show Tab Numbers. Refer to Figure 1-42.

Figure 1-42.  Field setting for tab order Currently, in my example, by default it is set to Order Tabs Unspecified with the tab numbers shown; however, I could change this to Manually after clicking OK to the warning message. Refer to Figure 1-43.

Figure 1-43.  Info alert message that appears and gives instructions about tabs if you change from an Order Tabs Unspecified to Order Tabs Manually

51

Chapter 1

A Fundamental Forms Primer

I could then, in the Fields panel, drag one field and alter the order to the tabbing order of my choice. Refer to Figure 1-44.

Figure 1-44.  Changing the tab order in the Fields panel

52

Chapter 1

A Fundamental Forms Primer

If I found this to be out of order, I could drag the field back in the fields list, or from the menu choose other options from the tab list such as Order Tabs by Row to reset the order. Refer to Figure 1-42. Ultimately, before you submit a form to a client, it is a good idea to preview your tab order and then save your file. If, while working in your form, you notice that your fields in the fields pane are not appearing in tab order, check in your next menu (AZ) that the Tab Order option is checked and not Alphabetic Order, which does not show the page number. This does not alter the tab order on the pages, and you may not be able to reorder the fields on this setting. Refer to Figure 1-45.

Figure 1-45.  Make sure Tab Order is selected in the list Either way, you cannot move a field from page to page unless you select a field and select Edit ➤ Cut and Edit ➤ Paste on a new page. Likewise, you can also right-click a field and from the pop-up menu move the tab order up or down for a specific field. Other operations include deleting a field. Refer to Figure 1-46.

53

Chapter 1

A Fundamental Forms Primer

Figure 1-46.  Right-clicking a field reveals other form editing options You can learn more about those settings here: https://helpx.adobe.com/acrobat/using/pdf-form-fieldbasics.html You can delete a selected field or multiple selected fields when you press the Delete key on your keyboard and use Edit ➤ Undo to get the field back again. 54

Chapter 1

A Fundamental Forms Primer

Clearing a Form While Working While editing and previewing your forms, you may want to reset or clear the content of the fields so that you can make alterations or present a final form to the client. Remember under the More menu to frequently use the Clear Form option before you save and close your final file. Refer to Figure 1-47.

Figure 1-47.  Clearing form fields using the More menu Keep in mind, however, that this option is only for when you build the form in Acrobat Pro. Someone who is using Reader will not have the option to reset the form like this. So, it is good to add a button field that can do this for all or selected fields if the client needs to reset or clear the fields. We will look at how to do this in Chapter 2. The More menu also has a few other helpful items, depending upon the type of form work. For example, we will look at e-signing in Chapter 19 and Chapter 20. Refer to Figure 1-48. 55

Chapter 1

A Fundamental Forms Primer

Figure 1-48.  Preparing a form for e-signing Though not the topic of this book, if you are specifically importing data to fields or exporting data to another file format for use with a database, refer to Figure 1-49.

Figure 1-49.  More menu options for working with data in forms The following links may be of use on that topic: https://helpx.adobe.com/acrobat/using/collecting-pdf-formdata.html https://helpx.adobe.com/acrobat/using/creating-distributingpdf-forms.html These links will also give you some information on Distribute and Tracker, which are not topics discussed in this book. You can find these same items in the Edit ➤ Form Options submenu when a form is first opened before entering the Prepare Form tool. Refer to Figure 1-50.

56

Chapter 1

A Fundamental Forms Primer

Figure 1-50.  Distribute and Track button form options Another option in the More Tab area is Set Field Calculation Order, which will be mentioned in Chapter 6. Refer to Figure 1-51.

Figure 1-51.  More menu options for Set Field Calculation Order Later in Chapter 8 and the following chapters, we will be looking at the final options in the More menu that pertain to JavaScript for the options Debugger, Debug, All JavaScripts, Document JavaScripts, and Document Actions. Refer to Figure 1-52.

57

Chapter 1

A Fundamental Forms Primer

Figure 1-52.  More menu JavaScript options

Summary This chapter covered the basics of form fields, their tabs, and the properties within those tabs, as well as how to order tabs and additional settings found in the pane on the right of the Prepare Form tool. The next chapter will be an introduction to the basic actions that you can apply to fields.

58

CHAPTER 2

Introduction to Actions Chapter Goal: Now that you have reviewed the basic form properties, you will begin your study of JavaScript by taking a closer look at several types of automatic or preprogrammed actions that can be applied within various tabs within each field. In this chapter, you’ll be working with forms, and you’ll discover how actions can be applied.

Getting Started If you want to work along in this lesson or review the final result, download the Chapter 2 files from the link mentioned in the introduction. The file with the label “Start” is the file without the code, and the file with the label “End” is the final result. You will also find a folder with original MS Word and PDF files if you would like to edit them plus a folder containing the original scripts (.txt) if you would like to add them to your own PDF forms.

Note  To view the properties of a field, you must select the Prepare Form tool. Only then can you right-click or double-click a field to review its properties. If you are creating your form from an original PDF that contains no form fields, refer to the “Forms Review” section in Chapter 1.

© Jennifer Harder 2023 J. Harder, Enhancing Adobe Acrobat Forms with JavaScript, https://doi.org/10.1007/978-1-4842-9470-3_2

59

Chapter 2

Introduction to Actions

You can apply actions to all form fields. Actions, as you will see in more detail in Chapter 4 and later chapters, can trigger various events such as alert boxes or cause a field to display a final calculation or a button to reset fields in a form. However, some actions work better with certain form fields than others. For instance, applying an action to a radio button might give you some very select calculations, but if you want to add up those values, using check boxes or text fields would probably be a better option. If there are fields on the page, you can open and view their properties by clicking the Prepare Form tool and then in edit mode either rightclicking the field and choosing Properties from the menu or doubleclicking the field itself. The text fields in these examples contain no information on the Actions tab and are blank. However, as you’ll see shortly, other tabs within the field and other field types do contain information that will cause an event to occur. See Figure 2-1.

Figure 2-1.  The Actions tab in the Text Field Properties dialog box 60

Chapter 2

Introduction to Actions

Here you can see one of the many areas where you can add actions and a trigger, which I will discuss in more detail shortly.

 ating Forms Value Averaging and Sum: R Working with Text Fields Let’s look at several ways to use a combination of text boxes, radio buttons, and check boxes to do averaging and summing. Let’s say you want to create a survey to see if your clients have any concerns about your customer service or interactions. You can create a rating form that helps you determine where you need to improve. On page 1 of the PDF form TMC_Customer Survey_Start.pdf example shown in Figure 2-2, you can see how the form looks unformatted. However, in the final “End” form, the Rating fields in this survey are the text fields that are formatted with a setting of Number rather than None so that the client cannot enter in letters, only numbers.

61

Chapter 2

Introduction to Actions

Figure 2-2.  Example of a customer survey form and the form tools (text field, check box, and radio button) used on this page and other pages To ensure a client puts the correct information into a field, it is important to limit their options. You can change the formatting by selecting from the “Select format category” drop-down menu. Figure 2-3 provides an example of the formatting used on the Format tab of the Text Fields Properties dialog box. In this example, I right-clicked a text field I named “1 Sales Rep Helpfulness” and in the Format tab in the Select Format Category list set it from None to Number. By default, Decimal Places will be set to 2. However, if you need the numbers not to have decimals as in this example, set it to 0 instead. Otherwise, I left the other lists at the default settings Separator Style (1,234.56), Currency

62

Chapter 2

Introduction to Actions

Symbol (None), and Symbol Location (disabled), as well as the Negative Number Style options of “Show parentheses” and “Use red text” disabled. Refer to Figure 2-3.

Figure 2-3.  The formatting for each of the rating text fields on page 1 of the Customer Survey file 63

Chapter 2

Introduction to Actions

We’ll talk about this Format tab in more detail in Chapter 7. However, as you build the form on page 1, note that in the Text Fields Properties dialog box you can click or select the next text field in the column, format it to the same Number setting again, or on the last field in the column, for a variation set Decimal Places to 1–10. In this case, I left it at 2. Refer to Figure 2-4.

Figure 2-4.  The formatting for each of the text rating fields on page 1 of the Customer Survey file

The Validate Tab On page 1 in the rating text field example, you can limit the client’s options even further by setting a range of numbers in the “Field value is in range” field on the Validate tab. Now the client can only enter numbers that range from 1 to 5. If they enter a 6 or higher or 0 or lower, a warning will occur, as shown in Figure 2-5. 64

Chapter 2

Introduction to Actions

Figure 2-5.  The Validate tab of each of the text following fields on page 1 with the values set from 1-5 to limit the range input and warning if a number is entered out of range 65

Chapter 2

Introduction to Actions

The user must then click OK to the message and enter the correct number to proceed in the form. In this example, the Final Result field is set to no validation since the user cannot enter a number here as the resulting value may be higher than 5 and it is set to Read Only on the General tab. Refer to Figure 2-6.

Figure 2-6.  The Final Result field is set to no validation and read-only

66

Chapter 2

Introduction to Actions

If you inspect the Calculate tab for the Grand Total or Final Result field on page 1 of the project (and as in Figures 2-7 and 2-8), you can see how the field will receive data from other fields using the “Value is the ________ of the following fields,” selecting Average from the list, and then clicking the Pick button to choose various text fields that this field will gather information from.

Figure 2-7.  The Calculate tab for the final result

67

Chapter 2

Introduction to Actions

Figure 2-8.  The Field Selection dialog box In your own work, to access other fields and their data for this final field, click the Pick button to access field selection. Select only the fields you want to calculate. Note which field name is on the current page so you don’t get calculations from other fields on other pages by mistake. When you’re done, click OK. You can also select or deselect all fields. This will allow you to make your selections faster, rather than checking off or on all the fields one at a time. In this example I just wanted to calculate the first six fields in the column. Refer to Figure 2-5.

68

Chapter 2

Introduction to Actions

Tip  If you have trouble selecting the check box, you can highlight it and press the spacebar on your keyboard. This toggles the check box on or off. Remember that the Final Result text field is set to read-only on the General tab so that a client cannot alter the final result. Refer to Figure 2-6.

T he Calculate Tab for the Grand Total Using Sum As you progress though form calculations, rather than using an average (for example, 1,2,3,4,5,5 = 3.33), which is the average of all numbers, you may instead prefer to add up all the numbers to a collective total of 20. Different surveys may require different accumulative ratings. On the final form for reference called TMC_Customer Survey_End. pdf, if you go to page 2, the only difference between this form and the one on page 1 is that the Final Result value in the Calculate tab was changed to sum (+) and I used the rating text fields on that page to add up the calculation. Refer to Figure 2-9.

Figure 2-9.  The Calculate tab for the final result on page 2 69

Chapter 2

Introduction to Actions

Note  I selected fields only on page 2. If I needed fields from other pages to complete the calculation, such as on page 1 or 3, I would pick these fields as well. Form calculations can be on as many pages within the PDF document as required. In this example, those fields on page 2 can be identified with their name with _2 on the end. However, in your own projects, your text field names may be different than mine. Alternate Drop-Down Rating  If you skip past page 3 down to page 4 of this example in the “End” document, you can see how, with this same form, you can replace some of the rating text fields with drop-down lists to rate. While this method is similar to text fields, I find it a suitable alternative if you want your client to use very specific values. Also, it eliminates the need for the Format and Validate tabs on each drop-down because the values are already set. To set an export value for a drop-down list, you need to set the Export value for each menu item on the Options tab. I also enabled “Check spelling” and “Commit selected value immediately” so that the calculation would change when selected from the list. Refer to Figures 2-10 and 2-11.

70

Chapter 2

Introduction to Actions

Figure 2-10.  The Dropdown Properties dialog box for the selections on page 4 of the customer survey

71

Chapter 2

Introduction to Actions

Figure 2-11.  One of the drop-down fields extended on page 4 On page 4 you can see how by choosing a word that has a numeric value applied to it, the Final Result text field takes that information and adds or averages it to what is already calculated.

 um and Averaging Using Check Boxes or S Radio Buttons with Text Fields While text fields and drop-downs are useful for surveys on pages 1, 2, and 4, sometimes radio buttons and check boxes will do a more efficient job. Look at page 3 of the PDF file in your Start and End files, as shown in Figure 2-12. 72

Chapter 2

Introduction to Actions

Figure 2-12.  Page 3 of the customer survey using radio button and check boxes 73

Chapter 2

Introduction to Actions

Using Radio Buttons on Page 3 of the Project On the Options tab, the choices can be set to any number value (1, 2, 3, or even negative numbers if required). Figure 2-13 displays how this is entered in the dialog box.

Figure 2-13.  Radio Button Properties dialog box’s Options tab on page 3 of the customer survey

74

Chapter 2

Introduction to Actions

Radio buttons as mentioned in Chapter 1 can all be part of the same group, so their name must be the same to function as one group, but the radio button choice of each button can be different. Refer to Figures 2-13 and Figure 2-14.

Figure 2-14.  Radio Button Properties dialog box’s Options tab on page 3 of the customer survey However, to complete the calculation, you need to have at the end of the group row a hidden text field to accept the calculate field for that group, which you can set in the Calculate field with a sum. Refer to Figure 2-15 and Figure 2-16.

75

Chapter 2

Introduction to Actions

Figure 2-15.  Text Field Properties dialog box’s General and Calculate tabs with the radio group selected on page 3 of the customer survey

76

Chapter 2

Introduction to Actions

Figure 2-16.  How the group of buttons appears in the Prepare Form Preview fields on the right side Each radio group should have a hidden text field. In this case, there are six groups. Remember, to operate correctly, radio buttons must always be in groups of two or more. Refer to Figure 2-17.

77

Chapter 2

Introduction to Actions

Figure 2-17.  Radio button examples and hidden text fields with tab numbers on Those text fields are then used to calculate the sum of the radio groups in the Final Result_3 text field on the Calculate tab, by selecting the hidden text boxes. The final result field is also set to Read Only, as in Figure 2-18.

78

Chapter 2

Introduction to Actions

Figure 2-18.  Text Field Properties dialog box’s Calculate and General tabs on page 3 of the customer survey The Final Result text box is used to calculate the average rating of the other text hidden boxes linked to the radio button groups.

79

Chapter 2

Introduction to Actions

Note  With radio button calculations, rather than leaving them unchecked, you can set one in each group to “Button is checked by default” on the Options tab if you want to see numbers change automatically in the final text field. For instance, in this case an average may remain at 0 for a bit until more radio buttons are selected. You can also use the option of “Buttons with the same name and choice are selected in unison “ to select two or more radio buttons with the same value. However, keep in mind that may yield unexpected results and not add up correctly. Generally, in most situations radio buttons should operate independently, each with their own values, so keep that property unchecked. Refer to Figure 2-14.

Using Check Boxes on Page 3 of the Project Figure 2-19 shows how similar values can be entered into the Options tab of the Check Box Properties dialog box.

80

Chapter 2

Introduction to Actions

Figure 2-19.  The Options tab of the Check Box Properties dialog box on page 3 of the customer survey Check boxes can be used in a comparable way on the Options tab and given an export value of 1, 2, 3…or even negative numbers for a negative rating. In this example, you do not need any hidden text boxes, and the Final Result text field (read-only) can sum up the check boxes’ values. See Figure 2-20.

81

Chapter 2

Introduction to Actions

Figure 2-20.  An example of the Calculate tab with the check boxes selected on page 3 of the PDF and how the check boxes appear not grouped in the Prepare Form Preview Fields on the right-side fields list

Note  This text field also has custom validation script that we will discuss in more detail in Chapter 10.

Turning Check Boxes into Radio Buttons As we have seen in this example, the check boxes can operate independently and don’t need to be grouped.

82

Chapter 2

Introduction to Actions

However, check boxes can become radio buttons, and in certain situations you may prefer this method over the other when you want a square shape. To program a check box to appear as a radio button, you can do the following steps. Place two or more check box fields on your page. Refer to Figure 2-21.

Figure 2-21.  Adding check boxes to a page Now in the Check Box Properties dialog box, make sure to name the boxes exactly the same as on the General tab. When you do this, a # and number will be added to the end of the name automatically. You do not add this symbol yourself. However, they are now grouped and will operate as one unit if the export values in the Options tab are the same. Refer to Figure 2-22.

83

Chapter 2

Introduction to Actions

Figure 2-22.  Make sure the check box names are the same on the General tab and that the export values are the same on the Options tab However, to turn the check box into a radio button, you need to change the Export Value field of one of the check boxes. Now when you use the boxes, they will toggle on and off as you click one or the other. Optionally, you can set one to be checked by default. Refer to Figure 2-23.

84

Chapter 2

Introduction to Actions

Figure 2-23.  Set a different export value for one of the check boxes to turn them into radio buttons On your own, try this with number calculations and see how a simple calculation with a text field can be accomplished by changing the export value in the check box to a number instead. See my example in CheckBox_ RadioButton.pdf, and in the text field set the Calculate tab to “Value is the sum (+) of the following fields” and then pick the Check Box 1 group and make the text field read-only on the General tab. Refer to Figure 2-24 for Calculate tab settings.

Figure 2-24.  Set the Calculate tab for your text field 85

Chapter 2

Introduction to Actions

Tip  If you need to get closer to your check boxes or any form field, remember to use your navigation - and + icons. You can also use the Ctrl/Cmd+ or Ctrl/Cmd- shortcut as well as the View ➤ Zoom menu.

 asic Action Button Triggers for Reset B Buttons and Printing Buttons There are many basic actions that can be added to buttons, as you’ll see in Chapter 4 and later. However, for this lesson let’s focus on two that are used quite frequently in forms: the Reset and Print actions. Review page 1 in the TMC_Customer Survey_End.pdf file, if you need to follow along.

Reset Button If a client makes a mistake in several fields or wants to clear the entire form rather than highlight and press the Delete or Backspace key for each field, it is helpful to add a Clear or Reset button to your form. Figure 2-25 displays what this action looks like on the Actions tab for a reset button.

86

Chapter 2

Introduction to Actions

Figure 2-25.  Button properties on the Actions tab All fields or only the comments can be reset by a button; it’s your choice. Try this on your own form. 1. Make sure the select trigger is set to Mouse Up. 2. Select the action “Reset a Form” from the Select Action menu list. Refer to Figure 2-26.

87

Chapter 2

Introduction to Actions

Figure 2-26.  Select the action of “Reset a form” 3. Click the Add button to add the action. For a new action, this will bring you to the Reset a Form dialog box. Refer to Figure 2-27 and Figure 2-28.

Figure 2-27.  Add the action to the Actions tab 4. Or, if you have the reset action selected, click the Edit button at the bottom of the properties box to open the Reset a Form dialog box to select which fields you would like to reset, as in Figure 2-28.

88

Chapter 2

Introduction to Actions

Figure 2-28.  Edit the actions in the Reset a Form dialog box 5. In this example, I chose Deselect All, chose just the Comments field, and then clicked OK and closed the properties dialog box. Refer to Figure 2-29.

89

Chapter 2

Introduction to Actions

Figure 2-29.  The Reset a Form options on the Actions tab

Note  The label name for the Button field is on the Options tab.

Print Form Button Likewise, you can also create a Print button, as seen on page 1. In the Button Properties dialog box, follow the same steps as with the reset button, but this time, from the Select Action list, you can choose “Execute a menu item” and click Add. Refer to Figure 2-30.

90

Chapter 2

Introduction to Actions

Figure 2-30.  Print Form options on the Actions tab From the Menu Item dialog box, select the File ➤ Print action if you want to create a Print button for the whole document. Then click OK. Refer to Figure 2-31 and to page 1 of the project’s “End” PDF file to review this action.

Figure 2-31.  The File ➤ Print options on the Actions tab 91

Chapter 2

Introduction to Actions

This will open the Print dialog box when you click the button. You can edit or delete this action if required. However, if you need only a specific page or pages to print in a range, you need to add JavaScript instead. To see a preview of this, refer to pages 2 and 4 of the “End” PDF file and to Figure 2-32. I’ll discuss this more in later chapters. Though script placement can effect whether the document will print successfully. In this example the script on page 2 allows us to print but if the print Action script is placed on the final page the document will not print and will show an error.

92

Chapter 2

Introduction to Actions

Figure 2-32.  Adding JavaScript on the Actions tab and closing the form When you are done previewing and editing the form, click the Close button in the upper-right corner of the preview to close the Prepare Form tool.

93

Chapter 2

Introduction to Actions

Summary As you saw in this chapter, you can use the Prepare Form tool and its respective properties in a variety of ways to create customer rating surveys to suit your needs. By looking through the tabs, you can also see that many of the form fields have similar properties, while others have properties that relate only to that specific field. However, as you saw with the radio buttons and check boxes, there is a way to make one behave like the other for a specific project. You are now starting to add actions to buttons as well. As you progress through the lessons, you will discover how knowing which types of fields and properties to use will be important as the forms become more complex.

94

CHAPTER 3

Creating a QR Code Custom Stamp Chapter Goal: In this chapter, you’ll create a custom QR Code stamp with the Adobe Acrobat Stamp tool. You’ve probably opened and viewed a PDF file that contains stamps and comments as well as customer changes and approvals. The application that made viewing those comments possible was most likely Adobe Acrobat Reader or Acrobat Pro. For many computer users, Reader has become the industry standard simply because it is a freeware program that anyone can download for the macOS or Windows platforms. When you are reviewing the file with your client, Acrobat Pro allows you to view and add comments to a PDF document. As mentioned in Chapter 1, Acrobat Pro also allows you to create barcodes and QR codes with the Prepare Form tool. However, the information generated in the barcode and QR code applies only to the surrounding form fields and not to specific text elsewhere in the document (see Figure 3-1). Currently, with the Comment tool, you cannot generate a custom QR code that you may want to use as a comment or stamp, so this chapter shows you a way to get around this situation.

© Jennifer Harder 2023 J. Harder, Enhancing Adobe Acrobat Forms with JavaScript, https://doi.org/10.1007/978-1-4842-9470-3_3

95

Chapter 3

Creating a QR Code Custom Stamp

Figure 3-1.  The Barcode Field Properties dialog box with an example of a created QR code from the Options tab’s Symbology list

Note  If you want to work along in this lesson or review the final result, download the Chapter 3 files from the link mentioned in the introduction. You will find the original Adobe InDesign, QR images, and PDF files if you would like to edit them. See “QR Code Creation” later in the chapter for more details on this topic.

96

Chapter 3

Creating a QR Code Custom Stamp

Remember that to view the properties of a field, you must select the Prepare Form tool. Only then can you right-click or double-click a field to review its properties.

Customizing Your QR Code Stamp It’s become popular to place a QR code on business cards, résumés, and newsletters; these codes can be read by smartphones. However, Acrobat only allows you to create a QR code that applies to forms. For your résumé or letterhead, you might want a QR code to contain the URL of your company website or just some text. The solution is to build your own custom QR code stamp that you can place in your online PDFs for clients to view. The following exercise will show you how.

Note  If you plan to use the QR code for professional print material, always place it into the original document (MS Word or Adobe InDesign Creative Cloud 2014 or later) rather than using the Acrobat Stamp tool as I will demonstrate next. While the stamp image will print fine on your home computer, it may not print when sent to some professional printers depending on if the layout requires altering. See details on how to do this in MS Word in the “Final Thoughts” section at the end of the chapter. You can also review the file QRCode_ Resume_Chapter3_End.pdf as a reference in this chapter.

97

Chapter 3

Creating a QR Code Custom Stamp

QR Code Creation Either create a QR code using InDesign CC 2014 or later, design software that allows you to generate a QR code, or ask a graphic designer in your company to create one for you. To work with the image, use a program like Adobe Photoshop to create a new document that is grayscale, is 200px width by 200px height, has a resolution of 72 pixels/inch, and is 8-bit. The graphic can also have a color mode of RGB if you are making a colorful stamp in InDesign. Refer to the “Summary” section for a link to steps on generating a QR code in InDesign. Select Edit ➤ Copy from InDesign and select Edit ➤ Paste in Photoshop and use the application to scale your code on the canvas if it comes in too small or too large. Commit to the change by clicking the check mark in the Options panel. Make sure to use the Layers Panel menu to flatten the Image; then save the file as a JPEG on your computer and click OK. Afterward, test it with your smartphone’s Camera app to make sure it works correctly. See Figure 3-2.

98

Chapter 3

Creating a QR Code Custom Stamp

Figure 3-2.  A generated QR code is added from InDesign to Photoshop and scaled and saved for use as an Acrobat Stamp 99

Chapter 3

Creating a QR Code Custom Stamp

Open the PDF file in which you plan to add the QR code in Acrobat Reader or Acrobat Pro via File ➤ Open. Refer to Figure 3-3.

Figure 3-3.  The File menu’s Open item Locate and select the PDF file you want to open. Click the Stamp button in the Tools menu in the Share & Review section. Refer to Figure 3-4.

Figure 3-4.  The Stamp tool Select the Custom Stamps option. Choose Create from the drop-down. Refer to Figure 3-5.

Figure 3-5.  The Stamp Tool Cmenu

100

Chapter 3

Creating a QR Code Custom Stamp

Create the custom stamp. When you choose this option, you will be presented with the Select Image for Custom Stamp dialog box. Click the Browse button to locate your file. Refer to Figure 3-6.

Figure 3-6.  The Select Image for Custom Stamp dialog box In Acrobat Pro, you can browse and use several different file formats including JPEG, TIFF, GIF, and PNG. Review the All Supported formats list to see what your options are. Refer to Figure 3-7.

Figure 3-7.  Browse for the QR code and select it

101

Chapter 3

Creating a QR Code Custom Stamp

In this case, choose a JPEG graphic of the QR code that you or your graphic designer has already created. You can use my file called Apress_ QRCode.jpg if you do not have a file. Click the Open button and you will be returned to the previous dialog box with the file link now shown. Refer to Figure 3-8.

Figure 3-8.  The Select Image for Custom Stamp dialog box with a QR code visible If you like how the image looks, click OK. Otherwise, browse for another image. You may need to make minor adjustments in a program like Photoshop for spacing needs to reduce or increase the size. If you do, make sure to keep the shape square and don’t distort the QR code. For example, in newer versions of Photoshop, holding down the Shift key while scaling can cause distortion. For now, use my image and click OK to proceed to the next dialog box.

102

Chapter 3

Creating a QR Code Custom Stamp

Before you can use the custom stamp, Acrobat wants you to choose a folder category for your stamp and give it a name. You can either create a new folder by typing a name in or choose from current folders that are available in the Category drop-down list. Refer here to Figure 3-9.

Figure 3-9.  The Create Custom Stamp dialog box You have the option to downsample the stamp to reduce the file size. In the case of the QR code, I might uncheck this to preserve the quality. In this case, the file is only about 45KB, which is not large. When you are done, click OK to add that stamp to your collection.

103

Chapter 3

Creating a QR Code Custom Stamp

Note The Help Button link can guide you if you have additional questions about stamp creation and will take you to the following page: https://helpx.adobe.com/acrobat/using/adding-stamppdf.html#create_a_custom_stamp

Using the Stamp Tool The stamp is created. While still in your Stamp tool, you can go to your file folder in the Stamp drop-down menu and choose your new custom stamp. Refer to Figure 3-10.

Figure 3-10.  Created QR code stamp in the Stamp menu At this point, a dialog box may appear that will request an initial identity setup. This is so the client will know who made this approval stamp for security reasons. You do not have to fill in all the boxes. When you’re done, click the Complete button. You should do this identity setup only once for your new stamp. If you do not see this box, it may mean that you or someone else has already set this area up. You can check this under Edit ➤ Preferences ➤ Categories: Identity and adjust your information there. Refer to Figure 3-11 if you need to check your settings.

104

Chapter 3

Creating a QR Code Custom Stamp

Figure 3-11.  Identity setup for new stamps as found in Preferences The mouse cursor will now turn into the stamp. You can move it around on the page until you find where you want to place the stamp. Click the mouse button, and the stamp will be set. If you don’t like where it is set, you can move it around. The mouse turns into four arrows. If you hold down the mouse icon on the stamp, you can use the bounding box handles to move the stamp around, rotate (upper circle) it, or scale it. Use Edit ➤ Undo or Ctrl/Cmd+Z to undo a scaling or rotation. 105

Chapter 3

Creating a QR Code Custom Stamp

If for some reason you need to delete the stamp later, while in the Stamp tool, go to the Custom Stamps ➤ Manage dialog box, and click Delete to remove the selected stamp from your custom list. Refer to Figure 3-12.

Figure 3-12.  The Stamp Tool menu and the Manage Custom Stamps dialog box

Note There is no undo setting for deleting a custom stamp from this dialog box. If you delete it by mistake, click OK and then add the custom stamp again as well as the folder if it was removed. This dialog box will also allow you to create and edit a currently selected stamp category. Refer to Figure 3-9. The Stamps Palette subtool can also help you access your custom stamp. Refer to Figure 3-12.

106

Chapter 3

Creating a QR Code Custom Stamp

Custom QR stamps, as in Figure 3-13, can also have comments attached. You can attach a comment in the Comment tool section.

Figure 3-13.  The Comment tool with Add Stamp subtool Now your comments list has a stamp comment. Here you can add further information about the stamp by double-clicking in the comment to add text to a comment and then clicking Post. If you need to delete the QR code stamp on the page, just select it and press the Delete button on the keyboard or right-click and select Delete from a pop-up list. You can also use Ctrl/Cmd+Z if you need to undo your deletion. You can add this QR code stamp to as many places in the document as required. When you’re done, click the Close button to exit the Stamp or Comment tool. Refer to Figure 3-14.

Figure 3-14.  Close your current tool to exit

107

Chapter 3

Creating a QR Code Custom Stamp

Tip The Comment Tool also has an Add Stamp subtool with a dropdown menu that will allow you to access your custom stamp rather than entering the Stamp tool again. Refer to Figure 3-13. Then save the file and email the file to a client or post it on your website. If you need to print the document (File ➤ Print, in the dialog box under Comments & Forms choose either the Document and Stamps or Document and Markups option in the Print dialog box. If you just choose the Document or “Form fields only” option, the QR code stamp will not print. Refer to Figure 3-15.

Figure 3-15.  Print settings for stamps. Choosing Document and Stamps will ensure that the QR code stamp prints

F inal Thoughts: QR Code for  Professional Printing If you plan to send your résumé or a newsletter to a company and you want to ensure that the QR code will print regardless of the print document settings, I recommend typing your résumé/newsletter in a program like

108

Chapter 3

Creating a QR Code Custom Stamp

MS Word and then choosing the location where you want to place your QR code. Then in the menu, choose Insert ➤ Picture ➤ This Device and on your computer locate, select, and insert the file. Refer to Figure 3-16.

Figure 3-16.  Insert an image in MS Word Locate your JPEG image and then click the Insert button. The image will be inserted. Finally, you would save the file and print your file as a PDF or use the Acrobat tab mentioned in Chapter 1. This will ensure that the QR code is embedded in the document and will print with the rest of your résumé.

109

Chapter 3

Creating a QR Code Custom Stamp

Summary In this chapter, you learned how you can turn a QR code into a custom stamp that you can use in a form for any PDF document. The stamp can also be modified and scaled, and a comment can be added. Creating the QR code in this manner, rather than just as a form field, allows for a wider range of possibilities. For more information about how to create a QR code in Adobe InDesign, visit https://helpx.adobe.com/indesign/using/generateqr-code.html.

110

CHAPTER 4

Buttons, Navigation, Form, and Nonform Actions Chapter Goal: You will learn about actions you can create for buttons that are for forms and nonform activities as well as improving navigation within the document with basic actions. In Chapter 2, you saw a few simple examples of actions you could create with buttons. Now you will focus on a few more. You’ll do the following in this chapter: •

Reviewing the Actions tab’s properties in various fields and nonform items

•

Looking at built-in triggers and actions that require no coding

•

Applying what you discover to buttons for page navigation

•

Using button icons rather than just text

•

Understanding how a button can become a help icon to show or hide information in an order form

© Jennifer Harder 2023 J. Harder, Enhancing Adobe Acrobat Forms with JavaScript, https://doi.org/10.1007/978-1-4842-9470-3_4

111

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

•

Understanding how a check box can show or hide information in combination with a reset button

•

Working with PDF Layers Bookmarks and Buttons

Note  If you want to work along in this lesson or review the final result, download the Chapter 4 files from the link in the introduction. The file with the label “Start” is the file without the code, and the file with the label “End” is the final result. You will also find folders with original MS Word, PDF, and related InDesign/Illustrator files if you would like to edit them, and you will find a folder containing the original images of the button icons if you would like to add them to your own PDF forms. To view the properties of a field, you must select the Prepare Form tool. Only then can you right-click or double-click a field to review its properties. If you are creating your form from an original PDF that contains no form fields, refer to the “Forms Review” section in Chapter 1.

Creating a Button Icon Not all buttons have to be just text; you can also have text and an image or just an image that you created in a program like Adobe Photoshop or GIMP. As in the QR code stamp example in Chapter 3, the file can be in many formats including JPEG, GIF, or PNG. In this example, you can refer to the “Start” and “End” PDF files for Newsletter_1_Navigation. On page 1 of the End file, look at the Next Page button for reference to its properties. Currently, in the Options tab Layout section, it is set to “Label only,” so only a label name can be typed into the Label field. The icon and advanced areas are therefore disabled, though 112

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

you can alter the Behavior setting from Invert to None, Push, or Outline. We will discuss how the Behavior setting affects the icon and label states later in the chapter. Refer to Figure 4-1.

Figure 4-1.  The Options tab with the Choose Icon button disabled 113

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

However, if in the Options tab you change the layout to another option that contains the word Icon, then you can access the Choose Icon button to locate an image using the Select Image dialog box. After you choose an image, the icon will display with the properties. You will see an example of the TMC_Order Form “End” PDF later in the chapter. Refer to Figure 4-2.

Figure 4-2.  The Options tab with the Choose Icon button enabled and the Select Image dialog box 114

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

The Layout list allows you to choose the layout setting of the icon only or display the icon with a label if you want to use the icon in combination with text. To review, the layout options are as follows: •

Label only (this setting will not allow you to add an icon)

•

Icon only (you cannot add a label)

•

Icon top, label bottom

•

Label top, icon bottom

•

Icon left, label right

•

Label left, icon right

•

Label over icon

After an icon layout is chosen, you can click the Advanced button. Clicking the Advanced button will open the Icon Placement dialog box, where you can adjust the placement of the icon precisely inside the button. You can set When to Scale (Always, Never, Icon is too big, Icon is too small), Scale (Proportionally or Non-Proportionally), and Fit to bounds. You can also move the two sliders to adjust where the icon should sit and reset everything to original settings (refer to Figure 4-3). Click OK to commit the settings, or click Cancel to exit without saving the changes.

115

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-3.  Clicking the Advanced button in the Options tab opens the Icon Placement dialog box

Example of a Button as a Label Only Figure 4-4 shows an example of a button with only a label applied, as found in the Newsletter 1 Navigation “End” file on page 1. This button’s label says “Next Page” because you want the user to go to the next page when clicking the button. The label is a helpful hint so that the user will know what will happen when the button is clicked. These types of buttons can be used in any document that contains three or more pages. 116

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-4.  Label-only button

Note  The current state is Up, based on the behavior of the button, which is Invert, or the color inverts when clicked. None creates no color change, and Outline inverts only the edge of the button. These have a state of Up. A behavior such as Push will give other options of states such as Up, Down, and Rollover; instead of one icon or label, you could now add three. This would cause the button to change as you activated each state. See Figure 4-5 for some of the options. While the label and icon will change, you will not be able to set a different fill color for each state using the Appearance tab.

117

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-5.  Example of various behaviors and states applied to a button

118

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Example of a Button Combination of Icon Only Figure 4-6 shows an example of a three-button group that has an icon image and some actions applied to them. We will look at this more closely later in the chapter. However, without actions, these buttons would function independently and not interact with each other.

Figure 4-6.  Example button group with different show and hide fields applied to each button in the TMC Order Form End PDF file If you enter each of the button’s properties, you will see, as in Figure 4-7, various hide and show actions set on the Actions tab, which we will look at later in this chapter in detail.

119

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-7.  Example button group with show and hide fields applied

120

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

All actions in the Actions tab, once selected, can be as follows: •

Added using the Add button

•

Rearranged using the Up and Down buttons

•

Edited using the Edit button

•

Deleted using the Delete button

Note  With the Show/Hide action, you need to apply the action to each field one at a time. Some actions, such as Reset, allow you to apply the actions to more than one field or collectively. Refer to Figure 2-28 in Chapter 2.

Nonform Properties Actions The following sections take a quick look at the kinds of properties you can apply actions to that are not part of forms.

Pages For this example, refer to the Newsletter 1 Navigation PDF End file or use the Start file for practice; see Figure 4-8.

121

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-8.  Accessing the page thumbnails Under View ➤ Show/Hide ➤ Navigation Panes ➤ Page Thumbnails, you will find on the left side of Acrobat all the page thumbnails of your current document. Select one of the pages such as page 1 in the Thumbnail section, and from the Options drop-down choose Page Properties at the bottom of the options list to access this dialog box. Then click the Actions tab (refer to Figure 4-9).

122

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-9.  The Page Properties option on the Actions tab Pages can have actions applied for improved navigation. The trigger, which we will look at in more detail later for forms, can be upon page open or page close. However, not all selected actions, which we will review shortly, may be compatible with page properties, so you may want to take some time to plan what type of action is appropriate, such as executing the Edit ➤ Find dialog box when you arrive on that page or playing a sound. 123

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Remember that you can access this area on the left side of Acrobat in the Page Thumbnail section. Alternately, you can right-click a thumbnail when no other menu items are active and choose Page Properties from the list. Refer to Figure 4-10.

Figure 4-10.  The Page Properties option on the Actions tab with a possible action applied for that specific select page Once you have chosen an action, you can then click OK to confirm or exit to cancel. Refer to Figure 4-9.

Bookmarks For this example, refer to the Newsletter 1 Navigation End PDF file. Under View ➤ Show/Hide ➤ Navigation Panes ➤ Bookmarks, you will find on the left side of Acrobat all the bookmarks of your current document (refer to Figure 4-11).

124

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-11.  Bookmarks found in the Newsletter file in the Navigation Panes area In Acrobat Pro, bookmarks are easily created when you highlight text in a document and then click the Add a New Bookmark icon. In this example, select one of the bookmarks and from the Options menu at the bottom of the list choose Properties. This will allow you to add or view the actions for the bookmark (refer to Figure 4-12) when you click the Actions tab.

125

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-12.  Bookmark properties on the Actions tab Remember that you can access this area on the left side of Acrobat in the Bookmark Thumbnail section. Alternatively, you can right-click a bookmark and choose Properties from the list. In this example, the Add action area shows that the bookmark has no trigger. It is assumed that clicking in the bookmark is the trigger. And the bookmark’s main purpose is to navigate to a page. In this case, when the bookmark was created, it was set to a default select action of “Go to a page in this document” for page 1. The Zoom level was set to Fit Page using the dialog box. Select the action and click the Edit button to see the options and edit, if required, the Zoom options. Refer to Figure 4-13. 126

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-13.  “Go to a page in this document” dialog box Alternatively, you can set a named destination. You will find an example of this in the file on page 3, and it can be selected by clicking the Browse button. Then select one and click OK to confirm. Look in the Destinations area on the left if you need to locate this option. Select View ➤ Show/Hide ➤ Navigation Panes ➤ Destinations. For details, refer to Figure 4-13 and Figure 4-14.

127

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-14.  A named destination in the thumbnail area with a page set Destinations can be created and named like bookmarks. When some text is highlighted, you click the Create New Destination button. On their own they contain no actions or properties, so they must be used in conjunction with a bookmark for better navigation.

Web and Custom Hyperlinks For this example, refer to the Newsletter 1 Navigation PDF End PDF file. You can access this area under Tools ➤ Edit PDF ➤ Link ➤ Add/Edit Web or Document Link. If a highlighted link already exists on a specific page, it will appear with a box around it. If not, you can select this option from the menu and then drag to highlight a selection of text to apply a hyperlink to. For example, try this in the “Start” file on page 4 and highlight the name of the company while using this tool and setting (refer to Figure 4-15).

128

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-15.  Accessing link properties when a custom link is chosen

129

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

In the Create Link dialog box, you can then choose a link appearance so that the user can see the link’s Link Type, Highlight Style, Line Thickness, Line Style, and Color settings applied. Then set a link action of one of these: Go to page view, Open a file, Open a web page, or Custom Link. Then click Next (see Figure 4-15). Based on the action chosen, you will be presented with different choices in the link dialog box. In the case of a custom link, you will be taken to Link Properties, where you can select a custom action from the menu on the Actions tab that will trigger when you click the link. Refer to Figure 4-16.

130

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-16.  Accessing link actions and properties on the Actions tab

131

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

In this case, I set a custom link to execute a menu item, clicked Add to display the attachments’ thumbnails (View ➤ Show/Hide ➤ Navigation Panes ➤ Attachments), and clicked OK. The action is now applied. Refer to Figure 4-17.

Figure 4-17.  Accessing link actions and properties on the Actions tab Or choose an action like “Open a web link,” as shown on page 1. Refer to Figure 4-17. If I needed to edit this custom link while in the Edit PDF Tool on the Add/Edit Link option, I could then right-click the link, choose Properties from the list, select the action to edit, and then delete the old action. Refer to Figure 4-17 and Figure 4-18.

132

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-18.  Accessing link actions and properties by right-clicking the link You can then on the upper-right side click the Close button to exit the Edit PDF tool and save the document. Alternately, outside of the Edit PDF tool, you can select the link by right-clicking it and choosing Edit Link from the list (refer to Figure 4-19).

Figure 4-19.  Accessing the link properties on the Actions tab outside of the Edit PDF tool Alternatively, you could apply this same custom hyperlink to a graphic that would link to the attachment thumbnails. In this case, I also added a comment sticky note for additional clarification. Refer to Figure 4-20.

133

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-20.  Adding a Custom Hyperlink action to a graphic so an attachment can be located within the PDF file

134

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Tip  You can use the Help button in the Create Link dialog box if you want more clarification on certain link actions (https://helpx. adobe.com/acrobat/using/links-attachments-pdfs. html). Refer to Figure 4-15.

Rich Media Nonform Navigation Buttons For this example, refer to the Floor Plan Layout “End” PDF file. Buttons can be added either via the Prepare Form tool or via the Rich Media tool (refer to Figure 4-21).

135

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-21.  Rich Media tool’s Button Properties dialog box on the Actions tab 136

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Nonform button actions can be used for video media, 3D models, navigation, or later for forms while working with the Rich Media tool. You can select a button with the Select object tool and then right-click the button to access the properties. However, after you close the file and open it again, to access the buttons properties, you will need to go into the Prepare Form tool to edit the button actions because you may alter or lose access after exiting the Rich Media tool, especially if you have later added other form elements. The button properties for rich media are the same as those for forms.

Layers Basic Actions For this example, refer to the Floor Plan Layout PDF file. Under View ➤ Show/Hide ➤ Navigation Panes ➤ Layers, you will find on the left side of Acrobat all the layers of your current document (refer to Figure 4-22).

Figure 4-22.  Access to the layers in the Navigation Panes area To access the layer properties, you can select a layer, and then from the Options menu, choose Layer Properties from the bottom of the list. Alternately, you can right-click a layer and choose Properties (refer to Figure 4-23). 137

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-23.  Layer properties as seen in the Floor Plan example when you select a layer and either choose from the Options menu or right-click the layer in the navigation pane 138

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Layer actions, compared to some button navigation setups, can be a bit more complex to build. I recommend using a program like InDesign to create your initial layer layout and export it as an interactive PDF, as you can see in the Creator Info area. However, here are some tips to get you started with the Layer Properties dialog box: •

Layer actions have some similarities to Acrobat page transitions.

•

Layers have a name and have an intent of view or reference.

•

Layers can have a default state of on or off.

•

They can be locked or unlocked.

•

You can set a Layers Initial State for the following:

•

Visibility (On, Never, or Always Visible)

•

Print (When Visible, Never, or Always)

•

Export (When Visible, Never, or Always)

•

Layers are good for overlays to show, for example, optional layouts of a room or floor. The layers can be separated and exported from a program such as Adobe InDesign when you create an interactive PDF.

•

Unlike other actions, they can be tricky to set up and are best kept to one or two layers.

Later I will show how you can add some buttons to make the layer more interactive in the PDF to show and hide layer visibility. As you can see, most of these nonform properties can be accessed in the Navigation Panes/thumbnail area in Acrobat. The same is true for layers.

139

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

 ther Nonform Actions That Can Affect Sticky O Note or Markup Tools Indirectly One final thing I will point out here and later in Chapter 8 with Time Stamps is that nonform or form buttons, when they are programed with custom JavaScript, can be set to alter the appearance of a placed comment or stamp. However, while stamps, comments, markup tools, and measurements do have properties that you can access when you right-click them, they do not have an Actions tab. So, by themselves no action can be applied without some indirect trigger applied first to a button or form field.

Triggers for Actions Before you choose an action from the Actions tab, it is important to select a trigger. Trigger + Select Action = Result You Want The most common trigger to use in digital forms is Mouse Up, as shown in Figure 4-24.

Figure 4-24.  Various action triggers that can be selected

140

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

The following describes this and a few other actions you may encounter: Mouse Up: When the mouse button is released after a click. This is the most common button trigger because it gives the user one last chance to drag the pointer off the button and not activate the action. Mouse Down: When the mouse button is clicked (without being released). In most cases, Mouse Up is the preferred trigger as down does not give the user any time to change their mind. While it might not be as apparent with a button with a check box, this trigger might be too fast. Mouse Enter: When the pointer enters the field or play area. Mouse Exit: When the pointer exits the field or play area. On Receive Focus (media clips only): When the link area receives focus, either through a mouse action or tabbing. This is also called On Focus. On Lose Focus (media clips only): When the focus moves to a different link area. This is also called On Blur. Bookmarks and hyperlinks are exceptions; they do not have an available trigger. It is assumed that you will click the link with your mouse or finger and that the action of going to that page or URL will be executed. However, pages as mentioned do have a select trigger of upon page open or page close.

141

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Refer to the following Adobe page for more details on additional media clip triggers: https://helpx.adobe.com/acrobat/using/applyingactions-scripts-pdfs.html.

Choose an Action That Requires No Code There are many actions you can choose from. As you can see in Figure 4-25, once you choose a trigger, you can set it to execute a selected action when you click the Add button. Upon exiting the dialog box, the action applied to the button will allow you to move to another page or print all the pages in the document, for example.

Figure 4-25.  Various actions that can be selected 142

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

You will look at some specific actions shortly. However, take a moment to review some of the select actions that are available, as listed here: Execute a menu item: Executes a specified menu command as the action. There are at least 50 menu item options in this area. Go to a 3D/multimedia view: Jumps to the specified 3D view. These 3D annotation views must already be present in the document. This is more for working with nonform buttons. Go to a page view: Jumps to the specified destination in the current document. Use the scroll bars, mouse, and zoom tools to select the target view and then press the set link button in the dialog box to create the link destination. Import form data: Brings in form data from another file and places it in the active form. This select file is in FDF format. Multimedia operation (Acrobat 9 and later): Executes a specified action for a multimedia object or annotation in the file (such as playing a sound file). The multimedia object must be added to the file before you can specify an action for it in the dialog box. Open a file: Launches and opens a linked file that is in the same folder as the PDF. If you are distributing a PDF file with a link to another file, the reader needs the native application of that linked file to open it successfully. You may need to add information on opening preferences for the target file such as in the form of a comment. 143

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Open a web link: Jumps to the specified URL destination on the Internet. You can use HTTP, HTTPS, FTP, and mailto protocols to define your link. Play a sound: Plays the specified sound file, in WAV or AIFF format. The sound is embedded into the PDF document in a cross-platform format. Play media (Acrobat 5, Acrobat 6, and later compatible): Plays the specified QuickTime or AVI movie that was created as Acrobat 5 or 6 compatible. The specified movie must be embedded in a PDF document. If no media of this kind is present in the document, then the action will not be created. Read an article: Follows an article thread or box in the active document. They are created with the Edit PDF tool. An article must be present in the left pane’s article thumbnails for this action to be executed. Select View ➤ Show/Hide ➤ Navigation Panes ➤ Articles. Refer to Figure 4-26.

144

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-26.  Select Article dialog box and article thumbnail present in PDF Reset a form: Clears previously entered data in a form. You can control the fields that are reset with the Select Fields to Reset dialog box, as shown in Chapter 2. Run a JavaScript: Runs the specified JavaScript. This requires JavaScript to do some custom action that is entered into the JavaScript Editor.

145

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Set layer visibility: Determines which layer settings are active. Before you add this action, specify the appropriate layer settings for a current state. This works with the layer properties, as we will see later in the chapter. Show/hide a field: Toggles between showing and hiding a field in a PDF document. This option is especially useful in form fields. For example, if you want an object to pop up whenever the pointer is over a button, you can set an action that shows a field on the Mouse Enter trigger and hides a field on Mouse Exit. Note in this case two actions will be present on your Actions tab. You will then need to move the actions up or down in the list as well as edit them one at a time if you need to make corrections. Refer to Figure 4-27.

Figure 4-27.  Example of setting the order for show and hide a field actions Submit a form: Sends the form data to the specified URL or email. You may need someone in your IT department to help you test this first and choose the correct export format, field selection, and date options (refer to Figure 4-28). 146

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-28.  Submit Form Selections dialog box It is important to note, in the case of the first option “Execute a menu item,” the additional 50 or more possible variations to the action will appear when the Add button is clicked. These include assorted options for page and document navigation. Included is View ➤ Page Navigation ➤ Go To page, which is a similar setting for bookmarks. Menu items fall into several categories, mostly found in the main menu: File, Edit, View, Bookmarks, Miscellaneous, and Tools. Figures 4-29 and 4-30 illustrate what options are available.

147

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-29.  An example of an action added to the Actions tab from the selected action “Execute a menu item”

Figure 4-30.  The many different menu options that are available 148

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

As mentioned, on the Actions tab, more than one action can be added to a trigger. as Also, separate triggers with different actions for each field can be added; just select them and click the Add button. One example is to show and hide items on a form; refer to Figure 4-27 and Figure 4-31, depending on the choice of field. A field or button with these actions applied shows some fields and then hides others.

Figure 4-31.  Multiple triggers and actions applied to one field

149

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Newsletter Navigation with Buttons Open the Newsletter 1 Navigation End file in the Chapter 4 folder. Test the buttons. You can use labels with or without images to enhance the navigation experience. See Figure 4-32 for the buttons with an example of a navigation action applied.

Figure 4-32.  Applying an action to a button to navigate to another page (see pages 1–3 of the Newsletter 1 Navigation End file) In your own project, choose an action of “Execute a menu item” and apply one of the following types of navigation to your button: 150

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

View ➤ Page Navigation ➤ •

First Page

•

Previous Page

•

Next Page

•

Last Page

•

Go to Page

•

Previous View

•

Next View

As shown in Figure 4-30, other types of viewing include the following: •

Page Display

•

Zoom

•

Portfolio

•

Show/Hide of Navigation Panes

•

Full Screen Mode

The Next Page button and the right-pointing arrow icon button in the newsletter document have had the action View ➤ Page Navigation ➤ Next Page applied. The Previous Page button and the left-pointing arrow button have had the action View ➤ Page Navigation ➤ Previous Page applied. Refer to Figure 4-32. To navigate to a file in the same folder or alternatively an attachment within the PDF document, see Figure 4-33 with the Go to Form button on page 4 and view the actions applied.

151

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-33.  Navigate to a file somewhere on your hard drive or within the PDF file in the Attachments pane. Refer to page 4 of the Newsletter 1 Navigation End PDF 152

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

With the Go to Form button created, you could do one of the following select actions to open the form: •

Open a file.

•

Execute View ➤ Show/Hide ➤ Navigation Pane ➤ Attachments.

As mentioned earlier, similar navigation can be a hyperlink or even a bookmark. In the Newsletter 1 Navigation End PDF, you can alter the URL link on page 1 with the text “New finds in China.” This link can go to a website, or if the text is highlighted, it can be added as a new bookmark that will anchor or jump to that page when clicked. However, if your bookmark name is no longer the same as the section title because you altered the link on the Properties Actions tab, you can rename the bookmark, as you can see in Figure 4-34, by double-clicking it. The bookmark has now been renamed and matches the URL or section it is jumping to.

Figure 4-34.  A bookmark can be used as a link to a section within a book or to navigate to a URL

153

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

F orm Navigation with a Button as a Helpful Hint If a client is unsure what to enter in a field, a hint can be created to give information. Open the TMC Order Form “End” PDF example to see how this is done. This example uses “Show/hide a field” to accomplish this. Refer to the button next to the text Customer Order Code and to Figure 4-35.

Figure 4-35.  Show and hide example with the Actions tab 154

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Here is a breakdown of each of the buttons: •

Info button: Show-Close, Show-Info Window, Hide-­ Info (Figure 4-36).

Figure 4-36.  The Info button is visible at first glance while other buttons are set to hide

155

Chapter 4

•

Buttons, Navigation, Form, and Nonform Actions

Close button: Hide-Close, Hide-Info Window, Show-­ Info (Figure 4-37).

Figure 4-37.  The Close button appears on top of the Info Window button

156

Chapter 4

•

Buttons, Navigation, Form, and Nonform Actions

Info Window button: No actions applied. Leave the Actions tab blank and the Close button visible on top (Figure 4-38).

Figure 4-38.  The Info Window button appears below the Close button

Adding a Comb of Characters A comb of characters spreads the user-entered text evenly across the width of the text field. If a border color is specified on the Appearance tab, each character entered in the field is separated by lines of that color. This option is available only when no other check box is selected on the Options tab; refer to Figure 4-39.

Figure 4-39.  Without and with a comb of characters

157

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Note  When entering a code, it can be helpful to add a comb of characters properties so that the client knows they have entered the correct number of letters or numbers. Just remember it is one field, so you cannot tab between parts of the comb.

Before Comb and After Comb Figure 4-40 shows how a text field on the Options tab appears before you apply the comb of characters. When you uncheck all other options, only then will the comb of characters be available to alter how many characters will be in it. you can specify a number between 1 and 999.

158

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-40.  Adding the comb of characters to the text field on the Options tab 159

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

So that the comb of characters displays correctly, go to the Appearance tab and add a border color, line thickness, and line style; refer to Figure 4-41.

Figure 4-41.  Adjusting the appearance of the comb on the Appearance tab You can also adjust the text options if you feel a certain font size and color are more visible; in my case, I just left it black. In Chapter 7 I will show you how you can use a comb of characters with the Format tab. There are other ways to help clients when they are unsure what to enter into a field, and we will look at them in later chapters.

160

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

More Action Triggers to Show and Hide Check boxes and buttons can be used in combination to create fields that show or hide. Refer to the TMC Order Form End file to see the final example of what happens when you enable the check box, as shown in Figures 4-42 and 4-43.

Figure 4-42.  Show and hide a shipping address using a check box

161

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-43.  Show and hide a shipping address using a check box and the Actions tab The settings for the check box “Check Box7” actions are on mouse up. For each of the Show/Hide Text and Button fields, show each field one at a time (Figure 4-44).

162

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-44.  When the check box is clicked, some fields in the form will show that they were hidden Since you must set the show fields one at a time, refer to the following list to see which field should have the Show setting: •

First Name_2

•

Last Name_2

•

Address_2

•

City_2

•

Province_2

•

Country_2

•

Postal Code_2

•

Hide and Clear Fields Button 163

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Hide and Clear Fields Button This button uses a combination of Reset and Show/Hide. If the shipping address is the same, you don’t want to store duplicate data, so you clear the fields that were shown when the check box was checked and hide them again along with the button. Refer to Figure 4-45.

Figure 4-45.  Reset button Figure 4-46 shows the settings for the button actions.

Figure 4-46.  When the button is clicked, some fields in the form will hide that were shown

164

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Since you must set the hide fields one at a time, refer to the following list to see which field should have the Hide setting: •

First Name_2

•

Last Name_2

•

Address_2

•

City_2

•

Province_2

•

Country_2

•

Postal Code_2

•

Hide and Clear Fields Button

Finally, reset all the fields that were earlier made visible including “Check Box7” to the previous blank state. The only field you cannot reset is the button; you can only hide it. This reset action is moved up to the top of this list. Refer to Figure 4-47 and Figure 4-48.

165

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-47.  Actions tab for the Reset button that clears the information in the fields and hides them again

166

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-48.  Reset for select fields using the dialog box including the check box using the Reset a Form dialog box

Set Layer Visibility As mentioned earlier, adding and setting layer visibility in a document can be tricky. One of the examples in this chapter is a file of a floor plan layout, showing how this can be achieved if you have a document with one or more layers. You can use either bookmarks or buttons to show and hide your layers. Refer to Figure 4-49.

167

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-49.  The layers in the floor plan PDF

Note  In the properties of each layer, I have set only the default mode of the title layer to be on when the document opens; the others are set to Off. Remember that to access the properties of a layer, you need to right-click the layer and choose Properties. You can find more details about adding and working with layers at https://helpx.adobe.com/acrobat/using/pdf-layers.html.

Using Bookmarks If you don’t want to use buttons, you can alternatively use bookmarks to show and hide layers. See Figure 4-50.

168

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-50.  Setting Bookmark properties Begin by making sure that the layers you want visible or hidden are on or off to create the correct view for your bookmark. Once you’ve created a bookmark, you can right-click it and choose Properties from the menu. The properties will appear. Then select the Actions tab, as shown in Figure 4-51.

169

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-51.  Bookmark action properties Notice that the action “Go to a page in this document” is already added. However, you will need to add the action of “Set layer visibility.” Upon clicking Add, an info warning will appear reminding you that whatever the current state the layers are in now will be what this bookmark will display. If you do not like your layer visibility, click Cancel and set your layers to the correct state before applying the action and choosing OK. Refer to Figure 4-52.

170

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-52.  Bookmark action warning properties for setting layer visibility on the Actions tab Now your bookmark should be able to show or hide the layer based on the set state. As with any action, it can be selected and then removed by clicking the Delete button on the Actions tab. You can repeat this action with the other bookmarks as well.

Using Buttons As with bookmarks, buttons can be used as well. Refer to Figure 4-53. However, you may want to hide some buttons and layers to reduce clutter while other layers are visible. Also, you may want to reset all the layers to the off or hidden state with a button. You can review the file to see what the final effect looks like. The following list shows what settings were applied

171

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

to each button on the Mouse Up trigger. As with the bookmarks, make sure that the layers are in the state you want before you set the layer visibility for each button. Make sure to test your file when you’re done.

Figure 4-53.  Example of settings applied to the buttons

172

•

Show Floor Plan button: Set layer visibility. You have the options Show – Show Vendor Number and Show – Hide Layers Button.

•

Show Vendor Numbers button: Set layer visibility.

•

Hide Layer button: Set layer visibility. You have the options Hide – Show Vendor Number and Hide – Hide Layers Button.

•

In the initial state, the Show Floor Plan button on the General tab is set to Form Field Visible, while the other two buttons are set to Hidden.

•

In the Layers pane, only the title layer is set to on; all other layers are turned off.

•

Only turn on layers that you want visible before adding the action of layer visibility to each button. Click OK to confirm setting. Refer to Figure 4-54.

Chapter 4

Buttons, Navigation, Form, and Nonform Actions

Figure 4-54.  This is the info alert that appears as the layer visibility is set Later you can use the up and down buttons in the Button properties dialog box if you want to reorder the actions, placing the Set Layer visibility as the last action. You can see my order in the file Floor_ planLayout_2023_End.pdf. In your own projects, once you are finished setting the buttons, return the layers to your default settings, save the file, and close it.

Summary This chapter covered a lot of topics concerning actions that can be applied to form fields and nonform items such as layers, bookmarks, buttons, pages, and hyperlinks. As you can see, Acrobat Pro offers a lot of options regarding navigation and controlling how you view or hide fields. At this point, you haven’t added any custom JavaScript. You’ve only used the settings that come with the Acrobat Actions tab. However, in the next part of the book, you are going to look at running your own JavaScript and how this affects what you input into your form fields. Before you go any further in this book, take some time to practice these actions on your own and try adding them to a few of your own projects.

173

PART II

Simplified Field Notation and Basic JavaScript

CHAPTER 5

Introduction to Simplified Field Notation and JavaScript Chapter Goal: In this chapter and the following chapter in Part II, you will first explore simplified field notation (SFN) used in Excel and how it compares to JavaScript. This will set the groundwork for what you can expect in the rest of the book. This chapter will begin by identifying where in Acrobat Pro form fields you can enter SFN and JavaScript. The JavaScript that you will be using in the following chapters is only for the form or navigation within a document and is not as advanced as a programmer’s JavaScript used in software or the Web. That is a whole other topic not discussed in this book. Mostly you will focus on simple math formulas that can be used to improve your forms in Acrobat Pro, as well as ones that clients will use in Reader.

© Jennifer Harder 2023 J. Harder, Enhancing Adobe Acrobat Forms with JavaScript, https://doi.org/10.1007/978-1-4842-9470-3_5

177

Chapter 5

Introduction to Simplified Field Notation and JavaScript

Note  This chapter does not reference any files, so there are none that need to be downloaded for this lesson.

Getting Started From the text files (.txt) provided in the following lessons, you will copy and paste the code into the correct dialog box areas and make minor modifications to the code. The following are some common uses for JavaScript in Acrobat Pro: •

Interaction and addition of watermarks, bookmarks, links, and annotations

•

Automatically filling in form fields

•

Changing the appearance of information in text fields as the information itself changes because of user input in other fields

•

Navigation of the document, such as zooming in and going to specific pages

•

Printing of the document

•

Controlling security settings, signatures, and custom validation

•

Assisting the Action Wizard to speed up tasks

The JavaScript entry can be found in the following fields’ properties tabs and tools: •

178

Text, dates, and drop-down lists: Actions (Run a JavaScript), Format Custom (Custom Format Script and Custom Keystroke Script), Validate (Run a Custom Validation Script), Calculate (Custom calculation script).

Chapter 5

Introduction to Simplified Field Notation and JavaScript

•

Check boxes, radio buttons, image fields, and buttons: Actions.

•

List boxes: Actions and Selection Change (Execute this script).

•

Digital signatures: Actions and Signed (This script executes when field is signed).

•

Barcodes: Actions and Value (Custom calculation script).

•

JavaScript tool: All JavaScripts (Global), Document JavaScripts, and Document Actions.

•

Action Wizard: New Action and New Custom Command subtools will be looked at in Chapter 15.

•

Remember the Actions tab is also available for Pages, bookmarks, and hyperlinks, but we will be focusing mainly on the form fields and buttons throughout the remainder of this book.

T ext Field, Date, and Drop-Down List Properties The following sections provide examples of what JavaScript added to these field tabs looks like.

Actions Tab Actions happen upon entering or exiting the field, as shown in Figure 5-1.

179

Chapter 5

Introduction to Simplified Field Notation and JavaScript

Figure 5-1.  The Actions tab in the Text Field Properties dialog box

Format Tab A custom format allows changes to text color, as shown in Figure 5-2. A custom keystroke allows events to change within the field when a certain criterion has been reached.

180

Chapter 5

Introduction to Simplified Field Notation and JavaScript

Figure 5-2.  The Format tab in the Text Field Properties dialog box

181

Chapter 5

Introduction to Simplified Field Notation and JavaScript

Validate Tab Similar to a custom format, on the Validate tab certain criteria are checked and must be met before you can proceed, as shown in Figure 5-3.

Figure 5-3.  The Validate tab in the Text Field Properties dialog box

Calculate Tab The Calculate tab offers custom calculations that can’t be done with SFN or Value, as shown in Figure 5-4. This is the only tab where SFN can be entered.

182

Chapter 5

Introduction to Simplified Field Notation and JavaScript

Figure 5-4.  The Calculate tab in the Text Field Properties dialog box

 heck Box, Radio Button, Image Field, C and Button Properties Check boxes, radio buttons, and regular buttons that include image fields can be used as visible or hidden fields, if required, to initiate a calculation, as shown in Figure 5-5.

183

Chapter 5

Introduction to Simplified Field Notation and JavaScript

Figure 5-5.  The Actions tab in the Radio Button Properties dialog box is the only tab where you can add actions. The same goes for check boxes and regular buttons

List Box Properties Besides the Actions tab, the Selection Change tab is an area for adding a script when you want to change the field that is being selected. In this example, an item selected from a List Box references another field elsewhere in the form. Refer to Figure 5-6.

184

Chapter 5

Introduction to Simplified Field Notation and JavaScript

Figure 5-6.  The Actions and Selection Change tabs

185

Chapter 5

Introduction to Simplified Field Notation and JavaScript

Digital Signature Properties You can add actions to a digital signature’s properties either on the Actions or Signed tab. The Signed tab is like the Validate tab in other fields. Validation occurs when some criteria are met, and then the script executes. Refer to Figure 5-7.

Figure 5-7.  The Actions and Signed tabs in the Digital Signature Properties dialog box 186

Chapter 5

Introduction to Simplified Field Notation and JavaScript

Barcode Properties As with other fields, you can add actions to barcodes. However, the barcode creates its own value script on the Value tab. Its value depends on what is in the form as a whole in regard to types of fields and their input values. Refer to Figure 5-8.

Figure 5-8.  The Actions and Value tabs in the Barcode Field Properties dialog box 187

Chapter 5

Introduction to Simplified Field Notation and JavaScript

Regardless of what type of field you plan to use, all actions and their edits are accessed through the JavaScript Editor box, which holds the script. You can access this editing area when you click the Edit or Add button. The Add button is generally on the Actions tab, as in Figure 5-9. The Edit button can also be found on the Actions tab but is on some other tabs as well such as Format, Validate, and Calculate; they all lead to the JavaScript Editor.

Figure 5-9.  Access to the JavaScript Editor through the Edit or Add button, found on the Actions, Format, Validate, and Calculate tabs

Global Document JavaScript Now let’s look at the global document JavaScript. If you have a document open, go to the Tools tab and select the JavaScript tool found in the Customize section. You will now be able to view all the subtools, as shown in Figure 5-10.

188

Chapter 5

Introduction to Simplified Field Notation and JavaScript

Figure 5-10.  JavaScript tool and its submenu items Actions that happen globally can affect more than one field. This could include formatting such as a color change to the field or the text being entered into fields. These types of actions will affect many fields throughout the file that access the Document JavaScripts dialog box in one of the field properties tab locations mentioned in this chapter. Fields can call upon a single global function to reduce typing and the size of the document, as shown in Figure 5-11. You will look at this area in more detail in later chapters.

Figure 5-11.  Document JavaScripts dialog box 189

Chapter 5

Introduction to Simplified Field Notation and JavaScript

Additional actions that are specific to the document can be added using the Document Actions tool, as shown in Figure 5-12.

Figure 5-12.  Document Actions dialog box Alerts can be placed here when these following events happen, which we will look at in Chapter 8.

Note  You can’t add more document actions here without advanced scripting knowledge. You can also view all your JavaScripts at once under the All JavaScripts subtool, which opens the JavaScript Editor. Refer to Figure 5-10. If there are errors, you can use Debug and Debugger subtools to help you. However, I find it helps to have some knowledge of JavaScript structure and do the editing in a program such as Notepad++ or Adobe Dreamweaver where there is more room to type. Editing programs like 190

Chapter 5

Introduction to Simplified Field Notation and JavaScript

Dreamweaver also show you clearly which line in the code you are on with numbers on the left. Acrobat does not have these visual cues, only a text reference in the lower right of the editor, which I do not find useful for detailed code editing. Refer to Figure 5-13 and Figure 5-15.

Figure 5-13.  JavaScript Debugger dialog box with settings for viewing and inspection 191

Chapter 5

Introduction to Simplified Field Notation and JavaScript

Note  if you find that your Debugger is not operating, you can check and reset this by selecting Edit ➤ Preferences ➤ JavaScript and selecting Enable JavaScript Debugger after Acrobat is Restarted. As well as the settings of “Enable interactive console” and “Show console on error and messages,” by default, these settings are disabled. Refer to Figure 5-14 and click OK if you choose to activate these options. Then close the Acrobat Pro Application and then open again. Make sure you have exited the JavaScript tool for the file before you close the application, or the dialog box may open suddenly before the document itself opens. Otherwise, click Cancel to exit and leave the debugger disabled, which may be your preference if you are working with lots of documents that do not contain JavaScript. Refer to Figure 5-14 to see the preference settings. In my case, I enabled these preference settings before I edited my forms.

192

Chapter 5

Introduction to Simplified Field Notation and JavaScript

Figure 5-14.  JavaScript Debugger preferences with settings to enable the Debugger dialog box Though we will not be using Debugger in this book, the following link can give you some further guidance on the limitations of using Debugger as well as other JavaScript preference settings: https://opensource.adobe.com/dc-acrobat-sdk-docs/library/ jsdevguide/JS_Dev_Tools.html#using-the-javascript-debugger-console When you’ve finished typing in your editing program, copy and paste the code into Acrobat’s JavaScript Editor and run the debugger and test it (Figure 5-15). 193

Chapter 5

Introduction to Simplified Field Notation and JavaScript

Figure 5-15.  How JavaScript appears in an application like Dreamweaver or Notepad++ compared to how the code appears in Acrobat Pro JavaScript Editor (no numbered lines)

Note  The Edit ➤ Preferences ➤ JavaScript area will also allow you to alter your Acrobat JavaScript Editor’s display of its font type and its font size. You can also link to a different external editor if required. However, for this book, select the Use Acrobat JavaScript Editor option, as shown in Figure 5-16.

Figure 5-16.  JavaScript Editor settings

194

Chapter 5

Introduction to Simplified Field Notation and JavaScript

Web Links and References For the full library, refer to version Acrobat SDK 2021: https://opensource.adobe.com/dc-acrobat-sdk-docs/acrobatsdk/ index.html Current known support of JavaScript is called SDK 2021, and you can review the latest JavaScript API Reference Guide online which is currently 1.7. https://opensource.adobe.com/dc-acrobat-sdk-docs/library/ jsapiref/index.html Outside of Acrobat, you can use the following resources to learn more about JavaScript in general: https://www.w3schools.com/js/ https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide However, keep in mind that the JavaScript used in Acrobat is limited to the application and in this case to forms, so certain declarations and scopes will fail to work. Building a PDF form is not the same as a website, which has more complex interactions. Nevertheless, I do find these links can add clarification when I compare them to the documentation found in the Adobe SDK Resources.

Regular Forms vs. E-Signature Forms The e-signature form tools are more recent additions to Acrobat Pro and contain digital signature fields for the Adobe Sign for eventual web form creation. While they look similar, they do not operate the same as regular electronic form fields and do not allow for the addition of JavaScript. For those reasons, we will not be looking at them in-depth until Chapter 20 where I will be giving a brief overview as well as resources for working with these fields and newer form-related Acrobat tools. For now, refer to Figure 5-17. 195

Chapter 5

Introduction to Simplified Field Notation and JavaScript Regular Form Fields & Editing tools.

E-Signature (E-Signing) Form Fields & Editing tools.

Figure 5-17.  Two types of form field tools in Acrobat Pro You can access the e-signature fields shown in Figure 5-17 if you open your Prepare Form tool by checking “This Document requires signatures” (Figure 5-18) and then clicking Start. For your forms in this book, this option should always remain unchecked; check this option only for Chapter 20.

Figure 5-18.  How to create e-signature forms. For the forms you are working with, keep this unchecked 196

Chapter 5

Introduction to Simplified Field Notation and JavaScript

JavaScript and Acrobat on the Document Level In Acrobat Pro, to have a resulting event or action occur in a field in your form, you need to follow this equation: Trigger + Select Action = Result In addition to knowing what’s being triggered, you need to know where the results are going to end up. In the case of forms, data, or if a value is going to be taken from a field (text, drop-down, check box, radio button, etc.), the collection of that data is going to be deposited into a final field as the result you want. Whether using a value, simplified field notation, or JavaScript, it’s important to know the exact name of those fields. If you do not know the exact name, you will not get a result, and the form will be useless. To avoid confusion with fields, each must have a unique name. The exception with naming is radio button groups, which act collectively; however, their groups must have distinct names. With all other fields, there can’t be two or more named Sum1 within a form for them to operate independently; it should be Sum1 and Sum2 and so on. Follow along with the form examples provided to complete the lessons in the next chapters. The PDFs with the name “End” are the final result.

Summary JavaScript can be added in a variety of areas; it all depends on what type of form field you plan to use or if you plan to add the JavaScript to the entire document. In the next chapter, you will see how a knowledge of SFN and JavaScript can improve forms that you use for creating calculations.

197

CHAPTER 6

Basic and Complex Calculations Chapter Goal: In the first example of JavaScript calculations in this chapter, we will compare three methods, value, Simplified Field Notation (SFN), and JavaScript, as found on the Calculate tab in the Text and Dropdown List form fields, as shown in Figure 6-1.

Figure 6-1.  Inside the Acrobat Calculate Tab Examples PDF file While value is generally the most straightforward way of dealing with calculations for beginner form creators, you will soon discover that there are limitations to value, so SFN and JavaScript might be better options. This chapter will show the strengths and weaknesses of each method.

© Jennifer Harder 2023 J. Harder, Enhancing Adobe Acrobat Forms with JavaScript, https://doi.org/10.1007/978-1-4842-9470-3_6

199

Chapter 6

Basic and Complex Calculations

Note  If you want to work along in this lesson or review the final result, download the Chapter 6 files from the link in the introduction. The file with the label “Start” is the file without the code, and the file with the label “End” is the final result. You will also find folders with original MS Word, Excel, and PDF files if you would like to edit them, as well as a folder containing the original scripts if you would like to add them to your own PDF forms. If you are creating your form from an original PDF, refer to the “Forms Review” section in Chapter 1. Remember that to view the properties of a field, you must select the Prepare Form tool; only then can you right-click or double-­click a field to review its properties.

Getting Started Let’s take the addition or sum example, which is common to all methods regardless of which method or option you choose on the Calculate tab. Refer to the Acrobat Calculate Tab Examples PDF “Start” and “End” files in the folder for this chapter. Refer to Figure 6-2.

200

Chapter 6

Basic and Complex Calculations

Figure 6-2.  The Calculate tab is common to all three methods we will discuss shortly, and with numbers you use the Format tab with a “Select format category” setting of Number

Note  If no value has yet been applied to a field on the Calculate tab, the option “Value is not calculated” will be selected. This is OK for text fields or even fields that will contain numbers but are not going to create the final calculation. In this case, the fields are formatted to Number with a decimal place of 0 on the Format tab, but you can set this to 1, 2, or higher if you do not want to round up the number. We will look at this tab more in Chapter 7. Refer to Figure 6-2.

201

Chapter 6

Basic and Complex Calculations

Sum Value In this example, I set the calculate properties in the field TotalSum, which is set to “Read-only” on the General tab, to prevent users from typing calculations into this field. On the Calculate tab, select the “Value is the…” button and pick sum (+) from the drop-down list. Notice in the “End” file there are field names of some of the fields in the form in the gray area (Figure 6-3).

Figure 6-3.  Entering the sum value into the Calculate tab In this example, I then clicked the Pick button and selected from the Field Selection dialog box the form fields I wanted to draw my calculations from, in this case Object 1Sum and Object 2Sum. Then I clicked OK to add them to the list. Refer to Figure 6-4.

202

Chapter 6

Basic and Complex Calculations

Figure 6-4.  Entering the sum value on the Calculate tab from the Field Selection dialog box In this example and Figure 6-4, you are getting data or values from two fields: Object 1Sum and Object 2Sum. They add together in the field TotalSum to offer a result. This works really well for other types of basic calculations from the list such as product (x) multiplication, the average of numbers, and the minimum and maximum of numbers. However, other basic value calculations such as subtraction or division are just not possible using this method. Refer to Figure 6-5.

203

Chapter 6

Basic and Complex Calculations

Figure 6-5.  Field value options are limited by what is available in the list After you click the Close button in the Properties panel, you can then test your form fields in preview mode. Then return to edit mode if you want to review other fields. To perform additional calculations, we need to look at the next option.

Simplified Field Notation Now let’s look at Simplified Field Notation. Notice on the Calculate tab in Figure 6-6 that the button called Simplified Field Notation is selected. These examples are found in the next set on page 1 of the Acrobat Calculate Tab Examples PDF file named with “End.”

204

Chapter 6

Basic and Complex Calculations

Figure 6-6.  Entering the SFN code into the Calculate tab and JavaScript Editor and the result on the form

Note  With SFN and JavaScript you cannot pick or select your fields; you must type the information directly into the JavaScript Editor. Refer to Figures 6-6 and 6-8. The second way of accomplishing this is with SFN, which is common to a program like Microsoft Excel. While this is similar to the value sum example, there are differences. In the previous sum example, you could have spaces between the words in the fields. However, Object 1Sum in SFN must be written as Object1Sum. There can be no breaks using SFN. This rule is very strict. Any break in the name of the field will cause it to not calculate. If you need a break, use an underscore (_), as in Object1Sum_2, or use what is known as the camel method where each new word is capitalized but with no breaks (ObjectSum).

205

Chapter 6

Basic and Complex Calculations

In this example, for the field TotalSum_2, I am adding together the two fields Object1Sum_2 and Object2Sum_2. I was able to enter this text into the JavaScript Editor when I clicked the Edit button in Figure 6-6 and then clicked OK to exit. Another difference with SFN is the addition of a plus symbol (+) to show that you are adding these two field values within the field TotalSum_2. Use an asterisk (*) to multiply, a minus (-) to subtract, and a slash (/) to divide. If you’ve ever taken algebra, you’ll be familiar with parentheses: (). Whatever occurs within parentheses happens first before the calculation continues. You can see an example of this in the fields TotalAverage_2 and TotalMoreComplex. Refer to Figure 6-7.

Figure 6-7.  Entering the SFN into the Calculate tab for a more complex calculation To type this code into the editor, you must first click the Edit button. When you’re done entering the code, click OK to exit. Here you can see (Object1MoreComplex*2) + (Object2MoreComplex-7) will now calculate the final result in the TotalMoreComplex field. Then click Close to exit the Properties dialog box and click Preview to test your fields. If you put numbers such as 5 and 10 into the fields Object1MoreComplex and Object2MoreComplex, this should be your answer in the field TotalMoreComplex: (5*2) + (10-7) = 13 206

Chapter 6

Basic and Complex Calculations

Note that division works best when you have already entered a number in one of the text fields. However, as you may notice, calculations such as minimum or maximum are a bit more complicated to figure out using SFN, so I have left these fields without a calculation.

JavaScript Custom Calculation Script The final method we will look at is a custom calculation script, which is found in the third section on the Acrobat Calculate Tab Examples page. Figure 6-8 shows the “Custom calculation script” with the Edit button selected for the field TotalSum_3.

Figure 6-8.  Entering the custom calculation script into the Calculate tab 207

Chapter 6

Basic and Complex Calculations

To type this code into the editor, you must first click the Edit button. Then you can type. When done, click OK to exit. Afterward, you click the Close button on the Properties dialog box, and then you would click the Preview button and test the form. In the case of JavaScript, you can again see that there are similarities and differences in the way the code is set up. To translate the fields into the language of JavaScript, you need to use variables to hold the fields. Variables act as information containers. In JavaScript, the word variable uses the short form var. After the word var you add a name. In this example, to keep it simple, let’s use the name a. This variable called a will now hold whatever value comes into the text field Object1Sum_3. Once a variable is named the first time, it does not need to have the word var attached and can be used anywhere in the script as just a. To ensure that the number input will follow through correctly, add this.getField, which means “get the data in this field,” which in the case is from the field Object1Sum_3. Place the field name into parentheses, (), and straight quotes (""). At the end of the variable, use a semicolon (;) to indicate that that is the end of this variable statement. Use the same steps for the second variable, b, which uses the field Object2Sum_3. They are the two fields that you want to use to calculate the final input for your current field, TotalSum_3. var a = this.getField("Object1Sum_3"); var b = this.getField("Object2Sum_3"); This is the final part of the script: event.value = a.value + b.value; This is similar to the SFN example. However, you need to add .value on the end of each variable to remind Acrobat that you want the value of each field and the final value to be added in the final field. The final field, TotalSum_3, is represented by event.value. In this final field, the event of the addition taking place is the result. It is important to note that the final 208

Chapter 6

Basic and Complex Calculations

field does not need a variable name because of the way Acrobat contains the script within the final field. Again, you end this line with a semicolon. Another variation on this same script could be, if you did not want to separate the variables, to combine them and write this: event.value = this.getField("Object1Sum_3").value + this. getField("Object2Sum_3").value; However, when more variables are involved or you are using the field more than once in a calculation, is this the best way of writing code? Or is it better to organize all your variables in one area to access if you need to change the name of a form field in the code quickly? For example, which is easier to change? event.value=((this.getField("Object1Sum_3"). value+this.getField("Object2Sum_3").value))*((this. getField("Object1Sum_3").value -this.getField("Object2Sum_3"). value)); Or instead write this: var a = this.getField("Object1Sum_3"); var b = this.getField("Object2Sum_3"); event.value = (a.value + b.value)*(a.value - b.value); Where the naming of variables is concerned, it’s OK to have the names longer than one letter, like a. You can give them more meaningful names like age or sum. In the final example, it would be written like this: event.value = age.value + sum.value; However, make sure to change your variables earlier in the code to var age and var sum so that the code will function.

209

Chapter 6

Basic and Complex Calculations

The following are a few other things to remember about variables when working in Acrobat Pro:

210

•

All JavaScript variables must be identified with unique names.

•

Field Names can contain letters, digits, and underscores.

•

Variable names must begin with a letter though it is OK for the field you are referencing to start with a number.

•

Names are case sensitive (y and Y are different variables).

•

Reserved words (like JavaScript keywords) cannot be used as names. I would not create a variable like var event because event is a key JavaScript word used in the final event. For example, event.value = age. value + event.value; might not function since event.value has already been used once.

•

As mentioned, as with SFN, make sure to keep your variable and generally your field names as one word rather than separate words. However, so along as the field names are within the straight quote marks, it is OK to have a space.

•

If you are using modern JavaScript, be aware that you cannot replace the declaration var with let as you will run into an error. Use var only.

•

Caution is required when you switch between value, SFN, and the Custom Calculate Script button options. As you select the alternative option, you will erase the code you just entered, so always keep a backup in your JavaScript code in your .txt file as you work. In addition, do not save my “End” file if you accidentally erase the code; just close it without saving changes.

Chapter 6

Basic and Complex Calculations

Note Also keep in mind when you are writing your quotes that surround the field name that you use a program like Notepad++ or Dreamweaver to write the code if you need more room, as mentioned in Chapter 5. A program like MS Word may try to substitute the double quote with the quote marks that are used in a conversation, also known as curly, when you should be writing “neutral” or straight quotes. This can confuse the Acrobat JavaScript Editor, causing an error and not allowing you exit the dialog box. At this point, if you need some basic knowledge about the Calculate tab, you can refer to this page: h­ ttps://helpx.adobe.com/acrobat/using/manage-form-fieldproperties.html

F inal Thoughts on Working with the Calculate Tab Let’s review. You have seen three ways in which addition can be done: value, SFN, and a JavaScript custom calculation script. However, which one is right for your project? Do you in all situations need to use Acrobat JavaScript? In most simple calculation projects, I recommend using value or SFN in various parts of the form. However, if you have been reviewing the file Acrobat Calculate Tab Examples “End” examples, you will see Value and SFN do not equally cover all issues. For Value, you cannot subtract or divide. SFN cannot find minimum or maximum numbers. In this case, you may have to use a combination of both these calculations in your form.

211

Chapter 6

Basic and Complex Calculations

Note  JavaScript can do all of these calculation as well as many others. Also, as you will see in Chapter 12, when the JavaScript becomes more complex, it’s not always a good idea to mix values and SFN with JavaScript as this can lead to some fields not responding correctly. Consistent coding methods are crucial for form calculations to run smoothly. See also the “Set Field Calculation Order” section later in this chapter. For example, in the Field TotalMinimum_3, I used the following custom calculate script: var q = this.getField("Object1Minimum_3"); var r = this.getField("Object2Minimum_3"); event.value=Math.min(q.value,r.value); You can use the JavaScript math formula Math.min to get a minimum number similar to the value example. You could use Math.max to get the maximum number. There are other math formulas that are not available to us via value or SFN but are with JavaScript:

212

•

Math.abs(x): Returns the absolute value of x.

•

Math.acos(x): Returns the arccosine of x, in radians. However, you should enter a number between -1 and 1 to avoid throwing an error. Setting a restriction with the Validate tab may be something you will want to explore further later in this book.

•

Math.asin(x): Returns the arcsine of x, in radians. However, you should enter a number between -1 and 1 to avoid throwing an error.

Chapter 6

Basic and Complex Calculations

•

Math.atan(x): Returns the arctangent of x as a numeric value between -PI/2 and PI/2 radians.

•

Math.atan2(y,x): Returns the arctangent of the quotient of its arguments.

•

Math.ceil(x): Returns x, rounded up to the nearest integer.

•

Math.cos(x): Returns the cosine of x (x is in radians).

•

Math.exp(x): Returns the value of Ex, where E is Euler’s number.

•

Math.floor(x): Returns x, rounded down to the nearest integer.

•

Math.log(x): Returns the natural logarithm (base E) of x.

•

Math.PI: Gives the formula of ∏.

•

Math.pow(x,y): Returns the value of x to the power of y.

•

Math.random(): Returns a random number between 0 and 1.

•

Math.round(x): Rounds x to the nearest integer. Example: Round up a subtotal.

•

Math.sin(x): Returns the sine of x (x is in radians).

•

Math.sqrt(x): Returns the square root of x.

•

Math.tan(x): Returns the tangent of an angle.

213

Chapter 6

Basic and Complex Calculations

And there are many other Math objects you can view and test at the following pages: https://www.w3schools.com/jsref/jsref_obj_math.asp https://developer.mozilla.org/en-US/docs/Web/JavaScript/ Reference/Global_Objects/Math In this case, x or y would be written as (x.value) or (x.value,y.value).

J avaScript Script Validation for Displaying Zero One final thing that you could not do in this form without JavaScript is to format the number 0. Sometimes on a form you do not want the 0 to be present if no calculation has been added to the first two fields; you just want it blank. Refer to Figure 6-9.

214

Chapter 6

Basic and Complex Calculations

Figure 6-9.  Adding a validation script into the Validate tab of the Total field. Before and after adding the script This looks better. Look at the Validate tab of the field TotalSum_3 if you need a reference, and see Figure 6-9. Along with the Calculate tab script, you can enter the following into your Validate tab: // Custom Validate script for text field if (event.value == 0) event.value = ""; To start off this script in text field TotalSum_3, a comment explains what we’re doing.

215

Chapter 6

Basic and Complex Calculations

A double slash (//) always starts off a comment. Comments can be written anywhere in JavaScript and will not affect the calculations. Consider them a place for helpful reminders. This is another type of commenting you can use for longer, paragraph-­ sized comments: /* This type of comment is for lots of text */ However, I generally prefer to use // because of the small space Acrobat provides.

The Final Line of Code This is what is known as a conditional statement, and you will look at them in detail later. Essentially it is saying, “If no value or only the zero number from the other two fields has been entered (both are blank or both contain zeros), then leave the final value field blank as well.” if (event.value == 0) event.value = ""; One final item: If you used this script in subtraction or addition with negative numbers and you needed to see the 0 (example: 5-5=0), you might not see the 0. If you need to see the 0 only when the fields are full, you can use a more complex and stricter validation. == is not a strict equality operator comparison. A result like 5-5=0 might not work, and 0-0=0 or 0x5=0 might not work because the validation regards 0 and a blank field as the same thing. === is a strict equality operator comparison, so now a result like 5-5=0 or 0-0=0 or 0x5=0 will work because the validation regards 0 and a blank field as not the same thing and will put a 0 in the results field. You could write the following to keep your 0: if (event.value === 0) event.value = "";

216

Chapter 6

Basic and Complex Calculations

However, Acrobat seems to act quirky and not get the intended result where the final field is blank if one value field is added but you have not entered a value in the other. Refer to Figure 6-10.

Figure 6-10.  Validation is not acting as it should in these fields So, here’s the alternate code that you can view in my file AcrobatCalculateTabExamples_End_option2validate.pdf: //Sum Validation to insure 0 is not missing from an actual calculation if (a.value !== a.defaultValue && b.value !== b.defaultValue) { event.value = a.value*1 + b.value*1 ; } else { event.value ="" ; } This code allows you to have the field blank if no numbers are in the other fields. However, if a Zero value is entered in both fields (&&), it will retain the 0 even if the final result is 0. In this case, you used !== (strict not equal), which is similar to strict equality operator comparison, ===, but works in reverse and checks the current value against the default. If no value is found initially in either of the other value fields (the default value), the event.value will remain blank. The values in this example are multiplied once against themselves and then added together. Notice you used another conditional statement, if/else. Refer to Figure 6-11.

Figure 6-11.  Validation is acting as it should in these fields when both fields have a value 217

Chapter 6

Basic and Complex Calculations

For other equality and inequality operators and comparisons refer to the following pages: https://www.w3schools.com/js/js_comparisons.asp https://developer.mozilla.org/en-US/docs/Web/JavaScript/ Reference/Operators

Note  In the subtraction example, go to the Validate tab, and change the following code in the PDF field called TotalSubtract_3: event.value = a.value*1 + b.value*1; to the following: event.value = f.value*1 - g.value*1; For the code to operate correctly, the Variable values on the Validate tab must match what is on the Calculate tab throughout the entire code, so refer to that field’s tab to compare. For example, in the code, the a.value variable must be replaced with f.value, and the b.value variable must be replaced with g.value. The same variable change is true for those variables ending an a.defaultValue or b.defaultValue. When you are done viewing the forms, click the Close button in the upper-right corner of the preview to close the Prepare Form tool. Refer to the “Forms Review” section in Chapter 1 if you are unsure what this button looks like. Save your copy of the “Start” file only if you made edits.

Drop-Down Alternatives As in Chapter 2, for this example, you can replace some of the text fields with drop-down lists to calculate. While they’re similar to text fields, I find this method a good alternative if you want your client to use very specific

218

Chapter 6

Basic and Complex Calculations

values; it eliminates the need for validation on each drop-down because the values are already set. You should not replace the final text field (Read-­ Only) with a drop-down. Even though these Validate and Calculate tabs do work with drop-downs, the end result is really only one value. In Chapter 12, you will see how to use JavaScript to get more than one result into a dropdown list when required. Refer to Figure 6-12.

Figure 6-12.  Using drop-down lists to fill in fields for calculations

Note  With drop-downs, I left the “Field value is not validated” field on the Validate tab blank because I was using specific numbers. Unlike text fields, there always is a value and never a blank value. Refer to AcrobatCalculateTabExamples_End_option2DDown. pdf, which contains a drop-down list in the file folder for this chapter.

Set Field Calculation Order Later, as you work with multiple fields that require calculation, you can use the Option on the right side of the Prepare Form tool to set the field calculation order from the More list. Refer to Figure 6-13.

219

Chapter 6

Basic and Complex Calculations

Figure 6-13.  Calculated Fields dialog box accessed from the More menu

220

Chapter 6

Basic and Complex Calculations

As more fields contain calculations or are accessed by other fields, being able to set the order by moving a field up or down in the list is crucial if you notice that one of the calculations is not appearing in the order you want. This is also a good way to see if certain fields are missing that should be using the Calculate tab. Keep this in mind, along with Show Tab Number Order, as you build more complicated forms in the following chapters.

Resetting Your Field of Focus While working with calculations in a form or any set of form fields, there may be situations where you reset the fields. In addition, you may want the user of the form to, upon clicking the reset button, return to a specific field; oftentimes this is the first field in the form. This can be done using JavaScript. Rather than having all fields inactive and not knowing which field to start typing in, the cursor on reset will be placed in the active field, and the user can begin to type again. We can see a basic example of this in the file AcrobatResetField_ Focus_End.pdf. Refer to Figure 6-14.

221

Chapter 6

Basic and Complex Calculations

Figure 6-14.  Reset your field of focus in a form In this example, I could have used JavaScript to perform calculations; however, in this case I am just using value. This is not relevant to creating a field of focus; instead, refer to the Reset button properties on the Actions tab. Refer to Figure 6-15.

222

Chapter 6

Basic and Complex Calculations

Figure 6-15.  Reset your field of focus in a form on the Button Properties dialog box’s Actions tab Here I initially chose the action of Mouse Up – Reset a form, which you can review how to do in Chapters 2 and 4. However, there is no preprogrammed way to set a field focus, so instead set the trigger to On Focus and then select the action Run a JavaScript and click the Add button. In this example, you can select the action and click the Edit button to review my code. Refer to Figure 6-16.

223

Chapter 6

Basic and Complex Calculations

Figure 6-16.  Code in the JavaScript editor for the field of focus var fn = this.getField("First Name"); fn.setFocus(); Upon clicking OK and exiting the JavaScript Editor, you can close the Properties panel and click the Preview button to test the fields. Then click the Reset button, and the field of focus is the text field called First Name. For your own projects, try changing the name of the field in the JavaScript code to set a new field of focus. We will see another example of setFocus(); in Chapter 10, when a text box becomes too full and you need to use another field to keep typing your text.

224

Chapter 6

Basic and Complex Calculations

Summary In this chapter, you looked at the three ways you can add calculations to your form fields using the Calculate tab. •

Value

•

Simplified Field Notation (SFN)

•

Custom calculation script (JavaScript)

While each example became progressively more complex, a broader range of possibilities opened up as you moved toward JavaScript. You also saw how adding JavaScript to your Validation tab made it possible to see when the Total field was being utilized and when it was not. Giving clients accurate form information updates is important. Finally, you saw how you can add a field of focus so that when a form is reset, the user knows where to start retyping again. In the next chapter, you will explore how custom JavaScript can affect the Format tab when it comes to the following: •

Number

•

Percentage

•

Date

•

Time

225

CHAPTER 7

Format Calculations Chapter Goal: In this chapter, you’ll be working mostly with number, percentage, date, and time formats using value, Simplified Field Notation (SFN) and some custom JavaScript. Let’s look at where it works and doesn’t. You’ll also be using some JavaScript to assist you. Like in Microsoft Excel (see Figure 7-1), sometimes you must work with different formats of numbers; you don’t always deal with just 1+1. The following are other formats you might encounter: •

Percentage (98%)

•

Date (June 25, 2023)

•

Time (8:30 a.m.)

© Jennifer Harder 2023 J. Harder, Enhancing Adobe Acrobat Forms with JavaScript, https://doi.org/10.1007/978-1-4842-9470-3_7

227

Chapter 7

Format Calculations

Figure 7-1.  Formatting cells in MS Excel The same is true when you work in Acrobat Pro. Text fields and drop-down lists offer the options shown in Figure 7-2.

228

Chapter 7

Format Calculations

Figure 7-2.  Formatting cells in Acrobat Pro in the properties dialog box Table 7-1 compares formatting in Acrobat to Excel.

Table 7-1.  Comparison of Acrobat and Excel Formatting Options Acrobat

Excel

None

General, Text

Number

Number, Currency, Accounting, Scientific

Percentage

Percentage

Date

Date

Time

Time

Special

Special

Custom

Custom

Possibly accomplished with Custom or using Fraction two separate formatted number fields

229

Chapter 7

Format Calculations

As you can see, most formatting is similar. None or general is considered a default setting; the field could contain generic numbers or text. However, they would not be used in a calculation.

Note If you want to work along in this lesson or review the final result, download the Chapter 7 files from the link mentioned in the introduction. The file with the label “Start” is the file without the code, and the file with the label “End” is the final result. You will also find a folder with original MS Word and PDF files if you would like to edit them, and a folder containing the original scripts if you would like to add them to your own PDF forms. Remember that to view the properties of a field, you must select the Prepare Form tool; only then can you right-click or double click a field to review its properties.

Number Formatting You can accomplish most of your calculations using a combination of value and SFN. To view, refer to the PDF files Acrobat Format and Calculate Tab Examples. See the file AcrobatFormatCalcTabExamples_ End.pdf in the file folder for this chapter and look at the fields TotalNumber for addition and TotalNumber_2 for subtraction. Refer to Figure 7-3 as well as the settings in Figure 7-4 and Figure 7-5. Later, for an additional example, refer to the file InvoiceForm_Example_End.pdf.

Figure 7-3.  An example of a field formatted with Number

230

Chapter 7

Format Calculations

As mentioned, when the Format tab is set to the Select Format Category setting of Number, you then have the number options of Decimal Places (0–10). Separator Style can be a combination of comma and decimal points. Examples include 1,234.56, 1234.56, 1.234,56, 1234,56, and 1’234.56. Refer to Figure 7-4.

Figure 7-4.  Settings applied to the fields in the Format tab

231

Chapter 7

Format Calculations

Currency Symbol by default is set to none. However, from the list you can choose options of dollar ($), euro (€), pound (₤), and other currency symbol options that can then appear before or after the currency (Figure 7-4). However, if the currency symbol or noncurrency symbol you need does not show up in the list, you may need to use custom JavaScript to accomplish that. We’ll look at that in Chapter 18. Symbol Location from the list sets where the symbol will appear before or after the numbers and with or without a space. The two Negative Number Style options are “Show parentheses” and “Use red text.” These are by default unchecked, and you can see how the example of the current format displays in the properties dialog box. However, when “Show parentheses” is enabled, rather than a negative (-) symbol, the numbers show in parentheses instead. “Use red text” also removes the negative symbol and changes the text color from whatever is set on the Appearance tab, like black, to red only when the number is negative. Refer to Figure 7-4. Then on the Calculate tab, as you saw in Chapter 6, and Figure 7-5 you can then decide whether to use value, SFN, or JavaScript (a custom calculation script) to perform the calculations.

232

Chapter 7

Format Calculations

Figure 7-5.  Possible settings applied to the Total field whether it is value, SFN, or a custom calculation JavaScript Remember, for examples of JavaScript, as you saw in the math example in Chapter 6, sometimes when doing more scientific calculations such as (Math.tan(x)), you can use a custom calculation script or JavaScript to assist you.

Formatting with a Percentage Like Number formatting, Percentage works well with the Calculate tab’s value and SFN. To view an example, refer to the “End” file called AcrobatFormatCalcTabExamples and refer to the fields Quantity 1Percentage and Quantity 2Percentage for addition. Refer to Figure 7-6. Later, for additional examples, refer to the files InvoiceForm_Example_ End.pdf and _End2_customPercent.pdf. 233

Chapter 7

Format Calculations

Figure 7-6.  An example of a text field formatted with Percentage Just like with the Number format, you can set the decimal places and separator style. The % symbol will always appear after the number. Refer to the “Number Formatting” section in this chapter if you need to review. In this example, I set the field TotalPercentage (read-only) to a format of percentage as well, but you could leave the format at Number if you prefer. However, if you want the numbers to remain within a range of 0–100, then you need to set the Validate tab (Field value is in range) to match this range and prevent the numbers from going higher than 100 percent when the user types in the other fields. Refer to Figure 7-7.

234

Chapter 7

Format Calculations

Figure 7-7.  Set the Validate tab when you want a percentage range You can set negative numbers as part of the range as well, such as From: -100 To:100. However, keep in mind when the user types in 1, Acrobat interprets that to mean 100 percent, so if you want 1 percent, you need to type in 0.01, and “1%” will appear as the number you entered. This can present an issue when you try to type in 100% in one field and 100% in the other and even after setting validation you get “200%” with no warning message. Only when you type 101 into a field, which would appear like “10,100.00%,” might you get a warning from the TotalPercentage field.

A Workaround for the Percentage If you are concerned that clients will not understand this formatting, you can add a helpful hint using JavaScript, which you’ll explore later. If you don’t want to add a helpful hint, an alternative is to improve this formatting. Let’s create a custom formatting so that when 1 is pressed, only 1% will be entered rather than 100%. To do this, you need to create a custom format for each percent field that you will be entering percents into. Refer to Figure 7-8. Fields that will not have data entered, such as the Total, which has been set to read-only on the General tab, can be left with a format of

235

Chapter 7

Format Calculations

Percent. You can review these same fields Quantity 1Percentage and Quantity 2Percentage now with the changes in this example in my file AcrobatFormatCalcTabExamples_End_CustomFormat.pdf.

Figure 7-8.  Custom format script rather than percentage added to the Format tab

Note  Your version may read Number, Percentage, or Custom options in the label area, but this does not affect the calculations. Refer to Figure 7-8.

236

Chapter 7

Format Calculations

Here on the Format tab, Custom was chosen for “Select format category.” Under Custom Format Script, enter the following code in the JavaScript Editor by clicking the Edit button (Figure 7-8): if (event.value !=="" && !isNaN(event.value)){ event.value = util.printf("%.2f%",event.value*100); }else{ event.value = ""; } Then click OK to exit. Then add a custom validation to the Validate tab. Refer to Figure 7-9. if (event.value !== "") { event.value = event.value / 100; }

Figure 7-9.  Validation script added to the Validate tab 237

Chapter 7

Format Calculations

On the Format tab, what you have done in this example is tell the field’s validation to remain blank if nothing is entered. You then tell the custom formatting to disregard items that are not numbers (NaN). Then you ask it to display in the following manner using the previous field calculation: it moves the math decimals over 2 so that you have two zeros following the code and multiply by 100. Adding the second % right after the f in the code ensures that a percent symbol will show after numbers. Leaving the first % out before the .2f creates error. Do not do this since we are creating a custom format. If you leave this second % out of the code after the f, then no percent symbol will display after the numbers. event.value = util.printf("%.2f%",event.value*100); Then the Validate tab (Figure 7-9) will be set next so that it understands between the two versions of JavaScript that 1 means 1% rather than 100%. The Validate tab custom script also ensures that the number is divided by 100 to get the percent in the correct decimals when the field is not blank. Refer to Figure 7-9. The following is the result you get when you enter a number: Addition of Percentage:  1.00%  + 1.00% =  2.00% As mentioned earlier, for the final summing field TotalPercentage, you do not need to create any custom script. You can leave it as a percentage format and use either Value or SFN in the Calculate area. Refer to Figure 7-10.

238

Chapter 7

Format Calculations

Figure 7-10.  Format tab and Calculate tab for the Total field

Note  Within the Custom Format settings and Validate tab is another example (Figure 7-8 and Figure 7-9) of a conditional or if/else statement. If/else statements set a condition. “If” the following conditions are met, do whatever is within the brackets ({ }). The other option, else, in the previous code gives the alternative. If if does not work, then do the else, which is whatever is within its brackets. As you will see, for longer conditions you will also add conditions,

239

Chapter 7

Format Calculations

else if, between the if and else, when you have more than two options. There can also be conditions within conditions, as you will see later in this chapter.For more on decimal places and separator style formatting, see the “Final Thoughts” section later in this chapter. In this example, you could set a validate range as well, to further prevent a number within the range of 0 and 100 from being entered with the input fields. Here is how that code could be expanded. See the new entry in bold. //Custom Validation if (event.value !== "") { event.value = event.value / 100 ; if (event.value 1){ app.alert("You must enter a Percentage that is between 0% and 100%"); event.value=""; } } This code was added to fields Quantity 1Percentage and Quantity 2Percentage. We will talk about app.alert later in Chapter 8, but essentially this code has a validation to prevent numbers entered outside of the 0% of 100% to be entered, and the field will reset if they are. This was done with the logical disjunction operator (||), which in this case will work only if one or more of the input values is true or out of range, in this case less than 0 or greater than 100. This is represented as 0 and 1 now that the validation and formatting has been already set. This code is placed within the current if statement.

240

Chapter 7

Format Calculations

Reset Fields with JavaScript However, you will still be able to add up a number like 200% in the final field; if that is what you want to do, that is OK. Or you can also go to the Validate tab of that field and just add this similar portion of the code as I did to the TotalPercentage field: if (event.value 1){ app.alert("You have entered a Percentage whose sum is not between 0% and 100%. The fields will reset"); this.resetForm(["Quantity 1Percentage","Quantity 2Percentage"]); event.value=""; } I also added another new line of code: this.resetForm();. Rather than using the Actions tab’s Reset a Form as I would for a reset button as in Chapters 2 and 4, you can use JavaScript to reset select fields that are placed between brackets, [], and quotes to reset. The field names in the quotes have spaces, but this is OK as long as they are within the quote marks like this: “Name of Field”. Each field is separated by a comma. This code is useful when you do not want to reset the whole form after a warning. This ensures that the user will have to enter the correct numbers this time. I have left the Subtraction example fields NumberInPercentage,Numb erOutPercentage, and TotalPercent_2 without this additional formatting if you want to compare the results with and without this kind of validation. In both examples, the Calculate tab for the total used SFN, but alternatively you could use JavaScript.

241

Chapter 7

Format Calculations

Date Formatting Date formatting is easy to do for one field. To view, refer to the “End” file of AcrobatFormatCalcTabExamples and refer to the field Quantity_1Date, which was set to the (mmm d, yyyy) format. You can set the date to a variety of options for month (mm), day (dd), and year (yyyy), with dashes for additional options for hours (hh), minutes (MM), AM/PM (tt), and a colon (:), including a custom setting. The format will display in the example area. Refer to Figure 7-11. Visit the following page to learn about cFormat string patterns: https://opensource.adobe.com/dc-acrobat-sdk-docs/library/ jsapiref/JS_API_AcroJS.html

Figure 7-11.  Selecting a format of date on the Format tab and an option 242

Chapter 7

Format Calculations

However, when it comes to adding or subtracting dates from one another, value and SFN do not work well. See the fields Quantity 1Date, Quantity 2Date, and TotalDate. fDate:    March 3, 2015     + 1.00 =    4.2015 As you can see, this math makes no sense, and trying to use two fields formatted to date to enter a number into a final text field formatted to Number can often cause errors when using value and SFN; refer to Figure 7-12.

Figure 7-12.  Examples of error warnings that happen when you try to add two fields that are formatted with dates or another format using Calculate Values or SFN Once again, you need to look at JavaScript to assist you.

243

Chapter 7

Format Calculations

Date Formatting with JavaScript Suppose that you want to create a hotel or timesheet form that deals with check-in and check-out dates for half or full days. Refer to Table 7-2 to see an example. You can also look at three fields: DateStart, DateEnd, and TotalDate_2.

Table 7-2.  Table of Formatted Dates Format Number In Date:

Number Out

Total

Mar 3, 2015 March 9, 2015 6

The Number In or DateStart field is formatted as a date. Refer to Figure 7-11. The Number Out or DateEnd field is formatted as Date as well so that it is consistent and easy to enter in the date fields using the Date Picker. With JavaScript you can use two date fields to do a calculation. The format options should be the same, for example, “mmm d, yyyy.” However, the final event field should be a Number format. Refer to Figure 7-13 and Figure 7-14.

244

Chapter 7

Format Calculations

Figure 7-13.  The setting for the DateEnd field on the Format tab is the same as the DateStart field The Total field TotalDate_2 is formatted as Number; with a custom calculation on the Calculation tab, this completes the formula. Refer to Figure 7-14 and Figure 7-15.

245

Chapter 7

Format Calculations

Figure 7-14.  Setting for the Total field on the Format tab

246

Chapter 7

Format Calculations

Figure 7-15.  Setting for the Total field on the Calculate tab The code is as follows: var sStart = getField("DateStart").value; var sEnd = getField("DateEnd").value; var dStart, dEnd, diff, days; if(sStart.length && sEnd.length) {      dStart = util.scand("mmm d, yyyy", sStart);      dEnd = util.scand("mmm d, yyyy", sEnd);

247

Chapter 7

Format Calculations

     if ( dEnd < dStart)  {           app.alert ( "The end date must be after start date and not before.");           event.value = ""; this.resetForm(["DateStart"]);      }      else{ //one day is equal to 24hours* 60minutes*60 seconds* 1000 miliseconds = 86,400,000 var oneDay = 86400000; diff = (dEnd.getTime() - dStart.getTime())/oneDay; //var days = Math.floor(diff)+1; var days = Math.round(diff)+1; event.value = days; } } else { event.value = ""; } In this example, I added a few comments to help me with the calculations. This code on the Calculate tab grabs the start date and the end date fields from the variables sStart and sEnd and gets an input value from each of them. Those values are then added into a conditional statement, which has another conditional if/else statement inside of it. The outer conditional statement if states that the solution will be a number or “else” it will be blank. However, in the outer if statement the calculation is broken down further. We see that the if makes sure that the values of start date and end date are indeed numbers. Length helps you get a number, and the 248

Chapter 7

Format Calculations

length of each variable (var sStart and var sEnd) is checked against the formatting “mmm d, yyyy.” It’s important that this is the same formatting found in the Number In and Number Out or DateStart and DateEnd fields or this calculation will not work. They are now in the new variables called dStart and dEnd. The util.scand() part of the code is a function or method that can convert any date string by using the date symbols, but it has to know the exact format of the date for this to work. In the inner if/else conditional, first a validation check is made with another alert. This is to ensure that you do not enter a start date after the end date by mistake. This would be considered an incorrect value, and you would get an alert. When you click OK to the warning message, the DateStart Field resets to the last default saved state and resets the field TotalDate_2 to blank, and then you must begin resetting the start date or end date again so that the TotalDate_2 field fills again. Likewise, in your own projects you could add a separate reset button to refresh the entire form. We saw an example of this.resetForm() earlier in the chapter. However, when both dates are correct, then you can proceed to the inner else condition. Once this is done for both fields, the end date and start date are recognized as time using the JavaScript .getTime() method. For more information, visit this page: https://developer.mozilla.org/en-US/docs/Web/JavaScript/ Reference/Global_Objects/Date/getTime With JavaScript there are many get Date-related methods available, but, in this example, we want to get the milliseconds rather than just part of a date. This returns a number in milliseconds (example: 1432672724073), which could be quite long. This is not the exact answer you want. You want to know how many days. Once the getTime of the dateStart is subtracted

249

Chapter 7

Format Calculations

from the getTime of the dateEnd, you then figure out how long one day is. In this case, one day is equal to 24 hours * 60 minutes * 60 seconds * 1000 milliseconds = 86,400,000 milliseconds. Then we divide a day of milliseconds from the result of the two dates to get our variable diff or difference. We can at this point make a choice between two different static methods. •

Math.floor() rounds down the difference to the nearest day.

•

Math.round() rounds up the difference to the nearest day.

Either of these numbers will work fine with the dates if you are accounting using half days; with a hotel, you arrive in the evening and leave in the morning. Therefore, you are not actually staying a whole two days. However, if you need to count full days, then you would write this: var days = Math.round(diff)+1; Otherwise, you can remove the “+1” from the code Giving you 6 days as in the example of Table 7-2 above rather than 7 full days. I then complete the inner else with this: event.value = days; The result now shows up in the field TotalDate_2 in the form. The files AcrobatFormatCalcTabExamples_End.pdf and Custom Format.pdf give examples. You could not have done this calculation in Acrobat without JavaScript.

250

Chapter 7

Format Calculations

Note in the code examples I wrote the two variables as follows: var sStart = getField("DateStart").value; var sEnd = getField("DateEnd").value; Likewise, I could have written it as follows: var sStart = this.getField("DateStart").value; var sEnd = this.getField("DateEnd").value; And the code would have worked the same. If you want to be stricter in your code, add this to getField. However, in the lengthy example, you may want to save space and leave it off in other lines if you must recall the variable and field elsewhere in the document. You can add this if you find your code is not acting correctly.

Time Formatting Time formatting is in many ways similar to date formatting. You can even add time to your date depending on what you intend for the field. However, time unlike the date field has no “time picker,” and you must type the numbers in yourself. So, it is important to choose the correct Time option from the list. To view, see the “End” file AcrobatFormatCalcTabExamples, and refer to the field Quantity 1Time. Refer to Figure 7-16.

251

Chapter 7

Format Calculations

Figure 7-16.  Comparison of Time and Date formatting on the Format tab

252

Chapter 7

Format Calculations

Either one can also accept a custom date or time format, which can also include hours (HH), minutes (MM), seconds (SS), and an a.m./p.m. indicator (tt). However, while they’re similar, you can use some SFN rather than JavaScript to do a simple subtraction of time, though I would ultimately recommend using JavaScript, which we will look at in a moment reusing our previous “Date” formatting code. For example, to see how using a value does not work well in the calculation area, refer to Tables 7-3 and 7-4.

Table 7-3.  Formatting Total Using Values on the Calculate Tab Format

Number In

Number Out

Total

Date:

12:15

27

39.15

In the first example, you could refer to the text fields Quality 1Time, Quality 2Time, and TotalTime, and the result makes little sense just like the Date formatting example. In the next table we try to subtract one time from another to get the total hours using the fields NumberInTime, NumberOutTime, and field TotalTime_2.

Table 7-4.  Formatting Total Using SFN on the Calculate Tab Format

Number In

Number Out

Total

Date:

04:30

15:30

11:00

Now let’s use SFN. To make this work correctly, let’s say Joe came in at 4:30 a.m. and left at 3:30 p.m. (formatted as 15:30). He therefore stayed a total of 11 hours. Both the NumberInTime and NumberOutTime fields are formatted this way: HH:MM. Refer to Figure 7-17. 253

Chapter 7

Format Calculations

Figure 7-17.  Formatting the in and out fields with time on the Format tab The TotalTime_2 field is then formatted as a number. Refer to Figure 7-18.

254

Chapter 7

Format Calculations

Figure 7-18.  Number format for the Total field on the Format tab

255

Chapter 7

Format Calculations

The last thing that is done is the SFN on the Calculate tab. Refer to Figure 7-19.

Figure 7-19.  Using SFN in the Total field on the Calculate tab NumberOutTime - NumberInTime gives you the number of hours that work was done in the day. This works with simple number formats that are in full-hour or half-­ hour increments, like 4:30 to 15:30, that add up to a full hour. However, that is not how the time is accurately calculated such as when you are working with certain times like subtracting 1:30 a.m. from 12 p.m. You can see what happens to the time using SFN. Now let’s look at an example of how to reuse the Date code we created earlier for Time.

T ime Formatting with JavaScript, a Custom Example This time with the code, let’s rewrite parts of the code. First, however, I will point out something I discovered. The code that I am going to show you does not work directly with the formatting of time and throws a few errors 256

Chapter 7

Format Calculations

when I try to modify it. However, you can get around this issue and create a custom time and date using the format of Date and then just modify specific areas of the code. In this example, make sure that your NumberInTime and NumberOutTime fields are formatted to a custom date of “mm/dd/yyyy HH:MM tt.” Refer to Figure 7-20.

Figure 7-20.  Using the Date format to set a custom time Thankfully, the Date format allows us to add HH for hours, MM for minutes, ss for seconds, and tt for the a.m./p.m. indication. Make sure that your TotalTime_2 field is formatted to Number. This time, on the Calculate tab, enter this code. Refer to Figure 7-21.

257

Chapter 7

Format Calculations

Figure 7-21.  Using the Date format to set a custom time Here is the time script: //Time Script var sStart = getField("NumberInTime").value; var sEnd = getField("NumberOutTime").value; var dStart, dEnd, diff, hours; if(sStart.length && sEnd.length) {      dStart = util.scand("mm/dd/yyyy HH:MM tt", sStart);      dEnd = util.scand("mm/dd/yyyy HH:MM tt", sEnd);      if ( dEnd < dStart)  {           app.alert ( "The end date must be after start date and not before.");           event.value = ""; this.resetForm(["NumberInTime","NumberOutTime"]);      }      else{ //one day is equal to 24hours* 60minutes*60 seconds* 1000 milliseconds = 86,400,000 258

Chapter 7

Format Calculations

// hours is 3,600,000 var oneHour = 3600000; diff = (dEnd.getTime() - dStart.getTime())/oneHour; //var hours = Math.floor(diff); var hours = Math.round(diff); event.value = hours; } } else { event.value = ""; } In this example, I was just rounding the numbers or in this case the hours. I changed the numbers from 86,400,000 to 3,600,000, which would also help me to figure out how many hours there might be in a day or maybe several days since with dates I can use the date picker. Refer to Figure 7-22 for an example of how this looks.

Figure 7-22.  Fields set with a custom date and time You can also write the variable hours without Math.round if you want a more accurate time number when dealing with half hours or other times. var hours = diff; Or if you want to round the nearest half-hour, you could write this: var hours = Math.round(diff*2)/2; You can refer to this code in my file A­ crobatFormatCalcTabExamples_ End_CustomFormat.pdf.

259

Chapter 7

Format Calculations

Comb of Characters for Dates You can also format your dates using a comb of characters, as found on the Options tab. This can be useful when setting a custom option under the date or even time. However, be aware that depending on the format you choose or create, you need to account for the dashes as well as any spacing. In this case, I added a border on the Appearance tab and on the Options tab set the comb of characters to 10. Refer to Figure 7-23 and Figure 7-24.

Figure 7-23.  Setting a comb of characters for a date format using the Format and Appearance tabs 260

Chapter 7

Format Calculations

Figure 7-24.  Setting a comb of characters for a date format using the Options tab

Special Formatting You can use the Special formatting option to set your ZIP code, phone number, Social Security number, and arbitrary mask (but not additional JavaScript); we will look at this area again in Chapter 11. Refer to Figure 7-25.

261

Chapter 7

Format Calculations

Figure 7-25.  Setting for Special formatting

Final Thoughts As you can see from the formatting examples covered in this chapter, sometimes you will use value and SFN. However, in some cases, they will not give you the results you want. If the calculation becomes complicated or scientific, you may need to look for a custom JavaScript to assist you or look at how you can reuse your code to solve a problem in another field when one type of formatting does not work.

262

Chapter 7

Format Calculations

Drop-Down Alternatives As in Chapter 2 and Chapter 6, there is a drop-down alternative in this chapter’s folder if your clients are required to enter very specific values. I have supplied an example that includes some modified code to work with the drop-down lists and the Total text field’s Calculate tab. Refer to the file AcrobatFormatCalcTabExamples_End_DDown.pdf.

 ore Information on Adding Decimal Places M and Leading Zeros Earlier in the chapter we looked at some code with added decimal places when it came to percents. if (event.value !=="" && !isNaN(event.value)){ event.value = util.printf("%.2f%",event.value*100); }else{ event.value = ""; } In that example, we only used that Format code without the validation, and we moved the decimal places over two places after the decimal point, written as (%.2f%). This code by itself would give the number 100.00%. By altering the following section of code: event.value = util.printf("%.1f%",event.value*100); you would then get 100.0% or only one decimal place. Finally, if you added numbers, before the decimal point, like so: event.value = util.printf("%08.0f%",event.value*100);

263

Chapter 7

Format Calculations

you would get 00000100% when you enter a 1. This moves the numbers over to eight places before the decimal, and in this case there are no decimal points. Try this with a similar line of code and observe how the leading zero changes. Keep this in mind with your current percent calculation between the Format and Validate tab code. event.value = event.value / 100 ; So, when you create your own calculations, you will not run into unusual formatting errors. If you need to use commas as a separator or another separator that was in the drop-down percent separator style list, instead you can write the line of code by adding a comma after the first percentage and then a number like 2 before the dot. You will get 100,00% or with longer numbers 120.000,00%. The second example uses a 0 and will add the comma first like 100,000.00%. event.value = util.printf("%,2.2f%",event.value*100); or event.value = util.printf("%,0.2f%",event.value*100); You can use the numbers 0–4 to access separator options in the list for number or percent formats. Just make sure to add the comma before the number choice, as shown in in the previous lines. If you do not add this code as in the earlier percent examples, 1 (decimal place only) appears to be the default format.

S  ummary In this chapter, you focused on using the Format tab while working in either text fields or drop-down lists.

264

Chapter 7

Format Calculations

You looked at formatting using the following: •

None

•

Number

•

Percentage

•

Date

•

Time

•

Special

•

Custom

While Acrobat has some automatic solutions for some formats, in this case you needed to create a calculation using value, SFN, or JavaScript to get the results you wanted. Sometimes you must use a combination of formats. You also looked at how custom formatting interacted with code on the Validate tab. In Part III, you’ll look at the Validate tab in more detail. In the next chapter, you’ll look at how you can add various alerts to your document using JavaScript and add some JavaScript to buttons that will create notes and time stamps.

265

CHAPTER 8

Various JavaScript Alerts, Notes, and Time Stamps Chapter Goal: In this chapter you’ll work with alerts that may or may not be part of a form. You’ll also create comment notes and add a signature and time stamp. As you have seen in previous chapters, JavaScript is useful for forms when you want to do calculations. However, sometimes you want to accomplish things that are non-­ form-­related. In this chapter, you’ll create an alert that welcomes a person when they open your PDF newsletter or catalog, like the one in Figure 8-1.

© Jennifer Harder 2023 J. Harder, Enhancing Adobe Acrobat Forms with JavaScript, https://doi.org/10.1007/978-1-4842-9470-3_8

267

Chapter 8

Various JavaScript Alerts, Notes, and Time Stamps

Figure 8-1.  An informational message that appears when someone opens the newsletter PDF file

Note  If you want to work along in this lesson or review the final result, download the Chapter 8 files from the link in the introduction. The file with the label “Start” is the file without the code, and the file with the label “End” is the final result. You will also find a folder containing the original scripts if you would like to add them to your own PDF forms. If you are creating your form from an original PDF, refer to the “Forms Review” section in Chapter 1. Remember that to view the properties of a field, you must select the Prepare Form tool; only then can you right-click or double-­click a field to review its properties.

268

Chapter 8

Various JavaScript Alerts, Notes, and Time Stamps

Alert Types JavaScript has at least four alert types that you can use to alert your clients to an event. It also has four button types that you can choose from. Figure 8-1 shows the info or status type. I chose this because I did not want to scare the person with a warning, which this is not. It is more of a greeting. Table 8-1 provides a breakdown of the alerts with icon and button type.

Table 8-1.  Alert Types #

Icon Type

0

#

Button Type

0 Error

1

1 Warning

2

2 Question

3

3 Status/Info

4

No Icon

4

Returns to default

To achieve this alert example, you need to add it globally, which means it is part of the whole document. When the document opens, you want to see this alert. To do that, you need to go to the JavaScript tool in the Tools menu. Refer to Figures 8-2 and 8-3.

269

Chapter 8

Various JavaScript Alerts, Notes, and Time Stamps

Figure 8-2.  The JavaScript tool

Create a Document JavaScript Now you need to choose Document JavaScripts from the JavaScript menu (Figure 8-3). To view, refer to the Newsletter_2_End.pdf in this chapter’s file folder. If want to practice, then use the file Newsletter_2_Start.pdf.

Figure 8-3.  The JavaScript menu When you first start creating your JavaScript for the document, the Document JavaScripts dialog box will appear blank. No JavaScripts have been created, so you’ll need to follow these steps: 1. Type in a script name. Refer to Figure 8-4. In this example, I typed welcome.

270

Chapter 8

Various JavaScript Alerts, Notes, and Time Stamps

Figure 8-4.  The Document JavaScripts dialog box 2. Click the Add button on the right. Refer to Figure 8-5.

Figure 8-5.  The Add button

271

Chapter 8

Various JavaScript Alerts, Notes, and Time Stamps

3. In this example, upon entering the JavaScript Editor dialog box, you can highlight and delete the default text and then type the following script: //Welcome Message on start app.alert("Welcome to our Newsletter!",3,0); The first line with the //, as mentioned earlier, is a comment. It has nothing to do with the function of the code; it is just a reminder of what the code is about. The real code look like this: app.alert("Welcome to our Newsletter!",3,0); This code is calling up an alert message. Within this app.alert(), you can put your custom text (“Welcome to our Newsletter!”) in this example. Then you choose what type of icon and button you want to appear; they are separated by commas. Refer to Figure 8-6.

272

Chapter 8

Various JavaScript Alerts, Notes, and Time Stamps

Figure 8-6.  The removed code and new code and message typed into the JavaScript Editor •

3 refers to the Alert Icon type (in this case Status/ Info). Refer to Table 8-1.

•

0 refers to the Button type (in this case, the OK button).

Depending upon the type of alert, you might choose other options.

273

Chapter 8

Various JavaScript Alerts, Notes, and Time Stamps

4. Click the OK button in the editor when done typing and click Close to exit the Document JavaScripts dialog box. Click the Close button to exit the JavaScript tool. Then save your work. 5. After you close the PDF and open it again, the alert should pop up. Click OK to the message, and the document opens.

Viewer Version and Validation Alert Let’s say you want to make sure that your customer’s version of Reader is up-to-date enough to accomplish certain tasks. You might create and add your own Viewer validation script such as viewerVersion. Refer to Figure 8-7. This example is also found in the file Newsletter_2_End.pdf under JavaScript Tool Document JavaScripts.

274

Chapter 8

Various JavaScript Alerts, Notes, and Time Stamps

Figure 8-7.  Document JavaScript dialog box displaying three scripts used in the Newsletter PDF //What version of Acrobat if (typeof(app.viewerVersion)!="undefined") if (app.viewerVersion