Adobe Document Server Developers Guide

Version 6.0

ADOBE SYSTEMS INCORPORATED Corporate Headquarters 345 Park Avenue San Jose, CA 95110-2704 (408) 536-6000 http://www.adobe.com Release

Adobe® Document Server Software Developers’ Kit December 19, 2003 Copyright 2003 Adobe Systems Incorporated. All rights reserved. Adobe® Document Server 6.0 Developers Guide for Sun™ Solaris™ and Microsoft® Windows® If this guide is distributed with software that includes an end user agreement, this guide, as well as the software described in it, is furnished under license and may be used or copied only in accordance with the terms of such license. Except as permitted by any such license, no part of this guide may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written permission of Adobe Systems Incorporated. Please note that the content in this guide is protected under copyright law even if it is not distributed with software that includes an end user license agreement. The content of this guide is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in the informational content contained in this guide. Please remember that existing artwork or images that you may want to include in your project may be protected under copyright law. The unauthorized incorporation of such material into your new work could be a violation of the rights of the copyright owner. Please be sure to obtain any permission required from the copyright owner. Any references to company names in sample templates are for demonstration purposes only and are not intended to refer to any actual organization. Adobe, the Adobe logo, Adobe Caslon, Adobe Garamond, Adobe Jenson, Acrobat, Acrobat Reader, FrameMaker, Distiller, GoLive, Illustrator, ImageReady, InDesign, Kozuka Gothic, Kozuka Mincho, Minion, Myriad, Photoshop, PostScript, and XMP are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. Apple, Mac, Macintosh, Power Macintosh and TrueType are trademarks of Apple Computer, Inc., registered in the United States and other countries. Microsoft, Windows, Windows NT, and OpenType are either a registered trademark or a trademark of Microsoft Corporation in the United States and other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc. Sun, Solaris, Java, Java Applet, Java Servlet, and JavaScript are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. UNIX is a registered trademark of The Open Group. X Window System is a trademark of The Open Group. All other trademarks are the property of their respective owners. © 1989 All Rights Reserved by Proximity Technology Inc. Proximity and Linguibase are registered trademarks of Proximity Technology Inc. The Proximity/Merriam-Webster Database © 1984-1990 Merriam-Webster Inc. © 1990 - All Rights Reserved. This product includes software developed by the Apache Software Foundation (http://www.apache.org). © 1998-2001 The Apache Group. All rights reserved. © 1995-2001 International Business Machines Corporation and others. All rights reserved. © 1990 David Koblas. Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted. This software is provided “as is” without express or implied warranty. © 1994 Anthony Dekker. This product includes code licensed from RSA Security, Inc. Some portions licensed from IBM are available at http://oss.software.ibm.com/icu4J . Copyright© 1990, RSA Data Security, Inc. All rights reserved. License to copy and use this software is granted provided that it is identified as the “RSA Data Security, Inc. MD5 Message-Digest Algorithm” in all material mentioning or referencing this software or function. License is also granted to make and use derivative works provided that such works are identified as ‘derived from the RSA Data Security, Inc. MD5 Message-Digest Algorithm’ in all material mentioning or referencing the derived work. RSA Data Security, Inc. makes no representations concerning either the merchantability of this softare or the suitability of this software for any particular purpose. It is provided “as is” without express or implied warranty of any kind. These notices must be retained in any copies of any part of this documenation and/or software. Copyright© 1994-1996 SunSoft Inc. Rights Reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL SUNSOFT, INC. OR ITS PARENT COMPANY BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Except as contained in this notice, the name of SunSoft, Inc. shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without written notice. License Language:ICU License - ICU 1.8.1 and later COPYRIGHT AND PERMISSION NOTICE Copyright (c) 1995-2003 International Business Machines Corporation and others All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, provided that the above copyright notice(s) and this permission notice appear in all copies of the Software and that both the above copyright notice(s) and this permission notice appear in supporting documentation. THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization of the copyright holder.

2 (1) University of California, Berkeley Copyright© 1990 The Regents of the University of California. All rights reserved. Redistribution and use in source and binary forms are permitted provided that the above copyright notice and this paragraph are duplicated in all such forms and that any documentation, advertising materials, and other materials related to such distribution and use acknowledge that the software was developed by the University of California, Berkeley. The name of the University may not be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED “AS IS” AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. (2) DJ Delorie Copyright© 1991 DJ Delorie, 24 Kirsten Ave, Rochester NH 03867-2954 This file is distributed under the terms listed in the document “copying.dj”, available from DJ Delorie at the address above. A copy of “copying.dj” should accompany this file; if not, a copy should be available from where this file was obtained. This file may not be distributed without a verbatim copy of “copying.dj”. This file is distributed WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. (3) David M. Gay at AT&T The author of this software is David M. Gay. Copyright© 1991 by AT&T. Permission to use, copy, modify, and distribute this software for any purpose without fee is hereby granted, provided that this entire notice is included in all copies of any software which is or includes a copy or modification of this software and in all copies of the supporting documentation for such software. THIS SOFTWARE IS BEING PROVIDED “AS IS”, WITHOUT ANY EXPRESS OR IMPLIED WARRANTY. IN PARTICULAR, NEITHER THE AUTHOR NOR AT&T MAKES ANY REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE. Hewlett-Packard Copyright© 1986 HEWLETT-PACKARD COMPANY To anyone who acknowledges that this file is provided “AS IS” without any express or implied warranty: permission to use, copy, modify, and distribute this file for any purpose is hereby granted without fee, provided that the above copyright notice and this notice appears in all copies, and that the name of Hewlett-Packard Company not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. Hewlett-Packard Company makes no representations about the suitability of this software for any purpose. Unless otherwise stated in each remaining newlib file, the remaining files in the newlib subdirectory are governed by the following copyright. Copyright©1994, 1997 Cygnus Solutions. All rights reserved. Redistribution and use in source and binary forms are permitted provided that the above copyright notice and this paragraph are duplicated in all such forms and that any documentation, advertising materials, and other materials related to such distribution and use acknowledge that the software was developed at Cygnus Solutions. Cygnus Solutions may not be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED “AS IS” AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF General Terms and Conditions page 9 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Copyright© 1996 Silicon Graphics Computer Systems, Inc. Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting Documentation. Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110-2704, USA. Notice to U.S. Government End Users. The Software and Documentation are “Commercial Items,” as that term is defined at 48 C.F.R. §2.101, consisting of “Commercial Computer Software” and “Commercial Computer Software Documentation,” as such terms are used in 48 C.F.R. §12.212 or 48 C.F.R. §227.7202, as applicable. Consistent with 48 C.F.R. §12.212 or 48 C.F.R. §§227.7202-1 through 227.7202-4, as applicable, the Commercial Computer Software and Commercial Computer Software Documentation are being licensed to U.S. Government end users (a) only as Commercial Items and (b) with only those rights as are granted to all other end users pursuant to the terms and conditions herein. Unpublished-rights reserved under the copyright laws of the United States. For U.S. Government End Users, Adobe agrees to comply with all applicable equal opportunity laws including, if appropriate, the provisions of Executive Order 11246, as amended, Section 402 of the Vietnam Era Veterans Readjustment Assistance Act of 1974 (38 USC 4212), and Section 503 of the Rehabilitation Act of 1973, as amended, and the regulations at 41 CFR Parts 60-1 through 60-60, 60-250, and 60-741. The affirmative action clause and regulations contained in the preceding sentence shall be incorporated by reference.

3 4 Contents

Preface ...... 23

Part I: Basics

Chapter 1 Overview of Adobe Document Server...... 27

Product Summary ...... 27 ADS Commands ...... 27 ADS Requests ...... 28 Manipulating Graphics Input...... 28 Manipulating Documents...... 29 Manipulating Metadata ...... 29 Format Summary ...... 30 Input, Output, and Metadata Formats ...... 30 Format Conversions ...... 32 Web-Related Standards and Formats ...... 33

Chapter 2 Invoking ADS ...... 35

Deploying and Invoking ADS ...... 35 The Interface Model ...... 37 The Objects in the Model ...... 37 Interacting with ADS ...... 37 Details of the Objects in the Model...... 39 Server Objects in the APIs...... 39 Requests ...... 40 Results and Responses...... 41 Logging ...... 42 How ADS Handles URIs ...... 43 Base URIs for the APIs ...... 44 Base URIs for the Command Line ...... 44 Base URIs for an ADS Process...... 45 Base URI Summary ...... 46

Adobe Document Server Developers Guide Dec 19, 2003 5 Contents

Chapter 3 ADS Command Basics ...... 47

Overview ...... 47 Content Holders and Types ...... 48 How Content Becomes Current ...... 49 How Content Holders Work ...... 50 Content Types and File Formats ...... 51 Loading Content ...... 53 Specifying Input Data ...... 53 How File Formats Map to Content Types Upon Load...... 55 Converting Content ...... 57 Direct Content Type Conversions ...... 57 Commands That Work on One Content Type but Produce Another ...... 58 Saving Content ...... 59 Determining Where Result Content is Saved...... 59 Naming Results ...... 60 Basic File Saving ...... 61 Saving to Optimized Formats ...... 63 Automatic File Saving ...... 64 Referenced Attributes Values ...... 65 General Commands ...... 66

Chapter 4 Working with File Metadata ...... 67

Overview of Metadata...... 67 Metadata and Content Types ...... 67 Creating a Custom Metadata Schema ...... 68 Working with Metadata in ADS ...... 69 Extracting Metadata from Loaded Content...... 69 Modifying Metadata in Loaded Content ...... 74 Saving Files with Metadata ...... 77 Transformations of Metadata Formats...... 78 Supported Metadata Formats ...... 78 Metadata Namespaces ...... 80 Metadata Aliases ...... 81 Automatic Metadata Updates ...... 82 Resolving Metadata Inconsistency ...... 83

6 Dec 19, 2003 Adobe Document Server Developers Guide Contents

Part II: Graphics

Chapter 5 Basic Image Manipulations ...... 87

Overview ...... 87 Sizing and Cropping Images ...... 88 Changing the Canvas Size ...... 88 Changing Image Size...... 90 Layer Manipulations ...... 95 Referring to Layers ...... 95 Setting Layer Visibility and Opacity...... 96 Flattening Layers ...... 97 Layers in Images from Other Formats ...... 98 Layer and Layer Set Support in Versions of Photoshop ...... 98 Working with Color...... 99 Manipulating Color Profiles Directly ...... 99 Color Profiles in Other Operations ...... 101 Color Space Support in ADS ...... 102 Modifying Image Data...... 103 Changing Image Orientation...... 103 Replacing All or Part of an Image ...... 104 Replacing Text in an Image ...... 106 Changing Colors in an Image ...... 107 Controlling Visual Quality...... 108 Accessing Raster Content...... 109 Retrieving Image Information ...... 109 Setting Elements of an Image ...... 110 Treating PostScript and PDF Content as Images ...... 112 Saving Optimized Files ...... 112 Tuning Optimization Settings Outside ADS ...... 112 Tuning Optimization Settings in ADS ...... 113 Balancing Quality and Size in Optimized Image Files ...... 115 Changing the Image File Size ...... 115 Saving Metadata with Optimized Files...... 116 Custom Color Palettes in Optimized Files ...... 117 Saving Dynamic PSD and Animated GIFs ...... 117 Legacy File Limitations ...... 118

Adobe Document Server Developers Guide Dec 19, 2003 7 Contents

Chapter 6 Changing Text in Images ...... 119

Changing Text in Images ...... 119 Replacing Text in Raster Content ...... 120 Replacing Text in an SVG Text Flow...... 121 Changing Text Attributes in Text Flows ...... 123 The Structure of a Text Flow ...... 123 Setting Text Characteristics...... 127

Chapter 7 Replacing Variables in SVG and PSD Files ...... 131

Overview of Variable Binding and Replacement ...... 131 Automatic Variable Replacement...... 133 Replacing Variables Explicitly ...... 134 Specifying Replacement Data ...... 136 Variable Replacement Error Behavior ...... 136 SVG Variable Replacement Syntax ...... 136 PSD Variable Replacement Syntax ...... 141

Chapter 8 Operations Specific to SVG Files...... 145

Overview ...... 145 Foreign Objects ...... 145 Graph Foreign Object ...... 146 Text Flow Foreign Object ...... 147 Image Replacement Foreign Objects ...... 147 SVG Font Considerations ...... 148 Embedded Fonts in SVG...... 148 Resolving Font References within SVG...... 148 Illustrator SVG Template Tips ...... 149 Naming Shapes and Layers ...... 149 Using Crop Marks ...... 150 Saving SVG for ADS Compatibility ...... 150 Converting SVG to Raster...... 151 Converting SVG to PDF ...... 151

8 Dec 19, 2003 Adobe Document Server Developers Guide Contents

Chapter 9 Creating Dynamic Graphs in SVG Files ...... 153

Overview ...... 154 A Working Sample ...... 155 Graphing Basics ...... 158 Parts of a Graph ...... 158 Basic Graph Types...... 158 Graph Objects in ADS ...... 159 Graph Formatting Overview ...... 160 Graph Layout...... 160 Stacking Options ...... 161 Graph Type-Specific Formatting Options ...... 161 Specific Graph Types ...... 162 ADS Graphing Features Not Supported by Illustrator ...... 163 General Graph Layout ...... 163 Legends ...... 164 String Substitutions in Axis and Legend Labels ...... 165 Ticks and Labels ...... 165 Axes ...... 165 Maps ...... 165 Transformations...... 166 ADS Features Applicable to All Graph Types ...... 166 Stacking and Normalizing ...... 166 Accumulating Graph Points ...... 167 Multiple Graph Descriptions ...... 167 ADS Graph Features by Graph Type ...... 167 Bar Graph Features ...... 167 Point Graph Features...... 168 Editing Exported Templates ...... 168 Data Sets ...... 169 The Impact of Maps on Graph Data ...... 169 Properties for Graph Data...... 171 XML Representation of Graph Data ...... 172 The Data Element ...... 172 Abbreviated Graph Data Syntax...... 178 Formatting a Graph ...... 179 Graphing Data Columns ...... 181 Major and Minor Data Columns ...... 181 Sample Graph Format ...... 184

Adobe Document Server Developers Guide Dec 19, 2003 9 Contents

Chapter 9 Creating Dynamic Graphs in SVG Files (Continued)

Graph Transformations (Xforms) ...... 186 The what and which Elements...... 186 Graph Designs and the symbol Element ...... 188 String Substitutions ...... 189 Strict and Lenient Graphing Modes ...... 192 Graph and XML Examples ...... 192 SVG Template ...... 192 Polar Pie Graph ...... 194 Accumulation and Multiple Graph Descriptions ...... 197 Applying a New Data Element ...... 200 String-Labelled Minor Axis ...... 201 Graph with Conflicting Data ...... 204 Applying a New Format ...... 207 Graph Design ...... 209 Graphing Template Guidelines ...... 213

Part III: Documents

Chapter 10 Creating PDF Files from XSL-FO ...... 217

Overview ...... 217 Supported Elements and Attributes ...... 218 Formatting With a FrameMaker Template ...... 219 Identifying the Template ...... 219 Defining the Master Pages ...... 221 Defining Formats ...... 222 Formatting the XSL-FO Content ...... 223 Verifying the Formatting Results ...... 224 Creating a Table of Contents...... 225 Creating Tagged PDF Documents ...... 228 Creating Running Headers and Footers ...... 229 Development Considerations ...... 230

10 Dec 19, 2003 Adobe Document Server Developers Guide Contents

Chapter 10 Creating PDF Files from XSL-FO (Continued)

Formatting Without a FrameMaker Template ...... 232 Defining the Master Pages ...... 232 Formatting Text ...... 234 Using Leaders and Rules ...... 235 Creating Running Headers and Footers ...... 236 Balancing Text Across Columns ...... 237 Generating Page # of ## Folios...... 238 Common Formatting Tasks ...... 239 Referencing Other Content Holders ...... 239 Embedding Graphics...... 239 Defining Variables ...... 240 Specifying XMP Metadata...... 242

Chapter 11 Controlling Document Security ...... 245

Encrypting PDF Documents ...... 245 Encryption Passwords ...... 246 Encryption Examples...... 248 Decrypting PDF Documents ...... 249 Usage Rights ...... 251 Setting Usage Rights ...... 251 Usage Rights in Encrypted Documents ...... 253 Retrieving Usage Rights ...... 255

Chapter 12 Manipulating PDF Features ...... 257

Annotations ...... 257 Annotation Types that ADS Supports ...... 257 Comments ...... 261 Links ...... 266 Bookmarks ...... 269 Exporting Bookmarks ...... 270 Thumbnails...... 271 Updating Thumbnails ...... 271 Deleting Embedded Thumbnails ...... 272 File Attachments ...... 273 Importing File Attachments ...... 274 Exporting File Attachments ...... 276 Deleting File Attachments ...... 277

Adobe Document Server Developers Guide Dec 19, 2003 11 Contents

Chapter 13 Working with PDF Form Fields ...... 279

Overview ...... 279 Filling In Form Field Data ...... 281 Setting Text Field Values Directly ...... 281 Importing and Exporting Form Data ...... 281 Controlling Form Field Appearance ...... 283 Controlling Field Accessibility ...... 286 Controlling the Visibility of a Form Field...... 286 Controlling Write Access for a Form Field ...... 287 Flattening Form Fields ...... 287 Deleting Form Fields ...... 289

Chapter 14 Manipulating Pages and Documents ...... 291

Deleting Pages ...... 292 Adding Pages ...... 294 Forcing an Even Number of Pages ...... 294 Spawning Pages from Templates ...... 294 Combining Documents ...... 296 Inserting One Document into Another ...... 296 Combining Multiple Documents into One ...... 298 Creating and Inserting a Table of Contents ...... 303 Changing Document Layout...... 306 Rotating Pages...... 306 Comparing the Overlay Commands ...... 307 Applying Page Overlays ...... 308 Applying Template Overlays ...... 311 Renumbering Page Labels ...... 315

Chapter 15 Converting and Saving PDF Documents ...... 319

Overview ...... 319 Converting Between Document Formats...... 320 Converting Between PDF and Image Formats ...... 321 Saving Optimized PDF Content ...... 322

Appendix A Example-to-Sample Mapping ...... 323

Index ...... 331

12 Dec 19, 2003 Adobe Document Server Developers Guide List of Figures

Figure 2.1 Deployment and invocation choices for ADS ...... 36 Figure 6.1 XML structure of text flows in Raster and SVG content ...... 123 Figure 9.1 A graph template created in Illustrator ...... 155 Figure 9.2 The Illustrator Variables palette ...... 156 Figure 9.3 A graph template with variables inserted ...... 157 Figure 9.4 Sample sales data set ...... 169 Figure 9.5 Sample grades data set ...... 170 Figure 9.6 Command line variable substitution ...... 179 Figure 9.7 Sample contractor data set ...... 183 Figure 9.8 Polar pie graph ...... 194 Figure 9.9 Multiple graph description, accumulation, and substitution ...... 197 Figure 9.10 Applying a new data element ...... 200 Figure 9.11 Minor axis with string labels ...... 201 Figure 9.12 Graphing conflicting data points separately ...... 204 Figure 9.13 New graph format ...... 207 Figure 9.14 Interstate graph design ...... 209 Figure 12.1 The XML schema for links in PDF content ...... 267

Adobe Document Server Developers Guide Dec 19, 2003 13 List of Figures

14 Dec 19, 2003 Adobe Document Server Developers Guide List of Tables

Table 1.1 Input file formats allowed by ADS ...... 30 Table 1.2 Output file formats produced by ADS ...... 31 Table 1.3 Metadata formats supported and preserved by ADS ...... 32 Table 1.4 Direct content type conversions supported by ADS ...... 32 Table 2.1 Deployment and invocation choices for ADS ...... 35 Table 2.2 Details of invocation choices for invoking ADS ...... 36 Table 2.3 The object model of the ADS interfaces ...... 37 Table 2.4 Steps involved in interacting with ADS ...... 38 Table 2.5 Kinds of server objects in the APIs ...... 40 Table 2.6 The kinds of information in an ADS request ...... 41 Table 2.7 Log levels and their meaning ...... 42 Table 2.8 Supported URI schemes ...... 44 Table 2.9 Base URIs for the ADS interfaces ...... 46 Table 3.1 How content types relate to input and output formats ...... 52 Table 3.2 Specifying input data sources in the loadContent command ...... 54 Table 3.3 Loading file data with the loadContent command ...... 55 Table 3.4 Direct content type conversions ...... 57 Table 3.5 Commands that work on one content type and produce another ...... 58 Table 3.6 Determining the result location ...... 59 Table 3.7 Saving content with the saveContent command ...... 61 Table 3.8 Saving content with the saveOptimized command ...... 63 Table 3.9 File extensions used by the saveOptimized command ...... 63 Table 4.1 Supported metadata formats ...... 79 Table 4.2 Preregistered namespaces ...... 80 Table 4.3 Metadata fields modified by ADS ...... 82 Table 4.4 Metadata format precedence for file types ...... 83 Table 5.1 Color space support for image formats ...... 102 Table 5.2 Photoshop feature introductions ...... 118 Table 5.3 ImageReady feature introductions ...... 118 Table 5.4 Illustrator feature introductions ...... 118 Table 5.5 GoLive feature introductions ...... 118 Table 6.1 Summary of elements and attributes in PSD and SVG text flows ...... 125

Adobe Document Server Developers Guide Dec 19, 2003 15 List of Tables

Table 9.1 Allowed string substitutions ...... 190 Table 12.1 Annotation types and operations supported by ADS ...... 258 Table 13.1 Form field properties you can change in ADS ...... 280 Table 14.1 Comparing the overlayPages and overlayTemplates commands ...... 307 Table A.1 Examples in this document that map to working samples ...... 323

16 Dec 19, 2003 Adobe Document Server Developers Guide List of Examples

Example 3.1 Using a content reference to select an image at run time ...... 66 Example 4.1 Metadata from IPTC format ...... 70 Example 4.2 Metadata from EXIF format ...... 72 Example 4.3 XMP Metadata in a PDF file ...... 73 Example 4.4 Modifying a metadata property ...... 74 Example 4.5 Creating and adding to a structured property ...... 75 Example 4.6 Streaming in replacement metadata in the importMetadata command ...... 76 Example 4.7 Loading replacement metadata from a file ...... 76 Example 4.8 Copying metadata from one file to another...... 77 Example 4.9 Saving an optimized image with a new metadata property...... 78 Example 5.1 Increasing canvas size by adding a border ...... 89 Example 5.2 Trimming an image ...... 89 Example 5.3 Applying a clipping path...... 90 Example 5.4 Making successive size modifications on the same image...... 91 Example 5.5 Changing the resolution of an image ...... 91 Example 5.6 The effects of attempted size changes on different images ...... 93 Example 5.7 Resizing an image and sharpening edges ...... 95 Example 5.8 Setting layer and layer-set visibility ...... 97 Example 5.9 Setting layer opacity ...... 97 Example 5.10 Converting image data to a color profile...... 101 Example 5.11 Rotating an image ...... 103 Example 5.12 Replacing pixels to add a product shot to an image ...... 105 Example 5.13 Duplicating one pixel layer out of several layers ...... 105 Example 5.14 Applying a layer effect by replacing pixels...... 105 Example 5.15 Replacing a color overlay in an image layer ...... 107 Example 5.16 Automatically adjusting contrast in an image ...... 108 Example 5.17 Using the set command to change copyright information for an image ...... 111 Example 5.18 Copying a value from one Raster content holder to another ...... 111 Example 5.19 Setting an optimization attribute ...... 113 Example 5.20 Changing the preferred optimization format with set ...... 114 Example 5.21 Choosing an optimization format automatically ...... 114 Example 5.22 Adjusting the quality of an optimized file ...... 115

Adobe Document Server Developers Guide Dec 19, 2003 17 List of Examples

Example 5.23 Creating a smaller image file ...... 116 Example 6.1 Replacing all text in a layer ...... 120 Example 6.2 Replacing specific text in a layer ...... 120 Example 6.3 Replacing the automatic text variable value ...... 121 Example 6.4 Replacing text in an SVG text flow...... 122 Example 6.5 Replacing an entire text flow in SVG content ...... 122 Example 6.6 Changing a font size ...... 128 Example 6.7 Changing the fill color for text ...... 128 Example 6.8 Changing the overlay color in a text layer ...... 128 Example 6.9 Replacing an entire text flow in Raster content ...... 129 Example 6.10 Replacing text flow attributes in SVG content ...... 130 Example 7.1 Automatic variable replacement on load ...... 134 Example 7.2 Automatic variable replacement from the command line ...... 134 Example 7.3 Loading multiple data sets for a single template file ...... 135 Example 7.4 Streaming in replacement data...... 135 Example 7.5 Basic variable replacement ...... 137 Example 7.6 Replacing a visibility variable ...... 138 Example 7.7 Replacing an image variable with an image file reference...... 138 Example 7.8 Replacing an image variable with embedded image data...... 138 Example 7.9 Replacing a graph variable ...... 139 Example 7.10 Abbreviated graph syntax data...... 140 Example 7.11 Replacing text using a text variable ...... 140 Example 7.12 Replacing text attributes using a text variable ...... 140 Example 7.13 Replacing a visibility variable ...... 141 Example 7.14 Replacing a text variable ...... 142 Example 7.15 Replacing a pixel variable using a file reference ...... 142 Example 7.16 Replacing a pixel variable with an embedded image ...... 142 Example 7.17 Replacing the default text variable ...... 143 Example 9.1 XML structure of the switch element ...... 159 Example 9.2 The values element ...... 172 Example 9.3 The propertyRow element...... 173 Example 9.4 A property element that defines units ...... 173 Example 9.5 An explicit map element ...... 174 Example 9.6 The globalMap element ...... 174 Example 9.7 A complete data element ...... 174 Example 9.8 Mapped values for data ...... 175

18 Dec 19, 2003 Adobe Document Server Developers Guide List of Examples

Example 9.9 A generated map ...... 176 Example 9.10 A data element with an explicit map ...... 176 Example 9.11 A data element with an implicit map ...... 177 Example 9.12 Command line variable substitution ...... 178 Example 9.13 The basic structure of the format element...... 180 Example 9.14 Graphing conflicting values separately...... 183 Example 9.15 A complete graph element for a bar graph ...... 184 Example 9.16 Changing point markers with the what element...... 186 Example 9.17 Changing all point markers for the second series ...... 187 Example 9.18 Changing point markers for the first cluster...... 187 Example 9.19 Changing all point markers ...... 187 Example 9.20 Set operations on what elements ...... 187 Example 9.21 A symbol definition for a graph design...... 189 Example 9.22 Basic string substitution ...... 189 Example 9.23 String substitution with a global units property ...... 189 Example 9.24 Column-specific substitution of a units property ...... 189 Example 9.25 Map string substitution ...... 190 Example 9.26 SVG template for samples ...... 193 Example 9.27 XML load and save...... 193 Example 9.28 XML code for a pie graph ...... 194 Example 9.29 XML code for the multiple graph figure ...... 197 Example 9.30 XML code for the new data element figure ...... 200 Example 9.31 XML code for the minor axis with string labels figure...... 201 Example 9.32 XML code for the conflicting data points figure ...... 204 Example 9.33 XML code for the new format element figure...... 208 Example 9.34 XML code for the Interstate Graph Design figure ...... 209 Example 10.1 Running headers and footers with a FrameMaker template...... 229 Example 10.2 Using ext-fo:fragment-root ...... 231 Example 10.3 Command file without a FrameMaker template ...... 232 Example 10.4 Basic XSL-FO document with a single page master ...... 232 Example 10.5 XSL-FO document with different regions ...... 233 Example 10.6 Running headers and footers without a FrameMaker template ...... 236 Example 10.7 Balancing text across columns ...... 237 Example 10.8 Generating page # of ## folios ...... 238 Example 10.9 Embedding graphics in an XSL-FO document ...... 240 Example 10.10 Defining variables in an XSL-FO document ...... 241

Adobe Document Server Developers Guide Dec 19, 2003 19 List of Examples

Example 10.11 XMP metadata in XSL-FO using fo:root ...... 242 Example 10.12 XMP metadata in XSL-FO using ext-fo:fragment-root...... 243 Example 11.1 Encrypting a PDF document with an open password...... 248 Example 11.2 Encrypting a PDF document with a master password and permissions ...... 248 Example 11.3 Encrypting a PDF file with permissions and both passwords ...... 249 Example 11.4 Decrypting a PDF document with a master password ...... 250 Example 11.5 Decrypting a PDF document with an open password ...... 250 Example 11.6 Enabling all usage rights ...... 252 Example 11.7 Disabling all usage rights ...... 253 Example 11.8 Setting usage rights and encryption permissions ...... 254 Example 11.9 Setting usage rights and resetting encryption ...... 254 Example 11.10 Getting usage rights ...... 255 Example 12.1 Exporting comments in the FDF format ...... 262 Example 12.2 Exporting comments in the XFDF format ...... 262 Example 12.3 Importing comments in XFDF format...... 262 Example 12.4 Merging comments from one source ...... 263 Example 12.5 Merging comments from multiple sources ...... 263 Example 12.6 Deleting all comments ...... 264 Example 12.7 Deleting comments by author ...... 264 Example 12.8 Deleting a specific type of comment ...... 265 Example 12.9 Deleting comments before a particular date ...... 265 Example 12.10 Deleting comments after a particular date ...... 265 Example 12.11 Deleting comments in a particular date range ...... 265 Example 12.12 Deleting comments by multiple authors...... 266 Example 12.13 Exporting links ...... 268 Example 12.14 Deleting links ...... 269 Example 12.15 Exporting bookmarks...... 270 Example 12.16 Updating thumbnails ...... 272 Example 12.17 Deleting thumbnails ...... 273 Example 12.18 Importing data for a file attachment from a content holder...... 275 Example 12.19 Importing data for a file attachment from an external file ...... 275 Example 12.20 Exporting a file attachment into a content holder...... 276 Example 12.21 Exporting a file attachment into an external file ...... 277 Example 12.22 Deleting a file attachment ...... 277 Example 13.1 Providing values for text form fields directly ...... 281 Example 13.2 Exporting form data to FDF format ...... 282

20 Dec 19, 2003 Adobe Document Server Developers Guide List of Examples

Example 13.3 Exporting form data to XFDF format ...... 282 Example 13.4 Importing form data ...... 283 Example 13.5 Exporting and importing together ...... 283 Example 13.6 Changing the appearance of a form field ...... 284 Example 13.7 Changing the style of a check box or radio button ...... 285 Example 13.8 Replacing a button’s icon and caption ...... 285 Example 13.9 Hiding a form field...... 286 Example 13.10 Restricting write access for form fields ...... 287 Example 13.11 Flattening all form fields with the flattenFormFields command ...... 288 Example 13.12 Flattening all form fields with the flattenForm command ...... 288 Example 13.13 Flattening certain form fields by inclusion...... 288 Example 13.14 Flattening certain form fields by exclusion ...... 289 Example 13.15 Deleting specific form fields...... 289 Example 13.16 Deleting all form fields ...... 289 Example 14.1 Deleting the first page of a document ...... 292 Example 14.2 Deleting the last page of a document ...... 292 Example 14.3 Deleting a specified range of pages...... 293 Example 14.4 Deleting discontiguous pages ...... 293 Example 14.5 Deleting all but one page ...... 293 Example 14.6 Forcing an even number of pages ...... 294 Example 14.7 Appending a spawned page ...... 295 Example 14.8 Appending one document to another ...... 297 Example 14.9 Prepending one document to another ...... 297 Example 14.10 Inserting pages before a specified page ...... 298 Example 14.11 Inserting pages after a specific page ...... 298 Example 14.12 Assembling multiple documents ...... 300 Example 14.13 Creating new root bookmarks during assembly ...... 301 Example 14.14 Specifying an alias to resolve former references ...... 302 Example 14.15 Inserting a table of contents into an existing PDF document ...... 305 Example 14.16 Inserting a table of contents in an assembled document ...... 305 Example 14.17 Rotating one page...... 306 Example 14.18 Rotating an entire document ...... 307 Example 14.19 Overlaying a single page...... 309 Example 14.20 Overlaying multiple pages ...... 309 Example 14.21 Skipping pages in the overlay document ...... 309 Example 14.22 Underlaying a page ...... 310

Adobe Document Server Developers Guide Dec 19, 2003 21 List of Examples

Example 14.23 Overlaying form fields and annotations ...... 310 Example 14.24 Applying a transform to an overlay page ...... 311 Example 14.25 Overlaying multiple templates ...... 314 Example 14.26 Renumbering page labels ...... 316 Example 14.27 Renumbering page labels after assembling a new document ...... 317 Example 15.1 Converting PDF to EPS ...... 320 Example 15.2 Converting PostScript to PDF ...... 320 Example 15.3 Converting a PDF document to TIFF format...... 321 Example 15.4 Saving a Web-optimized PDF document...... 322

22 Dec 19, 2003 Adobe Document Server Developers Guide Preface

Introduction Adobe® Document Server (ADS) is a dynamic publishing platform that extends the distinctive competence of Adobe in imaging, static and animated graphics, and page layout to the server infrastructure. ADS allows the extension of current workflow for dynamic HTML (HyperText Markup Language) to include visually rich images and graphics, as well as dynamic generation, manipulation, and combination of PDF files from a variety of sources. Purpose This guide contains information to guide programmers in using the ADS commands and in submitting requests to ADS. It contains some background discussion of basic concepts upon which the command language and the invocation interfaces are based, and provides details for writing commands that manipulate image and document data.

NOTE: "AlterCast" was the name of the previous version of this product. References to the name "AlterCast" still appear in both the product and the documentation. Such references are valid and required for the product to function correctly. Intended Audience The audience for this manual is programmers or other technical personnel who need to write commands or submit requests to ADS. Familiarity with XML (eXtensible Markup Language) is assumed for command set construction. Programmers preparing code to submit requests to ADS from one of the APIs or directly to the Web service are assumed to have some experience with Java, Perl, or COM programming, or with WSDL–capable tools for constructing Web service requests. Some familiarity with Illustrator®, Photoshop®, ImageReady®, Acrobat®, and FrameMaker®, and file formats that these applications use such as SVG, PSD, PDF, and MIF, is also assumed. Organization of This Guide This guide contains three parts. Part I contains general information about the architecture of the product and its general capabilities. Part II contains specific guidance for using the commands that manipulate images. Part III contains specific guidance for using the commands that manipulate document files. See the Table of Contents for detailed organizational information. Related Documents This guide is most useful when used in conjunction with the following references: ● Adobe Document Server Command Reference: Provides a complete reference for the XML commands that implements ADS functionality.

Adobe Document Server Developers Guide Dec 19, 2003 23 Preface

● Adobe Document Server API Reference: Provides a reference for the interfaces used to invoke ADS, including the Java, Perl, and COM APIs, the Web service interface, and the command line interface. Explains how to handle the information received in response. ● Adobe Document Server XML Grammars Reference: Explains how ADS uses and supports XML formats and protocols. Includes reference information for formats and grammars that ADS uses, defines, or extends. Other related documents are: ● Installation and Configuration Guide: Contains installation instructions, configuration requirements, and administrative guidelines for ADS. ● Adobe Document Server Command Quick Reference: Provides brief syntax statements for the ADS XML commands. ● Adobe Document Server 6.0 for Reader Extensions User Guide: Explains how to use and administer the Web application that can enable interactive features in PDF documents. Notational Conventions This document uses typefaces to identify the characteristics of text. These typefaces and the characteristics they imply are described below. To convey additional information, this document may also apply color and underlining to words or phrases that use the typefaces described above. Such use is described below:

Item Use and examples

File names are shown in Courier font. /psd/stoplight.psd

Code items within plain text are shown in Courier The loadContent command font. The getName method

Code examples set off from plain text are shown in Syntax: Courier font.

Document titles, new terms, and variables or other Adobe Document Server Developers Guide placeholders within code are designated by an italic These translation methods are known as font. rendering intents because... in="contentName"

Documentation Problems If you discover any errors in or have any problems with this documentation, please e-mail us at: [email protected] Please describe the error or problem as completely as possible and give us the document title and the page number or page range.

24 Dec 19, 2003 Adobe Document Server Developers Guide Part I

Basics

Adobe Document Server Developers Guide Dec 19, 2003 25 26 Dec 19, 2003 Adobe Document Server Developers Guide Overview of Adobe Document 1 Server

This chapter provides a very general overview of the architecture of Adobe Document Server (ADS), how it works, what file formats it supports, and the underlying standards, technologies, and protocols that it uses. The chapter contains the following sections:

Product Summary starting on page 27 Format Summary starting on page 30 Web-Related Standards and Formats starting on page 33

Product Summary

ADS provides you with functionality you can use to programmatically request a particular set of operations on images and documents. This functionality falls into two main areas: specifying what manipulations ADS should perform, and invoking ADS to perform those manipulations.

ADS Commands ADS provides an XML command language that you use to operate on input data you provide. These commands provide a wide range of manipulations, allowing you to: ● Modify, add to, and combine input data in various ways. ● Replace variables within data of certain types. ● Add data from XML sources and extract information in XML format. ● Modify metadata contained in the input. ● Convert between file formats; for example, from one image format to another, or between image and document formats. You create command sets (in files or other language constructs such as strings) that contain a series of these commands. These commands instruct ADS to load input data and perform specific operations on it. After the desired transformations are done, you can save the results in one of several ways. You can transform a single input file in a number of ways, creating multiple result files from a single input. You can also provide the same input file to the same set of commands, but use different associated data, such as variable replacement data, each time, resulting in a number of different result files from a single input file. In the latter case, input files are also sometimes called templates.

Adobe Document Server Developers Guide Dec 19, 2003 27 Overview of Adobe Document Server ADS Requests 1 Product Summary

The information you need to construct command sets, and a list of file formats you can load, convert, and save are described in Chapter 3, “ADS Command Basics.” The ADS commands are described in detail in the Adobe Document Server Command Reference.

ADS Requests You invoke ADS by sending it a request. A request consists of a set of commands, one or more input files, and some other optional information. ADS provides three APIs you can use to send requests: a Java, Perl, and COM API. You can also construct your own HTTP requests and send them directly to the ADS Web service. ADS also provides a convenient command line interface for executing commands during testing and prototyping. You can specify in a request how you want ADS to return the results of its processing to you, either in a response, or by writing result files to the file system on which ADS is running. For more information on how to send requests to ADS and process the results, see Chapter 2, “Invoking ADS.” The command line interface, the Web service interface, and Java, Perl, and COM APIs are described in detail in the Adobe Document Server API Reference.

Manipulating Graphics Input ADS loads graphics files from a number of different formats, as listed in Table 1.1 on page 30. SVG files are loaded as SVG content. You can replace text and graph data in SVG content, as well as other operations. You can also convert SVG content to Raster content. All other image formats are converted internally to the PSD-like format called Raster content. You can manipulate Raster content in a variety of ways. You can: ● Change the size of an image, crop or trim it, or change its orientation. ● Add, remove, position, or flatten layers. ● Change the color mapping in the image. ● Replace the pixels in a pixel layer and the text in a text layer. You can define graphic template files that contain variables. You use ImageReady to create variables in PSD files, and Illustrator to create variables in SVG files. You can bind variables to images, text, SVG graphs and individual SVG objects, and also use them to toggle the visibility of objects or layers. You can then use ADS to replace the variable values in those templates. ADS provides a very flexible mechanism for automatic variable replacement in various circumstances. You can convert document content (PDF and PostScript®) to image content (Raster and SVG), and image content to document content (PDF and PostScript). You can save Raster content to a variety of formats, as listed in Table 1.2 on page 31.

28 Dec 19, 2003 Adobe Document Server Developers Guide Manipulating Documents Overview of Adobe Document Server Product Summary 1

For More Information ● For details on the general operations available on Raster content, see Chapter 5, “Basic Image Manipulations.” ● For details on the general operations available on SVG content, see Chapter 9, “Creating Dynamic Graphs in SVG Files” and Chapter 8, “Operations Specific to SVG Files.” ● For details on replacing text in SVG and Raster content, see Chapter 7, “Replacing Variables in SVG and PSD Files.” ● For details on variable replacement, see Chapter 7, “Replacing Variables in SVG and PSD Files.” ● For details on converting between formats, see Chapter 15, “Converting and Saving PDF Documents” and “Treating PostScript and PDF Content as Images” on page 112.

Manipulating Documents ADS accepts PDF and PostScript files and allows you to convert one format to the other. ADS provides commands that manipulate PDF documents in a variety of ways: ● You can extract information such as bookmark and link data in XML format; import, export, and merge comments; and import and export embedded data objects. For more information, see Chapter 12, “Manipulating PDF Features.” ● You can create new documents by assembling existing PDF files, and add content to documents from other PDF documents, or from form data in FDF or XFDF format. For more information, see Chapter 14, “Manipulating Pages and Documents” and Chapter 13, “Working with PDF Form Fields.” ● You can create new PDF documents from XSL Formatting Object (XSL-FO) data. You can provide formatting information either in the XSL-FO input, or via a FrameMaker template, or both. For more information, see Chapter 10, “Creating PDF Files from XSL-FO.” ● You can use ADS to encrypt and decrypt PDF documents. See Chapter 11, “Controlling Document Security.” ● If you have purchased Adobe® Document Server 6.0 for Reader Extensions, you can insert usage rights information into PDF documents that selectively enables various editing capabilities in the Adobe Reader®.

Manipulating Metadata ADS uses Extensible Metadata Platform technology (XMP) to handle metadata associated with most of the file formats it accepts. ADS can read and write metadata values in both XMP and in the EXIF and IPTC formats defined for PSD, TIFF, and JPEG. It also handles metadata in PDF files. You can export metadata from a file to examine or copy it, add, delete, or modify metadata properties for most file formats, and save files with metadata. ADS generally preserves existing metadata for those formats that do not support metadata manipulation.

Adobe Document Server Developers Guide Dec 19, 2003 29 Overview of Adobe Document Server Input, Output, and Metadata Formats 1 Format Summary

ADS adds certain metadata properties to some files that it handles, to record data such as the date the file was modified and the fact that the file was handled by ADS. For more information, see Chapter 4, “Working with File Metadata.”

Format Summary

When you load a file into ADS, it becomes ADS content. Content types do not correspond exactly to file formats; image data from most image formats is converted on load to the PSD-like Raster content type, and some content types can store more than one data format. For a complete explanation of the concept of ADS content and the relationship of content types to file formats, see Chapter 3, “ADS Command Basics.”

Input, Output, and Metadata Formats The following table summarizes the files formats that ADS can read and shows the content type in which each format is loaded.

TABLE 1.1 Input file formats allowed by ADS

Content File format type Typical usage

PSD Raster Raster image data to be manipulated with the graphics commands. TIFF GIF JPEG PNG

SVG SVG Vector image data to be manipulated with the graphics commands.

PDF PDF Document input to be transformed to an image format or manipulated with the document commands.

PostScript PostScript Document input to be transformed to an image or PDF format. EPS

XML XML Replacement data for SVG or PSD variables, or other miscellaneous uses.

XMP XMP Replacement metadata values to be added to appropriate types of content, or extracted metadata being retrieved.

FDF FormData New or replacement form data or comments to import into existing XFDF PDF content.

XSL-FO XSL-FO Content to be transformed to PDF.

FM Frame Formatting template for XSL-FO content being transformed to PDF. MIF

30 Dec 19, 2003 Adobe Document Server Developers Guide Input, Output, and Metadata Formats Overview of Adobe Document Server Format Summary 1

The list below shows which TIFF variants ADS can read (load) and write (save):

Byte order Intel bye order (PC order in Photoshop) read & write Motorola byte order (Mac order in Photoshop) read Grayscale, RGB, CMYK (standard ink order only, 8–bit and 16–bit read & write Color modes chunky color) Compression LZW read

When saving content that was loaded in TIFF format, ADS preserves the following information from the original input:

Clipping Paths When saved to EPS, TIFF, PSD, and PDF formats Resolution When saved to EPS, TIFF, and PSD formats Metadata EXIF, IPTC, and XMP

FDF (Forms Data Format) is a file format based on PDF that is used to express interactive form data and annotations in PDF files. This format allows you to export form and annotation data from a PDF file, store it in another file, and import the data into another copy of the same PDF document. For more information on FDF, see Chapter 8 in the PDF Reference, fourth edition. XFDF is an XML version of FDF. This format is described in the Adobe technical note XML Forms Data Format Specification, Version 2.0. FM is the native binary FrameMaker file format. MIF (Maker Interchange Format) is a pure text form of a FrameMaker file. You can use MIF format to access FrameMaker files from other applications. The following table shows the content types ADS provides and the file formats which you can save from each content type.

TABLE 1.2 Output file formats produced by ADS

Content type File format

Raster PSD, TIFF, GIF, JPEG, PNG8/24, WBMP

SVG SVG

PDF PDF, Web-optimized PDF ADS can also write out embedded data objects from PDF files byte-for-byte, regardless of format.

PostScript PostScript, encapsulated PostScript (EPS), Photoshop EPS

XML XML

XMP XMP

FormData FDF, XFDF

Adobe Document Server Developers Guide Dec 19, 2003 31 Overview of Adobe Document Server Format Conversions 1 Format Summary

The following table shows the metadata formats that ADS preserves and supports, and shows which file formats and content types can contains which metadata formats:

TABLE 1.3 Metadata formats supported and preserved by ADS

Metadata formats supported File formats Content type

EXIF, IPTC PSD, TIFF, JPEG Raster

XMP PSD, TIFF, JPEG, GIF, PNG Raster

SVG SVG

PDF PDF

Photoshop EPS PostScript

XSL-FO XSL

For files containing metadata in EXIF or IPTC formats, those values are preserved in XMP format when the file is loaded. When you save Raster content to a PSD or TIFF file, ADS writes the metadata in all three formats. When you save Raster content to a JPEG file, ADS can write metadata in none, any, or all of the formats. For Raster, SVG, and PDF content, you can directly manipulate metadata only in XMP format. You can change, delete, or add properties. You can also export or import XMP metadata to or from an XMP file. For XSL content and Photoshop EPS, existing XMP metadata is preserved but you cannot manipulate it. Metadata is not preserved for other kinds of PostScript content.

Format Conversions Some file formats are transformed on load (see Table 1.1) and some content types can be transformed on save (see Table 1.2). In addition, you can perform some explicit content type conversions on loaded content, as listed in Table 1.4.

TABLE 1.4 Direct content type conversions supported by ADS

Raster ➟ EPS ➟ PDF SVG ➟ Raster ➟ PDF PDF ➟ Raster ➟ EPS

PostScript ➟ Raster EPS ➟ PDF

32 Dec 19, 2003 Adobe Document Server Developers Guide Format Conversions Overview of Adobe Document Server Web-Related Standards and Formats 1

You can combine any number of these conversions. For example, you can load a JPEG file, which is loaded as Raster content, convert the Raster to PDF, and save out a PDF file. You can load an SVG file, convert it to Raster, convert it again to EPS, and save out an EPS file.

Web-Related Standards and Formats

ADS takes advantage of many Web-related standards. The command set is defined in XML, and you use XPath syntax to identify parts of Raster and SVG files. You use URIs (Uniform Resource Identifiers) to identify source files, and locations for result and log files. You can load XML data and use it to replace various kinds of data in the files you are processing. ADS also makes use of various Web-related formats such as SOAP, PDF, SVG, XMP, and XSL-FO. For an overview and a description of how these formats and protocols are supported and used in ADS, as well as information on formats and extensions that ADS defines or uses, see the Adobe Document Server XML Grammars Reference. Many of these standards and formats are defined by the Internet Engineering Task Force (IETF) or the World Wide Web Consortium (W3C). ● For more information about SVG, SOAP, and other W3C standards, see the W3C site (www.w3.org). ● For more documentation of Adobe formats and protocols and Adobe extensions to standard formats and protocols, such as PDF, see the Adobe Web site (www.adobe.com). ● URIs are defined by IETF specifications.

Adobe Document Server Developers Guide Dec 19, 2003 33 Overview of Adobe Document Server Format Conversions 1 Web-Related Standards and Formats

34 Dec 19, 2003 Adobe Document Server Developers Guide 2 Invoking ADS

This chapter contains a summary of the architecture of ADS and the various ways you can send it requests, and explains the underlying model of an ADS request and response. For more detailed information about these topics, see the Adobe Document Server API Reference. This chapter also provides a complete description of how you specify file locations using URIs in the API methods, on the command line, and in command attributes. This chapter contains the following sections:

Deploying and Invoking ADS starting on page 35 The Interface Model starting on page 37 Details of the Objects in the Model starting on page 39 How ADS Handles URIs starting on page 43

Deploying and Invoking ADS

You can deploy ADS as a library and as a Web service. Once deployed, you have a choice of invocation mechanisms: the command line, one of three APIs (Java, Perl, or COM), or a direct connection to a Web service. Table 2.1 summarizes how the deployment and invocation choices are related.

TABLE 2.1 Deployment and invocation choices for ADS

Possible invocation choices Deployment choice Java API Perl API COM API Other Command line

Library ✔✔✔ ✔

Web service ✔✔ ✔

When you install ADS as a library, you can access it locally from the command line or the Java, Perl, or COM APIs. Depending on how you configure your systems, it is possible to access ADS as a library remotely from COM. When you install ADS as a Web service, you can access it from another system using the Java or Perl APIs, or directly by constructing your own HTTP request. Of course, local access to the Web service is also allowed. Figure 2.1 shows the same information as the table above. In addition, it shows where individual processes or process pools can be used.

Adobe Document Server Developers Guide Dec 19, 2003 35 Invoking ADS 2 Deploying and Invoking ADS

FIGURE 2.1 Deployment and invocation choices for ADS

Remote system Local system ADS Web Service

Other code Web service process pool

Perl API local process

Java API local process

remote process local process pool remote process pool

COM API local process local process pool

Command Line local process

Which interface you choose to use to invoke ADS depends on the larger environment in which you are deploying ADS, and which language or mechanism you want to use to access ADS functionality. Table 2.2 lists the four interfaces and the circumstances under which you might choose to use each one.

TABLE 2.2 Details of invocation choices for invoking ADS

Interface Access modes Usage scenarios

Command line Local execution In an environment that supports command line Windows & Solaris™ mode, for simple invocation of ADS. You can work interactively directly on the command line, or from scripts that you can run from the command line or through some automatic mechanism such as cron.

Java API Local and remote execution In any situation where you can write Java code to Windows and Solaris invoke ADS, for example, in Java applications or servlets, or in JSP pages.

Perl API Local and remote execution In any situation where you can execute Perl scripts, Windows and Solaris for example, CGI scripts.

COM API Local and remote execution In any situation where you can execute code in any Windows only language with COM support, such as JavaScript, VBScript, Visual Basic, .NET, VBNET, Perl, Java, C, C++, and C#.

Web service Remote execution From any Web–service–enabled client.

When writing a set of commands, it is important to know how the commands will be submitted for processing. For example, the ways in which a command can refer to an input file

36 Dec 19, 2003 Adobe Document Server Developers Guide The Objects in the Model Invoking ADS The Interface Model 2

or specify an output file location depend upon whether the request was made on the command line, an API, or directly to the Web service, and further on what data and information was included with the request. There are also some interactions between specifications made on the command line or in a request, and those made within a set of commands. For example, you can specify a result location (where result files are written) on the command line, in the commands themselves, or both, or you can write results into a results object to be sent back to the client.

The Interface Model

While they differ in some respects, the invocation mechanisms are all based on a common model and rely on the same core ADS code that executes requests. This model defines objects that represent a server, request, response, and result. The three APIs implement this model directly, creating objects in their respective languages. The XML syntax for expressing ADS requests in an HTTP request is also based on the same object relationships. The command line interface more loosely matches the model.

The Objects in the Model Table 2.3 explains briefly what each of these conceptual objects represents, and the following sections provide a more detailed description of the objects.

TABLE 2.3 The object model of the ADS interfaces

Object Represents

Server An ADS process or service that executes a request and returns a response.

Request A collection of all the necessary commands, input data, and request–specific settings needed to send a request to ADS.

Result A unit of output from an executed command. The form of the output may be result content (current content when the command finishes), a result file (written to the local file system), or a named result that can be collected into a response object. You may get one or more output results from executing a request.

Response A collection of log messages and results produced by an ADS server during the execution of a request, to be returned to the client. A response can contain zero or more results.

Interacting with ADS In general, an interaction with ADS involves a number of steps. These steps vary depending on the interface you use to invoke ADS, as outlined in the following table. This table distinguishes

Adobe Document Server Developers Guide Dec 19, 2003 37 Invoking ADS Interacting with ADS 2 The Interface Model

between calling ADS from the command line, from one of the 3 APIs (Java, Perl, COM), or by sending an HTTP request directly to the ADS Web service (without using the Java or Perl API).

TABLE 2.4 Steps involved in interacting with ADS

Step Interface Details Creating an ADS Java, Perl, COM APIs The Java and Perl APIs provide constructors for server objects. Server object Object construction is an integral part of COM. Web service direct N/A Command Line N/A Creating an ADS Java, Perl, COM APIs Java and Perl APIs provide request object constructors. Object Request object construction is an integral part of COM. All three APIs provide methods for populating the request object with the required information. Web service direct The HTTP message sent to the Web service is the request. Command Line You can loosely view the information passed in the command line options as the request. Sending a request to a Java, Perl, COM APIs All 3 APIs provide an execute method in the server object’s server class that sends a request to a server. Web service direct Sending an HTTP message to the Web service constitutes sending a request. Command Line Invoking ADS on the command line “sends” the “request.” Receiving a response Java, Perl, COM APIs The execute method returns a response object. Log messages from the server are always included in the response object, but may also be (A response consists written to a log file on the server’s file system. Result content is of log messages and returned either in the response object or written to the server’s result content.) local file system. Web service direct The Web service returns a response to the request message. The response contains log messages. Settings in the commands determine whether results are included in the response message or written to the Web service’s file system. Command Line Log messages are sent to the standard error stream. Result files are written to the local file system.

38 Dec 19, 2003 Adobe Document Server Developers Guide Server Objects in the APIs Invoking ADS Details of the Objects in the Model 2

TABLE 2.4 Steps involved in interacting with ADS

Step Interface Details Processing the contents Java, Perl, COM APIs Methods are provided for extracting the log messages and of a response results from the response object. If the results were written to the file system, you can inspect them with appropriate applications. Web service direct You can use any method you choose to extract log message and result information from the HTTP response. If results were written to the file system, you can inspect them with appropriate applications. Command Line You can redirect the standard error stream to a file for further examination of log messages. You can inspect result files with appropriate applications. Releasing a server Java, Perl, COM APIs With library deployment, Server objects persist until you when you are finished explicitly release them, which releases their association with with it any ADS process and makes them available for garbage collection. (N/A for Web service deployment). Web service direct N/A Command Line N/A

Details of the Objects in the Model

The information in this section is a high level presentation of the details of the server, request, response, and result objects as given in the Adobe Document Server API Reference. An overview is provided here so that you can understand the context in which commands are executed.

Server Objects in the APIs When you create a server object in any of the APIs, that object is associated, directly or indirectly, with an ADS process. Whether this association persists for the course of a single request or for the life of the object depends on what kind of Server object it is. Table 2.5 shows the several kinds of server objects and how they are associated with ADS processes.

Adobe Document Server Developers Guide Dec 19, 2003 39 Invoking ADS Requests 2 Details of the Objects in the Model

TABLE 2.5 Kinds of server objects in the APIs

Direct server object Associated with a single ADS process on the same system on which the server object is created, for the lifetime of the object.

Pooled server object Associated with a pool of ADS processes on the same system on which the server object is created. Each time you send the object a request, a different process from the pool can execute the request. Web service server object Associated with an ADS Web service, which uses a pool of ADS servers to execute requests it receives. The ADS Web service may exist on either the local system or a remote one. Each time you send the object a request, a different process from the pool can execute the request. You can establish a regular connection or a secure connection to the Web service when you create this type of object.

COM server objects Associated with a single or pooled ADS process. Pooling is an inherent part of COM+, so you can create either single processes or process pools. Whether or not the process or pool is local or remote from the system on which the server object is created depends entirely on how your system or systems were configured during installation.

When you send a request to a server object that will execute remotely, there are some concerns you must consider, such as whether to include your input files in your request and whether to ask ADS to return your results in the response object or write them to the remote file system; these decisions can affect the speed at which the request is processed, due to increased transmission time. These concerns are discussed in detail in the Adobe Document Server API Reference.

Requests When you invoke ADS, you must provide all the information it needs in order to do what you want it to do to your input files. This information includes specifying the input data on which you want ADS to operate, a set of operations to perform, and how to save the results of those operations. In addition, you can control certain aspects of how ADS behaves while processing this information. The collection of all necessary commands, input data, and settings needed for a single invocation of ADS is called a request. The actual form the request takes depends on which interface you use to invoke ADS: ● If you invoke ADS from the command line, your request specified by the command line options and the contents of the command file you provide (if any—ADS can perform certain default operations on a file passed in on the command line when you do not specify a command file). ● If you invoke ADS from the Java, Perl, or COM API, you construct a request object provided by those APIs and put the appropriate information into it.

40 Dec 19, 2003 Adobe Document Server Developers Guide Results and Responses Invoking ADS Details of the Objects in the Model 2

● If you invoke the Web service directly, you construct an appropriate HTTP request based on the WSDL (Web Services Description Language) for the Web service, using tools of your choice. In general, the following pieces of information are part of an ADS request:

TABLE 2.6 The kinds of information in an ADS request

Information Details

Input data File content of any file type allowed by ADS.

ADS commands A set of commands for ADS to execute on the input data.

Variable substitution data Replacement values for variables defined in PSD and SVG files.

User–defined variables Values for user-defined variables that can be referenced within commands. Available only from the command line interface.

Settings for ADS behavior Values for certain parameters that control how ADS behaves while processing the request, including a base URI for the result location, whether result files should be overwritten, and the error behavior. These values can also be specified in the commands. If a value is specified both in the request and in the commands, the value set in the request takes precedence.

For details of how to construct requests for all of the invocation interfaces, see the Adobe Document Server API Reference.

Results and Responses When you invoke ADS from one of the APIs or directly via the Web service, you can specify a result location in which ADS writes result files; this location must be locally accessible to the ADS process that executes the request. If you don’t specify a result location, or otherwise save your results to the file system, result content is returned to you in a response. When you invoke ADS from the command line, all result files are written to the local file system. Whenever you make a request from one of the APIs, ADS returns a response object. Response objects contain a (possibly empty) collection of log messages and a (possibly empty) collection of results. Log messages are simple strings, but results are represented by yet another object, the result. A result object contains the file data for the result. It also contains information about that data, such as the name it was given in the commands when it was saved, an appropriate file extension, its MIME type, and if it is image data, the height and width of the image in pixels.

Adobe Document Server Developers Guide Dec 19, 2003 41 Invoking ADS Logging 2 Details of the Objects in the Model

Logging While an ADS process executes a request, it may output log information of various kinds. You can control the types of messages ADS logs and where it writes the log information. Log Levels Each log message starts with a prefix that corresponds to the level number. Levels (0-7) group messages according to their severity and importance in the system, as shown in Table 2.7. You can set a parameter that causes ADS to report messages only at or below a particular level, using a command-line option or the appropriate API method when constructing a request.

TABLE 2.7 Log levels and their meaning

Level Prefix Use in ADS

0 [FATAL] Not currently used.

1 [ALERT] Not currently used.

2 [CRITICAL] ADS has failed to complete the current request. No further commands will be executed for this request.

3 [ERROR] An error occurred that makes it impossible for ADS to execute the current command. If the ADS process executing this request is configured to stop on errors, a log message at this level will be followed by a critical (level 2) message saying the request cannot be processed.

4 [WARNING] A possibly incorrect but recoverable situation has occurred during the execution of a request. This is the default log level.

5 [NOTICE] A significant event of interest occurred during execution.

6 [INFO] A common but interesting event occurred during execution.

7 [DEBUG] Not used.

Log Message Destinations Where log messages are written varies across the invocation mechanisms: ● The command line sends all log messages to the standard error stream. ● The APIs allow you to specify a log destination for single server objects and for server pools. Regardless of whether or not you specify a log location, ADS always includes the log messages generated by your request in the response object. The APIs also provide a way to retrieve log messages for a request if ADS fails to finish executing it and does not return a response object. ● Log file location is configured by an administrator when the Web service is installed. For details of the command-line options and API methods related to logging, see the Adobe Document Server API Reference.

42 Dec 19, 2003 Adobe Document Server Developers Guide Logging Invoking ADS How ADS Handles URIs 2

How ADS Handles URIs

There are many places in the ADS interfaces and the ADS command language where you must supply a URI for the value of a parameter or attribute. This section explains the basic concepts you need to know in order to understand when absolute URIs are required, and how relative URIs are resolved. This explanation assumes the following definitions:

Absolute URI A URI that begins with a scheme name, such as file:///C:/myfiles/working Relative URI A URI that does not begin with a scheme name. Relative URIs can be absolute or relative paths, or simple names with no path information in them. The following are all relative URIs: /tmp/logfiles, ../myfiles/working, myfiles/working, image.psd Absolute path (Solaris) A path that begins with a forward slash, such as /tmp (Windows) A path in one of three forms: • A path that begins with a drive name, such as C:/myfiles/working/image.psd • A UNC path that starts with // • A UNC path that starts with \\

NOTE: ADS transforms \\ to // on Windows. Absolute paths are relative URIs. Relative path (Solaris) A path that does not begin with a forward slash, or a simple name with no slashes or colons in it. (Windows) A path that does not begin with a drive name or with double slashes, as explained in the row above (Absolute path), or a simple name with no slashes or colons in it. Relative paths are relative URIs. Base input URI An absolute URI used to resolve relative URIs for arguments that specify input data for ADS. The three APIs, the command line, and the core ADS process that executes requests all have their own base input URI. Base output URI An absolute URI used to resolve relative URIs for arguments that specify output data for ADS. The command line and the core ADS process that executes requests all have their own base output URI. (The SDK executables do not have base output URIs.)

Adobe Document Server Developers Guide Dec 19, 2003 43 Invoking ADS Base URIs for the APIs 2 How ADS Handles URIs

ADS supports the following schemes for URIs:

TABLE 2.8 Supported URI schemes

file: Supported in all APIs and the commands

http: Supported only when specifying the URL of an ADS Web service. (Java and Perl APIs)

https: Supported only when specifying the URL of an ADS Web service. (Java API only)

adobe-content: Supported in some of the commands for specific purposes.

Base URIs for the APIs Some of the methods in the Java, Perl, and COM APIs have parameters that take URIs. In some cases, you can specify relative URIs; in many cases you must provide absolute URIs. Base Input URI: The SDKs establish their own base input URI, which is the current working directory in which the SDK was executed. Since you may or may not know what this location is, absolute URIs are usually recommended. The base input URI uses the file: scheme. You can always specify an absolute URI; in this case, the base input URI is ignored. Base Output URI: The SDKs do not have a base output URI, so you must provide absolute URIs for all method parameters that identify output locations. See the Adobe Document Server API Reference for method details. The entries for each of the method parameters in the APIs specify whether or not a relative URI is allowed.

Base URIs for the Command Line Base Input and Output URIs: The command line establishes base input and output URIs, both of which are the current working directory, the directory in which you invoked the command line. Both base URIs use the file: scheme. Any relative URIs you specify as argument values on the command line are resolved against the appropriate base URI. If you supply any absolute URIs as argument values on the command line, they must use the file: scheme. When you specify an absolute URI, the base URI is ignored. All URIs you specify for the command line must identify files on the local file system. See the Adobe Document Server API Reference for argument details. The entries for each of the command line arguments in that document specify whether or not a relative URI is allowed.

44 Dec 19, 2003 Adobe Document Server Developers Guide Base URIs for an ADS Process Invoking ADS How ADS Handles URIs 2

Base URIs for an ADS Process Establishing the base URIs for an ADS process is more complicated than for the SDKs or the command line. The base input URI is influenced by which interface you use to submit the request and where the commands are for the request. The base output URI is influenced by which interface you use to submit the request and whether or not a result location is specified for the request. (You can specify a result location on the command line, in an API Request object, or in the commands themselves.) The base URIs for an ADS process set the context for all relative URIs used in ADS commands. API Invocation Base Input URI: When you construct a Request object in any of the APIs, you can either include the commands themselves in the Request object, or you can specify a command file on the file system, which ADS reads to obtain the commands. If you include the commands in the Request object, the base input URI is the Request object. All relative URIs for input attributes in commands, such as the loadContent command, must be either simple names with no path information in them (no slashes or colons) or absolute file: URIs of files on the system local to the ADS process. If you specify a command file on the file system, the base input URI is the location of that command file, using the file: scheme. In this case, relative URIs for input attributes in commands, such as the loadContent command, can be simple file names or can contain path information (slashes or colons), and are resolved against the base input URI. Base Output URI: When you construct a Request object in any of the APIs, you can specify a result location to which result files are written. The commands for the request can also specify a result location. (If it is specified in both places, the request setting takes precedence). The result location must be a directory locally visible to the ADS process that executes the request. If you do not specify a result location, the base output URI is the Response object that is returned. All relative URIs for output attributes in commands, such as the saveContent and saveOptimized commands, must be either simple names with no path information in them (no slashes or colons) or absolute file: URIs of files that are written to the file system local to the ADS process. If you specify a result location, the base output URI becomes the location specified. The result location must be specified using the file: scheme. All relative URIs given for output attributes in commands, such as the saveContent and saveOptimized commands, are resolved against this base output URI. Regardless of what the base input or output URIs are, you can always specify an absolute URI, using the file: scheme, in which case the base URI is ignored. Command Line Invocation Base Input URI: When you submit a request to ADS from the command line, the base input URI is the location of the command file, if you specify one; otherwise, it is the current working directory. All relative URIs for input attributes in commands, such as the loadContent command, are resolved against this base input URI.

Adobe Document Server Developers Guide Dec 19, 2003 45 Invoking ADS Base URI Summary 2 How ADS Handles URIs

Base Output URI: When you submit a request to ADS from the command line, the base output URI is the result location if you specify one; otherwise it is the current working directory. All relative URIs for output attributes in commands, such as the saveContent and saveOptimized commands, are resolved against this base output URI. Both base URIs use the file: scheme. Regardless of what the base input or output URIs are, you can always specify an absolute URI, using the file: scheme, in which case the base URI is ignored. See the Adobe Document Server Command Reference for details on which commands have attributes that require URIs. The entries for each of these attributes specify whether or not a relative URI is allowed.

Base URI Summary The following table summarizes the base URIs for the APIs (SDKs), the command line, and the core ADS processes (the context of the commands). All base URIs that are not the Request or Response objects use the file: scheme.

TABLE 2.9 Base URIs for the ADS interfaces

Interface where URIs occur Condition Base URI Java, Perl, COM APIs Input: Location where SDK was (Method calls) executed Output: N/A Command line Input: Current working directorya (command line arguments) Output: Current working directory ADS process Invoked from Commands in Request object Input: Request object (command attribute APIs Commands in file on ADS Location of command file values) server’s file system Result location not set Output: Response object Result location is set Result location Invoked from Command file supplied Input: Location of command file command Command file not supplied Current working directory line Result location set Output: Result location Result location not set Current working directory

a. The directory in which the command line is invoked.

46 Dec 19, 2003 Adobe Document Server Developers Guide 3 ADS Command Basics

This chapter describes fundamental information you need to understand about how some of the basic ADS commands work and how to optimally combine commands in a command set. It explains how to specify and load input content, how ADS handles that content during request execution, and how to save output content. It describes the file formats, content types, conversions, and transformations that ADS supports. It also describes the techniques and mechanisms for specifying and working with content in commands, including how to handle metadata in the input data, and the ways in which you can specify attribute values for the ADS commands. This chapter contains the following sections:

Overview starting on page 47 Content Holders and Types starting on page 48 Loading Content starting on page 53 Converting Content starting on page 57 Saving Content starting on page 59 Referenced Attributes Values starting on page 65 General Commands starting on page 66

Overview

Chapter 2 explained the various parts of an ADS request, one of which was a set of commands that direct ADS to perform a series of operations on specified input. You can specify this command sequence in various forms (stream, string, filename, or URI) depending on which interface you use to invoke ADS; the general term command set applies to all of these forms. The ADS commands are defined using an XML syntax. A command is an element, and its parameters are its attributes. A command set contains a sequence of ADS commands in a command element. Observe the following conventions when writing command sets: ● The command set is an XML construct, and must conform to WC3 standards for well-formed XML documents. ● Indicate the text encoding in the first line of the command set. The text encoding controls how ADS processes data it reads from the command file and from input files. The UTF-8 text encoding is fully supported, and recommended.

Adobe Document Server Developers Guide Dec 19, 2003 47 ADS Command Basics 3 Content Holders and Types

NOTE: UTF-16 and Shift-JIS encodings may work in certain situations, but may cause errors in others. Use these encodings with caution. ● ADS commands are case sensitive. ● Comments can be included in a command set. The format for comments is: Two hyphens at the beginning and end delineate the comment. It is a syntax error to use two or more hyphens within the body of the comment. Generally, a command set contains one or more loadContent commands, other commands that manipulate the loaded content in some way, and one or more save commands that save the results. When you load an input file, ADS determines the type of the file’s contents and reads the file data into an appropriate content holder. ADS provides a number of different content holder types to hold the various file formats allowed as input. Once a file is loaded, it is called ADS content. Once you have loaded your input data, you can explicitly convert some content types to other content types, and perform other supported operations on the content. When you save content, ADS outputs the content in one of its supported output file formats, depending on the type of content being saved. The act of saving content to one of the supported file formats may transform the content again, depending on a number of factors, such as the original input format, optimization settings in the content itself, and which save command you use to save it.

Content Holders and Types

When you load an input file, the content of the file being loaded is stored in a content holder. A content holder is temporary storage that ADS uses while it processes a request. This section explains that mechanism. Almost all ADS commands create a new content holder to contain the result of the operation. Every content holder is of a particular type, which reflects the file type of the contents that go in it. The type of a content holder is determined by the command that creates it. See “Content Types and File Formats” on page 51. At any given time, there is one and only one current content holder. All other content holders are, by default, not current. You can think of the current status as a single label that moves around from content holder to content holder as command execution progresses. The next section explains this in more detail. You can name a content holder with the out attribute of a command, so that you can access it in subsequent commands. (The ADS documentation generally refers to a named content holder simply as “named content.”) Most of the commands have one or more input attributes that take content holder names as values. If you do not name a content holder, you can only access it as

48 Dec 19, 2003 Adobe Document Server Developers Guide How Content Becomes Current ADS Command Basics Content Holders and Types 3

long as it is current. When another content holder becomes current, the unnamed content holder is no longer accessible.

TIP: Try to order your commands to minimize the number of load operations for which you must name the resulting content. Doing this minimizes the amount of memory used during processing.

How Content Becomes Current Content becomes current in two ways: ● The content holder created by a command to hold the result of that command becomes current when the command terminates. This is true whether or not you name the content with the out attribute. ● If you specify the in attribute for a command, the named content that you specify becomes current before the command performs its operation. A command always operates on the current content. If you do not specify the in attribute for a command, it operates on the result of the previous command, regardless of whether that result was named. You can reuse the same content names in multiple commands. When you assign a name to a new content holder, the content holder that previously had that name is discarded and becomes inaccessible. If you use the same content name for both the in and out attributes of a command, the name is assigned to the result of the operation, and the content that was input to the command becomes inaccessible. The save commands (saveContent and saveOptimized) write the current content to two places: ● Into a new content holder — This new content becomes current when the save command terminates, and the content is not transformed. You can optionally name the new content with the out attribute. ● Into a named file — The act of writing the current content to a file of a specific format may optimize the contents, if the content being saved is able to be optimized and optimization settings in the content are appropriately set.

Adobe Document Server Developers Guide Dec 19, 2003 49 ADS Command Basics How Content Holders Work 3 Content Holders and Types

How Content Holders Work The following command sequence illustrates the changing state of content holders during execution, and is designed to illustrate all the important points about how content holders work. Each line in the sequence is numbered; the number corresponds to the explanation below of what happens when that line is executed, with an illustration of the content holder situation at that point. These commands load two PSD files and perform various rotation operations on them, saving them out to result files at the end. 1 2 3 4 5 6 7

1.

The load command creates a content holder named image1 image1 into which it puts the contents of the input file arrow.psd. This becomes the current content holder when the command completes. current

2.

The load command creates a new unnamed content holder image1 into which it puts the contents of the input file square.psd. This becomes the current content holder when the command completes. current

3.

The rotate command operates on the current content. It image1 image2turned creates another content holder named image2turned to hold the result of the rotate operation. This becomes the current content holder when the command completes. Note that at this point, the content loaded in the second current command is no longer accessible because that content holder was not named and is no longer current. 4.

The rotate command rotates the current content and puts image1 image2turned the result in another, unnamed content holder. The new unnamed content becomes the current content when the command completes. current

50 Dec 19, 2003 Adobe Document Server Developers Guide Content Types and File Formats ADS Command Basics Content Holders and Types 3

5.

This command resets the current content to a previously image1 image2turned saved content holder, image1, (from the first load) before it performs its operation. Note that at this point, the content produced by the fourth command is no longer accessible because the content current holder it is in was not named and is no longer current.

The command then rotates the current content, image1, image1 image2turned image1turned 180 degrees and saves it in a new content holder, called image1turned, which becomes the current content.

current

6.

This command creates a result file called pic1.psd from image1 image2turned image1turned the current content. When the command ends, image1turned is still the current content. current

7.

This command resets the current content to the named image1 image2turned image1turned content image2turned. It then creates a result file called pic2.psd from the current content. When the command ends, image2turned is still the current current content.

Content Types and File Formats Table 3.1 lists all the allowed input file formats. For each input format, it shows what content type that type of input becomes, and what formats you could save that content in, if you did not convert it to some other form before saving it or otherwise mark it to be saved in a different format. Notice that you can save all types of content with the saveContent command, but only some types with the saveOptimized command. For image content types, the saveOptimized command determines the output format from optimization settings in the content itself. If the content does not specify optimization settings, the content is saved as GIF. For PDF content, the saveOptimized command saves it to PDF 1.5 format optimized for Web use.

Adobe Document Server Developers Guide Dec 19, 2003 51 ADS Command Basics Content Types and File Formats 3 Content Holders and Types

TABLE 3.1 How content types relate to input and output formats

Input file Content format type Save command Output file format

PSD Raster saveContent PSD saveOptimized GIF, JPEG, PNG8, PNG24, WBMP

GIF Raster saveContent PSD saveOptimized GIF, JPEG, PNG8, PNG24, WBMP

JPEG Raster saveContent PSD saveOptimized GIF, JPEG, PNG8, PNG24, WBMP

PNG Raster saveContent PSD saveOptimized GIF, JPEG, PNG8, PNG24, WBMP

TIFF Raster saveContent TIFF saveOptimized GIF, JPEG, PNG8, PNG24, WBMP

SVG SVG saveContent SVG saveOptimized GIF

PDF PDF saveContent PDF saveOptimized Web-optimized PDF

PostScript PostScript saveContent PostScript

EPS PostScript saveContent EPS

Photoshop EPS PostScript saveContent Photoshop EPS

XML XML saveContent XML

XMP XMP saveContent XMP

FDF FormData saveContent FDF

XFDF FormData saveContent XFDF

XSL-FO XSL saveContent XSL-FO

FM Frame saveContent FM

MIF Frame saveContent MIF

52 Dec 19, 2003 Adobe Document Server Developers Guide Specifying Input Data ADS Command Basics Loading Content 3

Loading Content

You must load all your input data into content holders before the ADS commands can access it. This section explains how you specify input data for a request, and how you load that data with the loadContent command in a command set. It also describes the details of how input file content may be transformed when it is loaded into content holders.

TIP: For best performance, minimize the number of input files in a request. For example, if you have six PSD files that you want to process in the same way, it is more efficient to send six requests, each with a short command set that loads and saves one file, than to send one request with a command set that loads and saves six files.

Specifying Input Data If you send ADS a request using the Java, Perl, or COM API, you can include one or more input files with the request using the addFile method. You must explicitly load this input in your command set, using the name either you or ADS gave the input data. When you execute a request from the command line, you must also load input data explicitly, unless you are processing only one file and you specify that file on the command line. Loading Input Data Explicitly You use the loadContent command to explicitly load data into a content holder. If you submit a request with one of the APIs, the first command in your command set must be a loadContent command. If you submit a request from the command line, the first command in your command set must be a loadContent command unless you specify the -source argument on the command line. The value of the source attribute is a file URI. The file it identifies must be locally accessible to the ADS process on the file system where it is running. ● If you invoke ADS from the command line, or you specify a command file on the server from one of the APIs (you use the setCommandsFileOnServer method on the Request object), relative URIs for the source attribute are resolved with respect to the location of the command file. You can always specify an absolute URI. ● If you invoke ADS from one of the APIs and include the commands in the Request object, the value you provide for the source attribute must be either an absolute file URI or the name associated with the content when the file was added to the request with the addFile command. These names cannot contain slashes or colons. A simple name directs ADS to get the input data from the Request object; an absolute URI directs it to the local file system.

Adobe Document Server Developers Guide Dec 19, 2003 53 ADS Command Basics Specifying Input Data 3 Loading Content

TABLE 3.2 Specifying input data sources in the loadContent command

Form of source attribute Details Allowed Absolute file URI: Identifies a file on the local file Always. file:///mydir/myfile.ext system of the ADS process. (Solaris) Base input URI is ignored. file:///C:/mydir/myfile.ext (Windows) Absolute path: Identifies a file on the local file Allowed in all circumstances in /mydir/myfile.ext system of the ADS process. which the command file exists on C:\mydir\myfile.ext Considered a relative URI, and the local file system. resolved against the base input This condition is always true when URI. In this case, only the scheme invoking ADS from the command part of the base URI is needed to line, and from the APIs when resolve the URI. specifying the command file for the request with the Relative path: Identifies a file on the local file setCommandsFileOnServer system of the ADS process. mydir/myfile.ext method. myfile.ext Considered a relative URI, and This condition is not true when resolved against the base input myfile invoking ADS from an API and URI. including the command set in the Allowed only when the command request object (by using a setFile* file resides on the local file system. command that doesn’t end with “OnServer”). name Identifies input data in the request Required when invoking ADS from object. In this case, the name must one of the APIs and referencing not contain slashes or colons input data added to the request with (‘\’, ‘/’, or ‘:’). the addFile method. The base input URI is the request If the request contains any input object. data added in this way, the only forms you can use for the source attribute are this one and an absolute URI.

Loading Input Data Automatically Automatic loading occurs only when you invoke ADS from the command line. For files that you specify in command-line arguments, you can use either a relative or absolute path. In this case, relative paths are interpreted with respect to the current working directory. ● You can specify one input file on the command line with the -source argument. If you do this, ADS automatically loads that file into a content holder of the appropriate type named srcfile, before executing any commands in your command file. ● You can add variable replacement data on the command line, with the -data argument. If you do this, ADS automatically loads the replacement data into an XML content holder named data.

54 Dec 19, 2003 Adobe Document Server Developers Guide How File Formats Map to Content Types Upon Load ADS Command Basics Loading Content 3

If you specify either or both of these arguments, you can still load other input data with explicit loadContent commands in your command file, and can reference the automatically loaded content by name in any command. You can also specify user-defined variables and values on the command line. All variables and values are collected into an XML content holder named commandLineArguments. For details of the command-line arguments, see the Adobe Document Server API Reference.

How File Formats Map to Content Types Upon Load Table 3.3 shows all the input file formats ADS can handle, and the type of content holder into which each format is read. The next section, “Converting Content” on page 57, explains how you can transform loaded content to other content types. ADS uses an internal, PSD-like format to store and operate on all raster image data. All raster-based file data is transformed to this format when loaded. The transformed image data is called Raster content. When Raster content is loaded, it is marked to be saved in a particular format. The section “The Format Flag on Raster Content” on page 62 explains how you can change this setting. In most cases, when you load an image file from PSD, TIFF, JPEG, or Photoshop EPS format that was produced by Photoshop, ADS reads Photoshop Image Resources such as clipping paths and color profiles and updates them as necessary. For more information on color handling for image formats, see “Color Space Support in ADS” on page 102.

TABLE 3.3 Loading file data with the loadContent command

Content File format type Description Typical uses PSD Raster ADS automatically transforms the file contents to the Image data to be internal Raster format, maintaining all layers and layer manipulated with the names. If the PSD file has a background layer, it is graphics commands. always the first layer, layer[1] or layer[first()]. Any optimization settings that were present in the file are preserved. The content is marked to be saved in PSD format by the saveContent command. GIF Raster ADS automatically transforms the content to the Image data to be JPEG internal Raster format with one unnamed layer, manipulated with the PNG layer[1]. The content contains no initial graphics commands. optimization settings. The content is marked to be saved in PSD format by the saveContent command.

Adobe Document Server Developers Guide Dec 19, 2003 55 ADS Command Basics How File Formats Map to Content Types Upon Load 3 Loading Content

TABLE 3.3 Loading file data with the loadContent command (Continued)

Content File format type Description Typical uses TIFF Raster ADS automatically transforms the content to the Image data to be internal Raster format with one unnamed layer manipulated with the layer[1]. The content contains no initial graphics commands. optimization settings. The content is marked to be saved in TIFF format by the saveContent command. If you subsequently add PSD features, such as new layers, to this content, and want to preserve them, you must explicitly mark the content to be saved as PSD before saving it. SVG SVG ADS does not change SVG data when loading it. Any Image data to be optimization settings are preserved. manipulated with the graphics commands. PDF PDF ADS does not change PDF data when loading it. Document input to be transformed to an image format or manipulated with the document commands. PostScript PostScript ADS does not change PostScript data when loading it. Document input to be EPS PostScript content is saved to the same format that was transformed to an image loaded. or PDF format. XML XML ADS does not change XML data when loading it. Replacement data for You can load XML content in two different ways with SVG content. the loadContent command: you can specify a file that contains the XML content with the source attribute, or you can omit the source attribute and provide the XML data inline within the loadContent element. XMP XMP ADS does not change XMP data when loading it. Replacement metadata values to be added to appropriate types of content. XSL-FO XSL-FO ADS does not change XSL-FO data when loading it. It To transform to PDF. treats it as it does XML data, except that it recognizes it as XSL-FO information, not arbitrary XML. FDF FormData ADS does not change FDF or XFDF data when New or replacement XFDF loading it. It recognizes both formats as Acrobat Form form data or comments Data and loads the data into a FormData content to import into existing holder. Comments as well as form data are stored in PDF content. this format. FormData content is saved to the same format that was loaded.

56 Dec 19, 2003 Adobe Document Server Developers Guide Direct Content Type Conversions ADS Command Basics Converting Content 3

TABLE 3.3 Loading file data with the loadContent command (Continued)

Content File format type Description Typical uses FM, MIF Frame ADS does not change FM or MIF data when loading it. To provide a template for It recognizes both forms of FrameMaker output as XSL-FO content being Frame data and loads it into a Frame content holder. transformed to PDF. Frame content is saved to the same format that was loaded.

Converting Content

Once you have loaded data into ADS with the loadContent command, you can manipulate it in a number of ways. The Adobe Document Server Command Reference contains reference information for all the ADS commands, and identifies which commands work on which type of content. Some commands convert content of one type to content of another type. This section summarizes those conversions and points you to other locations in the documentation where these conversions are discussed in more detail.

Direct Content Type Conversions ADS provides commands for converting some content types to other content types. All of the conversion commands take input content of one type, and output content of a different type, which becomes current. The following table summarizes the available content type conversions, and how to accomplish them.

TABLE 3.4 Direct content type conversions

Direct conversion Command Details Raster ➟ EPS convertRasterToEPS ➟ PDF convertRasterToPDF SVG ➟ Raster convertSVGToRaster The Raster content is marked to be saved as PSD. Optimization settings that were set with the Illustrator Save For Web feature are preserved. ➟ PDF convertSVGToPDF PDF ➟ Raster convertPDFToRaster The Raster content is marked to be saved as PSD, and contains no optimization settings. ➟ EPS convertPDFToEPS

Adobe Document Server Developers Guide Dec 19, 2003 57 ADS Command Basics Commands That Work on One Content Type but Produce Another 3 Converting Content

TABLE 3.4 Direct content type conversions (Continued)

Direct conversion Command Details PostScript ➟ Raster convertPSToRaster The Raster content is marked to be saved EPS as PSD, and contains no optimization settings. ➟ PDF convertPSToPDF

You can perform these conversions in sequence to achieve a conversion for which there is no single explicit command. For example: ● To transform an SVG file to a PostScript file, load the SVG, convert it to PDF with the convertSVGToPDF command, convert the PDF content to EPS, and save with the saveContent command. ● To convert a PostScript file to a TIFF file, load the PostScript file, convert the PostScript content to Raster content, mark the Raster content to be saved as TIFF (see “The Format Flag on Raster Content” on page 62), and save with the saveContent command. ● To convert a PDF file to a JPEG file, load the PDF file, convert the PDF content to Raster content, use the set command to add the JPEG optimization settings, and save with the saveOptimized command.

Commands That Work on One Content Type but Produce Another Most of the ADS commands, other than the conversion commands listed in Table 3.4, produce the same type of content as the type on which they operate. A few commands, however, work on content of one type but produce content of a different type. These commands are listed in Table 3.5.

TABLE 3.5 Commands that work on one content type and produce another

Command Input content type Output content type

imageInfo Raster XML

exportMetadata Raster, SVG, PDF XMP

exportBookmarks PDF XML

exportComments PDF FormData

exportDataObject PDF any type

exportLinks PDF XML

exportFormData PDF FormData

formatXSL XSL-FO PDF (and optionally FM or MIF)

getUsageRights PDF XML

58 Dec 19, 2003 Adobe Document Server Developers Guide Determining Where Result Content is Saved ADS Command Basics Saving Content 3

Saving Content

The saveContent and saveOptimized commands save ADS content to an external file. You can call these commands to save content explicitly at any point in a command set. The contents may be saved to the local file system, or included in a response object if you have invoked ADS from one of the three APIs. Both save commands require the name attribute, which is used to name the file (on the file system) or result (in the response object). If a command set does not contain an explicit save command, ADS automatically saves the current content after the last command has been processed; see “Automatic File Saving” on page 64.

NOTE: Some files written out by ADS may not be binary compatible across different operating systems. For example, if you write a file on a Microsoft® Windows® system, it is not always identical to the same file written out on a Solaris system.

Determining Where Result Content is Saved When you construct a request, you can tell ADS where to save the result files by specifying a result location. This must be a folder on the file system where the ADS process executes the request. You can specify the result location: ● In the interface — On the command line, give the resultLocation argument when you invoke ADS. From the Java, COM, or Perl API, call the resultLocation method when you construct the request. ● In the commands — Set the resultLocation attribute of the commands element.

NOTE: If you specify a result location in both the interface and the commands, the setting in the interface takes precedence. Specifying the result location is optional. If you do not specify a result location, the default behavior for returning results is used. This default behavior varies across interfaces. The following table shows where results are placed in all cases:

TABLE 3.6 Determining the result location

Result Interface location Rule for determining destination

Java API specified The name specified in the save command is interpreted as Perl API a file URI. If it is relative, the value of resultLocation is COM API used as the base. Web service direct not specified Content not saved with an absolute file: URI is returned to the client in a response object, identified by the name specified in the save command. The name must not be a file URI; it must not contain forward or backward slashes or a colon.

Adobe Document Server Developers Guide Dec 19, 2003 59 ADS Command Basics Naming Results 3 Saving Content

TABLE 3.6 Determining the result location (Continued)

Result Interface location Rule for determining destination

The command line specified The name specified in the save command is interpreted as a file URI. If it is relative, the value of resultLocation is used as the base.

not specified The name specified in the save command is interpreted as a file URI. If it is relative, the current working directory of the command line is used as the base URI.

Naming Results If you have a command set that does not contain any save commands, ADS automatically saves the result of the last command. If the content type can be optimized, it uses the saveOptimized command; otherwise it uses the saveContent command. In either case, ADS names the result "Untitled" and appends an appropriate file extension. When you explicitly save current content using a save command, you must specify a name for the result; both the saveContent and saveOptimized commands require the name attribute. The form this attribute value can take depends on how the request was invoked: ● If the request is invoked from one of the APIs and you have not specified a result location, the value of this name must be either an absolute URI (file:///path) or a simple name that does not contain slashes or colons (myfile). An absolute URI causes the result to be written to the local file system; a simple name causes it to be written to the response object. ● In all other cases, the value of the name can be a simple name, a name with a file extension, or a relative or absolute URI, including a filename. For requests submitted from the command line, relative URIs are resolved against the result location, if set, or against the location of the command file. For requests submitted from the APIs or directly to the Web service, relative URIs are allowed only if a result location has been specified, and are resolved relative to that location. Providing Your Own File Extension If you are sure of the file format being saved, and your results are being written to the file system, you can include an appropriate file extension as part of the name you supply. For example: When you do this, ADS does not check that the extension you provide matches the actual format of the file written out. Letting ADS Provide the File Extension You can choose to have ADS automatically append the proper file extension. This guarantees the extension accurately reflects the file format. For example:

60 Dec 19, 2003 Adobe Document Server Developers Guide Basic File Saving ADS Command Basics Saving Content 3

If you set appendExtension to true and you also specify a file extension as part of the file name, you get a filename with two extensions. For example, if you save SVG content as follows: the resulting file name is pelican.svg.svg. Leaving Off File Extensions You can also create a result with a name but no extension: If this command is submitted from one of the APIs, and the results are returned in the response object, you can use the methods in the appropriate Result class to extract both the name and the correct extension for the content.

Basic File Saving The saveContent command saves ADS content to the external file system. The following table shows how the saveContent command transforms content to file formats.

TABLE 3.7 Saving content with the saveContent command

Content type File format on save

Raster Raster content is marked to be saved as PSD or TIFF. • If it is marked as PSD, it is saved to a PSD version 7 file (.psd). • If it is marked as TIFF, the saveContent command transforms the content to the TIFF format and saves it to a TIFF version 6 file (.tif).

SVG Written as SVG (.svg), using the version and namespaces with which the content was loaded.

PDF Written as PDF 1.5 (.pdf).

PostScript Written to the format and version from which the content was loaded or created: •PostScript (.ps) • encapsulated PostScript (.eps) • Photoshop-compatible encapsulated PostScript (.eps) New PostScript files created with the convertPDFToEPS or convertRasterToEPS command are written as level 2 EPS.

XML Written as XML (.xml) using the version and namespaces with which the content was loaded.

XMP Written as XMP (.xmp). For details of namespaces used in the file, see Chapter 4, “Working with File Metadata.”

FormData Written to the format and version from which the content was loaded, or that was specified by the format attribute of exportFormData or exportComments: • FDF 1.2 (.fdf) • XFDF (.xfdf), in the XFDF namespace http://ns.adobe.com/xfdf/

Adobe Document Server Developers Guide Dec 19, 2003 61 ADS Command Basics Basic File Saving 3 Saving Content

TABLE 3.7 Saving content with the saveContent command (Continued)

Content type File format on save

XSL-FO Written as XSL-FO (.fo), using the version and namespace with which the content was loaded.

Frame Written to the format and version from which the content was loaded: •MIF (.mif) •FrameMaker (.fm)

The Format Flag on Raster Content A Raster content holder has a format flag that controls the format of the file produced by the saveContent command. When you load a PSD, JPEG, GIF, or PNG file, the flag is set to PSD. When you load a TIFF files, it is set to TIFF. You can change the setting of this flag between loading and saving an image file, with the setFileFormat command. For example, you can load a GIF file and mark it to be saved as a TIFF file, or you can load a TIFF file and mark it to be saved as a PSD file. Similarly, you can convert another content type to Raster, then use setFileFormat to change the format flag, so that the content will be transformed to TIFF on save. Metadata Conversions on Basic Save The saveContent command saves all existing metadata with a file in the XMP format. For PSD and TIFF formats, applicable properties are also written in the EXIF and IPTC formats. Upon save, metadata values in all formats supported by ADS are guaranteed to be consistent. If you do not want metadata saved with a file, you must explicitly remove it from the content before saving, using the removeMetadata or importMetadata command. For more information, see Chapter 4, “Working with File Metadata.”

62 Dec 19, 2003 Adobe Document Server Developers Guide Saving to Optimized Formats ADS Command Basics Saving Content 3

Saving to Optimized Formats You can save Raster, SVG, or PDF content to a Web-optimized file format with the saveOptimized command. The command saves to optimized formats depending on the current content type, as follows:

TABLE 3.8 Saving content with the saveOptimized command

Content type Save behavior

Raster The saveOptimized command saves to one of the optimized image formats — GIF, JPEG, PNG8, PNG24, or WBMP — depending on the optimization settings in the content. The saveOptimized command flattens layers in the current content before creating the result file according to the current optimization settings. ADS uses optimization settings that were set in Photoshop using Save For Web, or set previously in ADS. You can use the optimizeToSize and set commands to modify optimization settings within ADS. Any settings that are not explicitly provided default according to the preferred file format. If the current content does not contain optimization settings, the command writes a GIF file using built-in default optimization settings. The command operates only on images that use RGB color profiles. You can use the convertProfile command to convert the color to an RGB profile.

SVG The saveOptimized command converts SVG content to the Raster format, then saves it in the preferred format using any optimization settings that were set in Illustrator using Save For Web, or set previously in ADS. You can us e t he set command to modify optimization settings within ADS. If the current content does not contain optimization settings, the command writes a GIF file using built-in default optimization settings.

PDF The saveOptimized command saves to PDF 1.5 format optimized for Web use (the "Fast Web View"). This may make it much faster to read the file from a Web site. You cannot set any specific optimization parameters for PDF content.

The following table summarizes the file name extensions that this command assigns for file formats, and the versions of those formats that it writes.

TABLE 3.9 File extensions used by the saveOptimized command

Format Extension Version GIF .gif Written as version 89a. JPEG .jpeg Written as JFIF 1.2. PNG8/24 .png Written according to the PNG 1.2 specification (the PNG file format itself is not versioned). WBMP .wbmp Written as a WAP 1.1 type 0 image. PDF .pdf Written as linearized PDF 1.4.

For more information, see “Saving Optimized Files” on page 112.

Adobe Document Server Developers Guide Dec 19, 2003 63 ADS Command Basics Automatic File Saving 3 Saving Content

Setting Optimization Information There are two ways you can set or modify the optimization information in content before saving it: ● Use the optimizeToSize command to automatically set the preferred optimized file format for an RGB image. This command determines whether GIF or JPEG format results in a smaller file. ● Use the set command to explicitly modify or replace the optimizationSettings element in the content. The optimized save format is determined by the name of the child element you provide. The choices are: – GIFFormat – PNG8Format – PNG24Format – WBMPFormat – JPEGFormat The default optimization file format is GIF. Saving Metadata with Optimized Files In the saveOptimized command, you can use the optional metadata attribute to specify whether to save metadata with an optimized image file, and what metadata formats to save (XMP, EXIF, and/or IPTC). If you do not supply the attribute, no metadata is saved with the image file. (XMP metadata is always saved with PDF files.) You can specify any combination of the supported formats; however, the non-XMP formats apply only to JPEG files. If the file is not being written in JPEG format, those values are ignored. You can include XMP format metadata for any output file. If you specify any non-XMP formats for a JPEG file, the properties appropriate to the format are saved with the file. If you also specify XMP format, all current XMP metadata is saved with the file. Upon save, metadata values in all formats are guaranteed to be consistent. For more information, see Chapter 4, “Working with File Metadata.”

Automatic File Saving After every command in the request has been processed, in the absence of any explicit saveOptimized or saveContent commands, ADS performs an implicit save operation on the current content. Which save command it uses depends on the type of the current content.

Content type Save command used

RGB Raster, SVG, PDF saveOptimized

CMYK Raster, PostScript, XML, XMP, saveContent XSL-FO, FormData, Frame

When a result file is created by an automatic save operation, it is given the name Untitled, and the appropriate file extension is appended.

64 Dec 19, 2003 Adobe Document Server Developers Guide Automatic File Saving ADS Command Basics Referenced Attributes Values 3

When you pass a file to ADS on the command line in the -source argument and do not specify a command file, an automatic save is performed on the file, and the result is saved with the default name in the current working directory or the result location, if specified.

Referenced Attributes Values

ADS defines a special reference function you can use to access named content and retrieve values from it, as long as that content is accessible with abbreviated XPath syntax. You can use such a content reference anywhere as an attribute value. A content reference can be useful for retrieving values from loaded content at run time, when you do not know ahead of time what those values will be. When ADS executes a command containing a content reference, it first evaluates the reference, then passes the result to the command as the attribute value. If the reference does not evaluate to the expected value type, the command reports an error. The syntax for a content reference is as follows: reference(adobe-content:contentName#XPath) The #XPath portion of the specification is optional. If it is not supplied, the expression evaluates to the entire named content. For example, suppose you load and name the following simple XML content: ● The following reference extracts the string value "dog" from the d attribute of the B element: reference(adobe-content:myXml#/A/B/@d) You could pass this reference for an attribute that expected a text-string value. ● The following reference, with no XPath, evaluates to the entire named content: reference(adobe-content:myXml) Note that this reference does not evaluate to the content-name string, "myXml", but to the entire named content, the string "".

Adobe Document Server Developers Guide Dec 19, 2003 65 ADS Command Basics Automatic File Saving 3 General Commands

EXAMPLE 3.1 Using a content reference to select an image at run time The following commands load the sample XML shown above from an external source and use the reference syntax to select and operate on the dog image: In this example, you do not need to know which of the loaded images is wanted when you write the commands. The name of the desired image file is specified in the selectPet.xml file; the content of this file is accessed during execution to determine which content name is used by the flip command.

General Commands

The following commands report on or affect the state of the system and do not operate on content: ● info: Reports information about the ADS application, such as copyright information and Adobe personnel involved on the project, in XML format. ● version: Reports the current ADS version information in XML format. ● registerMetadataNamespace: Creates an XML namespace for use with metadata, and requests a prefix to be associated with it. For more information, see Chapter 4, “Working with File Metadata.”

66 Dec 19, 2003 Adobe Document Server Developers Guide 4 Working with File Metadata

This chapter describes how ADS deals with metadata in the files that you can load and manipulate. It contains the following sections:

Overview of Metadata starting on page 67 Working with Metadata in ADS starting on page 69 Transformations of Metadata Formats starting on page 78

Overview of Metadata

ADS uses Extensible Metadata Platform technology (XMP) to handle metadata associated with many content types. XMP is a framework for XML metadata exchange and a labeling system for document and digital assets. XMP defines a mechanism for placing metadata in a variety of file formats. ADS can read and write metadata values in both XMP (for Raster, SVG, and PDF content) and in the EXIF and IPTC formats (defined for PSD, TIFF, and JPEG). However, it manages all metadata internally in the XMP format, and you must use the XMP format for modifying metadata. ADS handles the translation to and from XMP and other formats upon load and save; see “Transformations of Metadata Formats” on page 78. When you load a file into ADS, ADS resolves any conflicts in corresponding metadata values from different formats. When you save a file from ADS, metadata values are guaranteed to be consistent in all formats. ADS operates only on document-level metadata. If a file contains component-level metadata (such as metadata stored in an embedded JPG image in a PDF file), ADS preserves it, but does not allow you to access it. ADS supplies commands for extracting and replacing metadata, and for manipulating individual metadata values. See “Working with Metadata in ADS” on page 69.

Metadata and Content Types ADS represents and manipulates metadata in the XMP format. When it loads a file, it translates all supported metadata formats into the XMP format. Properties from each original format go into a specific namespace, so that they can be restored to that format on save. See “Transformations of Metadata Formats” on page 78.

Adobe Document Server Developers Guide Dec 19, 2003 67 Working with File Metadata Creating a Custom Metadata Schema 4 Overview of Metadata

You can extract metadata from a file using the exportMetadata command. The metadata is returned as XMP content. XMP content contains data in the XML Packet format; however, it is not the same as XML content. XMP and XML content cannot be used interchangeably. ● When you save the XMP content, the saveContent command provides the .xmp file extension and saves the file as an XML Packet using the XMP packet wrapper. ● You can reload the saved metadata in another ADS session using the loadContent command, and, if you wish, use it to replace all of the metadata for a file, using the importMetadata command. When ADS loads an XML Packet with the XMP packet wrapper, it treats it as XMP content, rather than XML content. All metadata manipulation operations other than importMetadata act on XMP metadata embedded in content of the various supported types: PDF, Raster, and SVG. The saveContent command automatically transforms the current XMP metadata to all metadata formats supported for the content type, and embeds it in the output file. The saveOptimized command allows you to specify whether or not to write out metadata with the optimized file, and, if you include metadata, which formats to include.

Creating a Custom Metadata Schema ADS defines standard XMP namespaces, and in addition defines namespaces for XMP properties that are created from EXIF– and IPTC–format metadata. See “Metadata Namespaces” on page 80. If you add or modify properties in these namespaces, the save commands can write out that information to the EXIF and IPTC formats. See “Saving Files with Metadata” on page 77. Within ADS, you can register your own metadata namespace that identifies a custom metadata scheme. Before manipulating the metadata, register your namespace with ADS using the registerMetadataNamespace command. The namespace is then recognized throughout the current ADS request, and you can add or modify properties in that namespace, using the metadata manipulation commands. When ADS writes out XMP metadata, by itself or embedded in a file, each namespace is associated with a prefix in the XML Packet. For example, the following XML Packet fragment specifies that the namespace http://ns.adobe.com/photoshop/1.0/ is associated with the prefix photoshop, as in the following code fragment: jsmith Thereafter, the file always uses the prefix to refer to that namespace (as illustrated here for the Author property). In the registerMetadataNamespace command, you suggest a prefix to be used for your namespace. If that prefix is already in use, ADS assigns a unique generated prefix for the namespace. You must always use a complete namespace to specify metadata properties in ADS metadata manipulation commands.

68 Dec 19, 2003 Adobe Document Server Developers Guide Extracting Metadata from Loaded Content Working with File Metadata Working with Metadata in ADS 4

Working with Metadata in ADS

When you load a file into ADS, it creates an XMP representation of that file’s metadata, translating properties as needed from IPTC and EXIF metadata formats. ● You can extract metadata from a loaded file and write it out to an XMP file. ● You can modify the metadata in a loaded file by adding or deleting properties, changing property values, or completely replacing the metadata with a new XML Packet.

Extracting Metadata from Loaded Content To extract metadata in ADS content, use the exportMetadata command. This command copies all of the existing XMP-format document-level metadata for the current content into a new XMP content holder, which contains the data in the XML Packet format. The command makes the new XMP content current. The XMP contains the namespaces required to preserve metadata that was loaded from other supported formats (IPTC and EXIF), as well any other namespaces used in the file. Because ADS does not support program-logic branching in its command syntax, you cannot make metadata-based decisions inside ADS. You can, however, extract and write out metadata to a separate file, read that file outside ADS, and make decisions based on the values. Once you have extracted metadata from ADS content, you can use the saveContent command to save the extracted XMP data as an XML Packet. For example: This example creates a file myImageMetadata.xmp, which contains: ● All of the XMP metadata loaded with myImage.psd. ● Any properties that were originally defined in the IPTC and EXIF formats, in the appropriate namespaces. ● Metadata properties created by ADS to reflect its own manipulation of the file (see “Automatic Metadata Updates” on page 82). The following three examples show excerpts of exported metadata from various files, showing how IPTC, EXIF, and XMP metadata are expressed.

NOTE: The actual information returned by the exportMetadata command varies by the original file type of the content and the application (and version) that last touched the file before it was loaded into ADS.

Adobe Document Server Developers Guide Dec 19, 2003 69 Working with File Metadata Extracting Metadata from Loaded Content 4 Working with Metadata in ADS

EXAMPLE 4.1 Metadata from IPTC format The following example shows part of the result of exporting metadata from a PSD file, in which much of the metadata was expressed in IPTC format. The output is an XML Packet. The IPTC metadata is reflected in the photoshop namespace. 65535 Joe Smith iLucy These are the instructions Lead Developer, Smith Engineering Joe Rebecca Boulder CO USA Transmission Reference cat 2000-05-09 1 Cat1 Cat2 Cat3

70 Dec 19, 2003 Adobe Document Server Developers Guide Extracting Metadata from Loaded Content Working with File Metadata Working with Metadata in ADS 4

. . . . . TIFF aliases omitted . . . 6 506 0 1 2 72/1 72/1 3 1 8 8 8 . . . XMP metadata omitted . . .

Adobe Document Server Developers Guide Dec 19, 2003 71 Working with File Metadata Extracting Metadata from Loaded Content 4 Working with Metadata in ADS

EXAMPLE 4.2 Metadata from EXIF format The following is an example of the XMP representation of metadata that was originally in the EXIF format: 1 2 3 0 The image's title

72 Dec 19, 2003 Adobe Document Server Developers Guide Extracting Metadata from Loaded Content Working with File Metadata Working with Metadata in ADS 4

EXAMPLE 4.3 XMP Metadata in a PDF file The following is an example of XMP metadata extracted from PDF content: Acrobat Distiller 5.0.5 (Windows) 1997-04-15T18:17:39Z 2002-07-25T13:58:04-05:00 2002-07-25T13:58:04-05:00 FrameMaker 6.0 23 jsmith Sample.fm

Adobe Document Server Developers Guide Dec 19, 2003 73 Working with File Metadata Modifying Metadata in Loaded Content 4 Working with Metadata in ADS

Modifying Metadata in Loaded Content You can modify the metadata in a loaded file by adding or deleting properties, changing property values, or completely replacing the metadata with a new XML Packet. Adding and Modifying Non-Structured Properties To add a new non-structured (scalar) property and its value, or to change the value of an existing property, use the command setMetadata. When you add new metadata in ADS using the setMetadata command, it is created according to the W3C Resource Description Framework (RDF). For more information on this syntax, see http://www.w3.org/TR/1999/REC-rdf-syntax-19990222. ADS uses a set of aliases defined in the XMP specification for equivalent properties. Any alias can be used to refer to the source property, which contains the value. When you specify an alias as the property to be modified, ADS modifies the source. (See “Metadata Aliases” on page 81.)

EXAMPLE 4.4 Modifying a metadata property This example loads a PSD file, sets the metadata property AuthorsPosition to the value artist, then saves the content to a new PSD file. The file is saved with embedded XMP, EXIF, and IPTC metadata. The new property value is in the namespace for IPTC, so the new value will be seen both in the XMP data and in the IPTC metadata that you can view in Photoshop, as artist. Note that you must supply the complete namespace in the namespace property, not the prefix. Adding and Modifying Structured Properties Structured metadata properties are containers for multiple items. There are three types of structured properties, which reflect different restraints on the value set: ● The type bag contains an unordered list of items. ● The type sequence contains an ordered sequence of items. ● The type alternative contains a set of alternative items. Use the command createMetadata to create a new structured property along with its first item. For an existing structured property, use the command appendMetadata to add a new item, before or after an existing item. Use the command setMetadata to set the value of an existing item.

74 Dec 19, 2003 Adobe Document Server Developers Guide Modifying Metadata in Loaded Content Working with File Metadata Working with Metadata in ADS 4

EXAMPLE 4.5 Creating and adding to a structured property This example loads a PSD file and creates a new structured metadata property named Keywords in the standard XMP namespace. The new property is of type bag, indicating an unordered list of items. The first item is Keyword1. The example then adds a second item to the property, Keyword2, appending it to the first item (regardless of what that item was). It then saves the Raster content as a new PSD file (with embedded XMP, IPTC, and EXIF metadata), changes the value of the second Keywords item, and saves the file with the new value. Deleting Metadata You can delete an individual property, or delete all current metadata by replacing it with different XMP data. To delete an individual property, use the removeMetadata command, specifying the full namespace and name of the property. For example: To remove an item from a structured property, provide the XPath to that item in the path attribute. For example: ADS uses a set of aliases defined in the XMP specification for equivalent properties. You can use any defined alias to refer to the source property, which contains the value. When you specify an alias as the property to be deleted, ADS deletes the source property. (See “Metadata Aliases” on page 81.) ● If you do not specify any namespace in the removeMetadata command, ADS deletes all of the current metadata and replaces it with a default XML Packet containing those properties automatically updated by ADS. ● If you specify the namespace but not the path, ADS deletes all metadata in the specified namespace.

Adobe Document Server Developers Guide Dec 19, 2003 75 Working with File Metadata Modifying Metadata in Loaded Content 4 Working with Metadata in ADS

Replacing Metadata You can completely replace the metadata for the current content with a new set of properties, with the importMetadata command. All metadata associated with the content is removed and replaced with the new XML Packet that you provide. You can specify the new XML Packet in one of several ways, as shown in the next three examples.

EXAMPLE 4.6 Streaming in replacement metadata in the importMetadata command This example loads the XML Packet inline between importMetadata tags.

NOTE: You cannot load XMP data inline into ADS using loadContent. The loadContent command would interpret the XML Packet as XML and store it as XML content, which you cannot pass to importMetadata.

2002-08-28T09:08:09Z

EXAMPLE 4.7 Loading replacement metadata from a file This example loads the XML Packet from an XMP file and names it using the out attribute of loadContent. It is stored as XMP content. You then refer to the named XMP content in the source attribute of importMetadata.

76 Dec 19, 2003 Adobe Document Server Developers Guide Saving Files with Metadata Working with File Metadata Working with Metadata in ADS 4

EXAMPLE 4.8 Copying metadata from one file to another This example extracts and stores metadata from one PSD file, then loads another PSD file. It refers to the stored XMP content as the replacement value for metadata in the new current content.

Saving Files with Metadata When you save a file with the saveContent command, ADS writes out all of the current metadata with the file in the XMP format. If there was any metadata transformed from other formats on load, it is copied back to that format on save. Because the load process resolved all conflicts between different formats, metadata values are guaranteed to be consistent in all formats when you save a file from ADS. ADS derives some metadata values automatically (see “Automatic Metadata Updates” on page 82). These values are saved along with values that have been preserved from load or explicitly set in ADS. If you do not want to save a metadata property with a file, use the removeMetadata command to remove it before saving the file. However, you cannot remove those metadata properties that are automatically updated by ADS. Specifying Formats for Optimized Image Files When you save optimized image files, you can specify whether to save metadata with the files, and which formats to save it in. To do this, use the metadata attribute of the saveOptimized command. The metadata attribute takes a list of supported metadata formats to save, separated by spaces. You can give any combination of the three formats, or none. If you do not supply the attribute, or if you give an empty string, the command does not save any metadata with the file. The three supported formats are XMP, EXIF, and IPTC. Of the optimized file types, only JPEG files can be written with EXIF and/or IPTC metadata. If you specify a format that is not supported for the type of file being saved, that attribute value is ignored. The optimization settings for the JPEG file format also include an embedMetadata attribute. (See the chapter “Accessing Raster Content” in the Adobe Document Server XML Grammars Reference.) If this attribute is true, IPTC metadata is embedded in the file regardless of the value of the saveOptimized metadata attribute. In this case, you can use the saveOptimized metadata attribute to specify XMP and/or EXIF in addition to the IPTC format.

Adobe Document Server Developers Guide Dec 19, 2003 77 Working with File Metadata Supported Metadata Formats 4 Transformations of Metadata Formats

EXAMPLE 4.9 Saving an optimized image with a new metadata property

Transformations of Metadata Formats

When you load files into ADS, ADS uses a set of aliases and precedence rules to resolve equivalent metadata properties from different formats to a single value. It automatically derives and adds certain metadata values that reflect its own manipulation of the files. When you save content containing metadata, the saveContent command transforms the information into all of the metadata formats that apply to the file format, and saves them along with the XMP. This ensures that metadata within and saved from ADS is consistent across all formats. The saveOptimized command similarly transforms the metadata into those formats that you specify, if they apply to the saved file format. This section describes: ● Metadata formats that ADS supports for each file type. ● The namespaces ADS uses to represent non-XMP metadata. ● The aliases that define equivalencies among namespaces. ● The metadata values that ADS derives automatically. ● The precedence rules ADS uses to resolve property value conflicts.

Supported Metadata Formats Table 4.1 shows the metadata formats that ADS supports for each file format. It describes how ADS treats the metadata in each kind of file upon load, and how ADS treats metadata when content loaded from one format is converted to a different format.

78 Dec 19, 2003 Adobe Document Server Developers Guide Supported Metadata Formats Working with File Metadata Transformations of Metadata Formats 4

TABLE 4.1 Supported metadata formats

Metadata File format formats Metadata support on load, save, and convert

PSD XMP, IPTC, EXIF ADS preserves EXIF, IPTC and XMP metadata on load. •The saveContent command writes out all supported JPEG XMP, IPTC, EXIF metadata formats for PSD and TIFF files. TIFF XMP, IPTC, EXIF •The saveOptimized command writes out only the metadata formats you specify that are supported for the GIF XMP destination file format. Only the JPEG format supports EXIF and IPTC formats. The optimization settings for PNG XMP JPEG also affect whether IPTC metadata is saved with the file.

SVG XMP ADS preserves the document-level XMP metadata in SVG files on load, but ignores metadata stored in other metadata elements. When you convert SVG content to PDF content, some of the PDF metadata is updated (see “Automatic Metadata Updates” on page 82). Metadata embedded in images that are referenced in the SVG remains inside the image in the resulting PDF file, but is not accessible to ADS.

PDF XMP, PDF 1.5 The rules for XMP metadata propagation to the PDF Info dictionary are described in the XMP Framework documentation. Upon load, ADS updates the NPages property in the namespace http://ns.adobe.com/xap/1.0/t/pg/ to reflect the number of pages in the document. When you use the convertPDFToRaster command, the document-level metadata is preserved, but any metadata associated with embedded images is lost. For operations that combine multiple PDF documents, or multiple portions of PDF documents, the metadata of the destination document is preserved, and the metadata for the donor document is discarded. Metadata carried inside images in both documents is preserved. If necessary, you can retrieve desired metadata before the conversion operation, then restore it after the operation.

PhotoShop EPS XMP When you convert an EPS file created by Photoshop to Raster format, XMP metadata is preserved and can be saved with the file. When you convert Raster content to Photoshop EPS, all metadata is preserved in XMP format and is saved by the saveContent command.

Adobe Document Server Developers Guide Dec 19, 2003 79 Working with File Metadata Metadata Namespaces 4 Transformations of Metadata Formats

TABLE 4.1 Supported metadata formats (Continued)

Metadata File format formats Metadata support on load, save, and convert

generic EPS, -- ADS cannot access metadata in generic EPS or PostScript PostScript files, even when the metadata is stored in XMP format. Any metadata that was in the loaded file is saved with the file by the saveContent command. When you convert EPS files that were not created by Photoshop to Raster content, ADS does not preserve metadata, even if it is in XMP format.

XSL-FO XMP When you use the formatXSL command to create PDF content, XMP metadata in the XSL-FO file is preserved in the PDF.

Metadata Namespaces ADS uses the following preregistered XMP namespaces:

TABLE 4.2 Preregistered namespaces

Namespace Prefix

http://ns.adobe.com/xap/1.0/ xap http://ns.adobe.com/xap/1.0/g/ xapG http://ns.adobe.com/xap/1.0/g/img/ xapGImg http://ns.adobe.com/xap/1.0/dyn/ xapDyn http://ns.adobe.com/xap/1.0/dyn/a/ xapDynA http://ns.adobe.com/xap/1.0/dyn/v/ xapDynV http://ns.adobe.com/xap/1.0/t/ xapT http://ns.adobe.com/xap/1.0/t/pg/ xapTPg http://ns.adobe.com/xap/1.0/rights/ xapRights http://ns.adobe.com/xap/1.0/mm/ xapMM http://ns.adobe.com/xap/1.0/s/ xapS http://ns.adobe.com/xap/1.0/bj/ xapBJ http://ns.adobe.com/pdf/1.3/ pdf http://purl.org/dc/elements/1.1/ dc http://ns.adobe.com/tiff/1.0 tiff http://ns.adobe.com/exif/1.0 exif http://ns.adobe.com/photoshop/1.0/ photoshop

80 Dec 19, 2003 Adobe Document Server Developers Guide Metadata Aliases Working with File Metadata Transformations of Metadata Formats 4

When you load a file containing metadata into ADS, ADS transforms properties from EXIF and IPTC formats into XMP equivalents in their respective namespaces. The properties can be transformed back to the original format upon save. ● Properties read from the EXIF format may be in the tiff or exif namespace. ADS base-64-encodes some EXIF values. In these cases, the value is prefaced with the string 'base64,'. ● Properties in the photoshop namespace are equivalent to fields available through the PhotoShop File Info dialog, which PhotoShop may store as IPTC or XMP or both. Because IPTC metadata is often stored without any encoding information, ADS uses the following rules to map unencoded character values when converting between IPTC and XMP: – Invalid 7-bit characters appearing in IPTC fields (that is, non-graphic characters other than space, newline, carriage return, and tab) are mapped to a question mark when converted to XMP. – 8-bit characters appearing in IPTC fields without encoding information are mapped to a question mark when converted to XMP. (IPTC allows 8-bit encodings to be specified, but Photoshop does not.) – Non-ASCII characters in XMP fields are converted to an ASCII character (question mark or appropriate fallback character) when mapping from XMP to IPTC.

Metadata Aliases To ensure consistency of metadata, ADS uses equivalencies among the metadata formats that it supports. The XMP toolkit defines aliases from equivalent properties in other namespaces to a source property, usually in the Dublin Core (dc) namespace. When ADS reads in metadata from an aliased property, it stores the value in the source property. You can refer to a property by any of its aliases. When you specify an alias in a metadata command, ADS performs the operation on the source property for that alias. For example, the XMP property dc:description is the source for the aliased fields xap:Description, tiff:imageDescription, and photoshop:Caption. When ADS reads a file that has any one of these values, it creates the source property (dc:description). The source property contains the value, regardless of where the value came from. The aliases do not have values, but simply point to the source, dc:description. The following fragment of an XML Packet illustrates how aliases are shown at the beginning of the packet:

Adobe Document Server Developers Guide Dec 19, 2003 81 Working with File Metadata Automatic Metadata Updates 4 Transformations of Metadata Formats

Automatic Metadata Updates When you save content from ADS, some internal metadata properties such as xap:MetadataDate are automatically updated. Other metadata values, such as the size or bit depth of an image, that are derived from the data, cannot be set explicitly, but may be updated automatically on save. Derived properties are not automatically copied to the IPTC or EXIF metadata formats. If metadata is not present in either IPTC or EXIF format in the source document, it is not present in the output in that format, unless you specifically add it using ADS commands. The following table lists metadata properties that are automatically updated during format conversion and file save operations.

TABLE 4.3 Metadata fields modified by ADS

Command Fields modified

saveContent (SVG) xap:Format xap:MetaDataDate xap:ModifyDate

saveContent (PDF) pdf:ModDate xap:Format xap:MetaDataDate xap:ModifyDate

saveContent (EPS) xap:Format xap:MetaDataDate xap:ModifyDate

NOTE: Metadata is not saved with PostScript content that does not conform to PhotoShop-compatible encapsulated PostScript.

saveContent (PSD) stDim:w saveOptimized (JPG, GIF, PNG) stDim:h xap:Format xap:MetaDataDate xap:ModifyDate

saveContent (TIFF) stDim:w stDim:h tiff:BitsPerSample tiff:ColorSpace tiff:ResolutionUnit tiff:SamplesPerPixel tiff:XResolution tiff:YResolution xap:Format xap:MetaDataDate xap:ModifyDate

82 Dec 19, 2003 Adobe Document Server Developers Guide Resolving Metadata Inconsistency Working with File Metadata Transformations of Metadata Formats 4

TABLE 4.3 Metadata fields modified by ADS (Continued)

Command Fields modified

formatXSL pdf:Producer convertSVGToPDF convertRasterToPDF convertPSToPDF

convertPDFToEPS none convertPDFToRaster convertPSToRaster convertRasterToEPS convertSVGToRaster convertTo (SVG to Raster)

Resolving Metadata Inconsistency Some tools read and write only a particular format of metadata, ignoring any others. If such a tool has modified the metadata at any point, it can become inconsistent — that is, equivalent properties can have different values. If a file contains inconsistent metadata, ADS resolves the inconsistency when you load the file, so that metadata in loaded content and metadata in files that you save from ADS is always consistent. If values of equivalent properties are inconsistent between formats, ADS applies precedence rules to determine the final value. In general, if a file contains XMP metadata, ADS uses the XMP property value, unless it can determine that an equivalent property in another format has been updated more recently. The following table describes the rules that govern which value takes precedence.

TABLE 4.4 Metadata format precedence for file types

File format Metadata precedence rules

PSD, TIFF ADS reads information in the following order, replacing earlier values with later values: • kCaptionID image resource For older Photoshop files, the caption data is read from the image resource ‘1008’ (kOldCaptionID) or ‘1020’ (kPrintCaptionID). It cannot appear in both. • Image Description Tag (TIFF only) • IPTC-NAA Tag (TIFF only) TIFF information is read before image resource information, so an edit to the TIFF information is not recognized unless the image resource information is removed. For Photoshop 6.5 XMP Data, the kCaptionID image resource is written out with a digest signature. The digest is regenerated. If it does not match, then the XMP information is dropped. Otherwise the XMP information is used instead of all previous data.

Adobe Document Server Developers Guide Dec 19, 2003 83 Working with File Metadata Resolving Metadata Inconsistency 4 Transformations of Metadata Formats

TABLE 4.4 Metadata format precedence for file types

File format Metadata precedence rules

SVG ADS reads and preserves only XMP metadata.

PDF PDF files can have metadata stored in two places: the Info dictionary, and as XMP. ADS parses any existing XMP metadata first. If the Info dictionary information is older than the XMP data, ADS ignores it. If the Info dictionary information is newer, ADS uses it. • Keys that correspond with XMP keys go into the pdf namespace. • Keys that do not correspond with XMP go into the pdfx namespace.

84 Dec 19, 2003 Adobe Document Server Developers Guide Part III

Graphics

Adobe Document Server Developers Guide Dec 19, 2003 85 86 Dec 19, 2003 Adobe Document Server Developers Guide 5 Basic Image Manipulations

This chapter describes how to perform various image manipulation tasks using ADS commands, how to convert document formats to image formats, and how to save images to various optimized file formats. It also discusses the versions of other Adobe products (such as Illustrator and Photoshop) in which image file features were added, to help you in planning how to use ADS with legacy image source files. This chapter contains the following sections:

Overview starting on page 87 Sizing and Cropping Images starting on page 88 Layer Manipulations starting on page 95 Working with Color starting on page 99 Modifying Image Data starting on page 103 Accessing Raster Content starting on page 109 Treating PostScript and PDF Content as Images starting on page 112 Saving Optimized Files starting on page 112 Legacy File Limitations starting on page 118

Overview

You can use ADS to perform programmatic manipulations of images in a number of ways: ● Use specific image-related commands to do the following: – Change the size of an image, crop or trim it, or change its orientation. – Add, remove, position, or flatten layers. – Change the color mapping in the image. – Replace a pixel or text layer. This chapter provides information and examples to help with these tasks. (For detailed information on each command, see the Adobe Document Server Command Reference.) ● Use the more general set command to manipulate some elements of the Raster content directly, using the ADS Raster content model. See the chapter “Accessing Raster Content” in the Adobe Document Server XML Grammars Reference. ● Use automatic or explicit variable replacement to provide new values at run time for variables you have defined in a PSD or SVG file using Photoshop or Illustrator. For details, see Chapter 7, “Replacing Variables in SVG and PSD Files.”

Adobe Document Server Developers Guide Dec 19, 2003 87 Basic Image Manipulations Changing the Canvas Size 5 Sizing and Cropping Images

ADS transforms non-PSD image files into the internal, PSD-like Raster format on load, so you can manipulate all images as if they had originated in the PSD format. You can convert Raster content to other kinds of content, and save Raster content to a variety of file formats. For more information on converting Raster content to and from other content types and file formats, see: ● “Accessing Raster Content” on page 109 ● “Saving Optimized Files” on page 112 ● “Converting Content” on page 57 and “Saving Content” on page 59 You can load SVG content from a file, or inline in a loadContent command. SVG can contain image references or embedded images in a variety of formats. Some of the information in this chapter applies to SVG, but most is about Raster content. For more information on SVG, see Chapter 9, “Creating Dynamic Graphs in SVG Files” and Chapter 8, “Operations Specific to SVG Files.”

Sizing and Cropping Images

ADS provides commands that you can use to: ● Increase or decrease the size of the image canvas by adding or removing border pixels, or by cropping any pixels outside the interesting area. ● Change the overall image size by setting new pixel dimensions, document dimensions, resolution, or some combination.

Changing the Canvas Size ADS provides commands to change the canvas size by adding or removing work space around an existing image. They adjust the size with reference only to the outside dimensions, not with reference to the image area. The canvas size commands can either increase or decrease the canvas size. ● canvasSize command: Specify a new absolute width and height for the canvas. ● canvasSizeRelative command: Specify a new width and height relative to the original width and height of the canvas. If you increase the canvas size, added canvas appears transparent if the image does not have a background layer. If the image does have a background layer, then added pixels appear opaque white.

88 Dec 19, 2003 Adobe Document Server Developers Guide Changing the Canvas Size Basic Image Manipulations Sizing and Cropping Images 5

EXAMPLE 5.1 Increasing canvas size by adding a border This sample increases the canvas size of the guitar image to 300 by 600 pixels. It centers the original image by adding equal numbers of pixels to the top and bottom, and to the left and right. Because this image does not have a background layer, added canvas pixels are transparent. You can decrease the canvas area by using the canvas size commands to specify an arbitrary desired border area. Alternatively, you can use one of the cropping commands, which change the canvas based on the image data. To reduce the canvas size while maintaining a particular image area, use one of the following commands: ● crop command: Allows you to specify a crop rectangle that is equivalent to the crop rectangle you drag over an image using the Photoshop cropping tool. ● trim command: Shaves pixels on the edges of the image that are of constant color. For example, on a printed page, the margins are all white. If you trim an image representing a printed page, all of the margins are automatically removed. This command is equivalent to the trim command in Photoshop. ● applyClipPath command: A clipping path in an image is used to define a cropping region when printing. This command applies the clipping path’s cropping region on the image for outputs other than print workflows. You might use this command, for example, to update a legacy print image for Web use.

EXAMPLE 5.2 Trimming an image This sample first performs a default trimming operation on the guitar image, trimming unneeded transparent pixels from all edges of the background to make the image fill the canvas, and reduce the file size. The second trim command further trims the image by removing pixels on the left and right sides that are of the top left color.

Adobe Document Server Developers Guide Dec 19, 2003 89 Basic Image Manipulations Changing Image Size 5 Sizing and Cropping Images

EXAMPLE 5.3 Applying a clipping path This sample flattens the layers in the guitar image so that the clipping path can be applied to the entire image. It retains the clipping path information in the result.

Changing Image Size The ADS imageSize command directly parallels the Photoshop image size command. Use it to increase or reduce the total image size. You might resize an image, for example, to create a thumbnail, medium, and large version for a Web-based retail catalog. This can be a complex operation, in which you make choices that affect the image quality. To modify the image size, you specify variables in the fundamental size equation: number_of_pixels = measured_size * resolution The command has optional attributes for providing a width or height in pixels, a document width or height in a measurement such as inches or centimeters, and a specific resolution. You can modify only the size, only the resolution, or both the size and resolution. If you want to change both size and resolution, it is best to do so in one command, to avoid unnecessary resampling that could occur if the two were run as distinct operations. Specifying values for all three variables in either width or height overconstrains the equation. Unless the values fit the equation perfectly, this causes an error. Fractional numbers in computer systems are often not exactly represented and can cause unexpected errors in overconstrained conditions. It is recommended that you do not specify all three variables. Unless you specify otherwise, the command maintains the aspect ratio of the original image. If you specify only width, proportions are constrained by the width. If you specify only height, proportions are constrained by the height. If you specify both height and width, proportions are constrained by the smaller value. For details of the attribute names and values, see the imageSize command in the Adobe Document Server Command Reference.

90 Dec 19, 2003 Adobe Document Server Developers Guide Changing Image Size Basic Image Manipulations Sizing and Cropping Images 5

EXAMPLE 5.4 Making successive size modifications on the same image This sample loads the guitar.psd file, containing a guitar image that is 205 pixels by 511 pixels, and performs a series of size transformations. Each transformation is numbered and described below. 1 2 3 1. Resizes the image to be 200 pixels by 500 pixels. 2. Resizes the image again to be 150 pixels in width. Because it maintains the aspect ratio by default, the height becomes 375 pixels. 3. Has no effect, because changing the width to 200 would enlarge the image and the scale policy is set to doNotEnlarge. (For more examples of scaling policies, see “Scaling Policies” below.)

EXAMPLE 5.5 Changing the resolution of an image This sample loads the logo.psd file, containing an image that is 200 by 200 pixels, with a resolution of 72 DPI. It performs a series of transformations, specifying a new resolution each time. Each command allows constrainProportions to default to true, maintaining the aspect ratio. Depending on the other parameters, each resolution change has a different effect on the pixel and document size. Each change is numbered and described below. 1 2 3 4

Adobe Document Server Developers Guide Dec 19, 2003 91 Basic Image Manipulations Changing Image Size 5 Sizing and Cropping Images

1. Reducing the resolution to 300 DPI and allowing resampling leaves the document size unchanged, but reduces the pixel size to 139x139. 2. Reducing the resolution to 300 DPI and without resampling changes the document size to 4x4 inches, leaving the pixel size unchanged. 3. Increasing the resolution to 96 DPI and reducing the document width to 1.5 inches reduces the document height to 1.5 inches, and the pixel size to 144x144. 4. Increasing the resolution to 96 DPI and reducing the pixel width to 100 pixels reduces the pixel height to 100 pixels, and the document size to 1.042x1.042 inches. Scaling Policies Both the imageSize and replacePixels commands allow you to set a scaling policy. The scaling policy determines whether and how to limit the maximum or minimum size of the resized image. ● If the scaling policy is free (the default), then the resulting size will have the largest width and height possible such that neither exceeds the width and height of the target size and the aspect ratio is preserved. For example, a 1x2 pixel image with a target size of 4x4 will have a resulting size of 2x4. If either width or height is omitted, the resulting image will have exactly the height or width specified. The size of the image in the omitted dimension is scaled as appropriate to maintain the aspect ratio of the image. (Omitting both width and height results in no change to the size of the image.) ● If the scaling policy is doNotEnlarge then the actual target size of the image is the smallest of the specified target size and the original image size. This is useful when shrinking a set of images of unknown size to some maximum target size while not enlarging images that are already sufficiently small. For example, if a set of images with sizes 1x1, 10x10, and 100x100 were resized to 20x20 with constrainProportions="true" and scalePolicy="doNotEnlarge", the resulting image sizes would be 1x1, 10x10, and 20x20. ● If the scaling policy is doNotShrink then the actual target size of the image is the largest of the specified target size and the original image. This is useful when enlarging a set of images of unknown size to some minimum target size while not shrinking images that are already sufficiently large. For example, if a set of images with sizes 1x1, 10x10, and 100x100 were resized to 20x20 with constrainProportions="true" and scalePolicy="doNotShrink", the resulting image sizes would be 20x20, 20x20, and 100x100.

92 Dec 19, 2003 Adobe Document Server Developers Guide Changing Image Size Basic Image Manipulations Sizing and Cropping Images 5

EXAMPLE 5.6 The effects of attempted size changes on different images Suppose you have the following images (not shown to scale):

Image A: Image B: Image C 1in x 4in, 50 x 200 pixels 6in x 2in, 300 x100 pixels 2in x 2in, 400 x 400 pixels dpi = 50 dpi = 50 dpi = 200

The following command examples with scaling policies and proportion constraints have different effects when applied to the different images, as shown. 1

Image A Image B Image C No change in dimensions, since Size changes to: Size changes to: modifying the width to 100 100 x 33 pixels 100 x 100 pixels would enlarge the pixel 2 x .66 inches 0.5 x 0.5 inches dimensions, which is prevented The scale policy allows the by the scale policy. image to become smaller, and the resolution remains the same.

2

Image A Image B Image C No change in dimensions. To No change in dimensions. The No change in dimensions. The maintain the proportions, the new image would be 2 x .66 command accepts the largest command tries to fit the image inches, 100 x 33 pixels. This values that fit in the box, which into the specified 2 x 3 inch box, would shrink the pixel are the current values of 2 x 2 which would result in an image dimensions, which is prevented inches. of 0.75 x 3 inches, 37 x 150 by the scale policy. pixels. This would shrink the pixel dimensions, which is prevented by the scale policy.

Adobe Document Server Developers Guide Dec 19, 2003 93 Basic Image Manipulations Changing Image Size 5 Sizing and Cropping Images

3

Image A Image B Image C Size changes to: No change in dimensions. The No change in dimensions. The 1.5 x 6 inches current 6 x 2 inch image fits in new size would be 6 x 6 inches, 75 x 300 pixels the specified 6 x 6 inch box. 300 x 300 pixels, which would Proportions and resolution are shrink the pixel dimensions, Both the pixel and document retained. which is prevented by the scale size are allowed to enlarge. policy.

4

Image A Image B Image C No change in dimensions. At 50 Size changes to: Size changes to: DPI, the new box would be 200 x 66 pixels, which fits the 200 x 200 pixels, which fits the 200 x 300 pixels. To maintain constraining box of 200 x 300 constraining box of 200 x 1200 proportions, the new size would pixels. pixels. be 75 x 300 pixels, which would 4 x 1.16 inches, which 1 x 1 inches, which maintains enlarge the pixel dimensions, maintains 50 DPI resolution. 200 DPI resolution. which is prevented by the scale policy.

Sharpening an Image After Resizing The unsharpMask command applies a traditional film compositing technique to sharpen edges in an RGB image. (This command does not work for CMYK images). The procedure corrects blurring introduced during photographing, scanning, resampling, or printing. It is useful for images intended for both print and online viewing. In a Web-oriented workflow, this command is very effective at restoring sharpness to images that were scaled down with the imageSize command. The unsharpMask command works on one layer at a time. If the image is not in a single layer, and if you want to sharpen multiple layers in a single pass, you must first flatten the image using the flatten command. The unsharpMask command allows you to specify a threshold, a radius and an amount. ● The threshold determines how different the brightness values between two pixels must be before they are considered edge pixels. Adjusting the threshold helps you to avoid sharpening the photographic grain in high-resolution scans. This is unlikely to be a problem at on-screen resolution, so it is best to use the default value of 0 for online images. ● The radius is the number of pixels surrounding the edge pixels that are affected by the sharpening operation. This can be an integer between 0 and 255. The default value, 1, is recommended for online images.

94 Dec 19, 2003 Adobe Document Server Developers Guide Referring to Layers Basic Image Manipulations Layer Manipulations 5

● The amount is the amount by which the command increases contrast for the affected pixels. This can be an integer between 1 and 500. The default is 50, and an amount between 50 and 120 is recommended for online images.

EXAMPLE 5.7 Resizing an image and sharpening edges This example loads a PSD image with multiple layers, resizes it, flattens it, and then sharpens the edges with a threshold setting of 0, a radius of 1.5, and the amount to sharpen set to 100. It then saves the modified image.

Layer Manipulations

ADS provides commands that you can use to manipulate image layers programmatically. You can add or delete layers (addLayer, deleteLayer), move a layer (setLayerPosition), or merge multiple layers into a single layer (flatten). In addition, you can use the set command to change the opacity and visibility of individual layers or of layer sets.

Referring to Layers Layer sets and layers are represented by the layerSet and layer elements. ● A layer element for a layer that is not in a layer set is a direct child of the root psd element. ● If there is a layer set, the layerSet element is a direct child of the root psd element, and the member layers are layer subelements of layerSet. In any command that take a layer attribute and in the target attribute of the set command you can reference layer and layerSet elements by index or by name, using the abbreviated XPath syntax. If there are layer sets, you must include the layer set in the XPath layer reference. For example:

/psd/layerSet[@name='myGroup']/layer[1] Refers to the first layer of a layer set named myGroup. /psd/layer[@name='grid'] Refers to a layer by name. /psd/layer[1] Refers to the bottommost layer by number. /psd/layer[last()] Refers to the topmost layer.

Adobe Document Server Developers Guide Dec 19, 2003 95 Basic Image Manipulations Setting Layer Visibility and Opacity 5 Layer Manipulations

/psd/layerSet[last()]/@opacity Refers to the opacity of the entire topmost layer set. /psd/layerSet[1]/@opacity Refers to the opacity of the entire bottommost layer set.

You cannot change the names of layers or layer sets with the set command; you must use Adobe Photoshop to change layer or layer set names. File and Layer Naming Conventions When preparing files in Photoshop for use with ADS, you can use a naming convention for both your PSD templates, and the layers and layer sets within a PSD template. A naming convention can make it easier to remember and reference file and layer names. Your naming convention should take ADS naming rules into account: ● Template file names cannot contain double-byte characters, although text within a text layer can contain double-byte characters. ● Template file names should contain only ASCII text. Avoid spaces in template file names. ● The maximum length for layer and layer set names is 255 characters. ADS truncates any characters beyond this limit and reports a warning to the error log. ● Referencing layers by name is easier and less error-prone if the layer name does not contain certain special characters, such as ampersands, quotes, or spaces. In particular, ADS cannot address layer or layer set names that include a dot character.

Setting Layer Visibility and Opacity You can use the set command to access layers and layer sets directly in order to set their visibility and opacity. Both layer and layerSet elements have visibility attributes. When a layer set is hidden, all of its member layers are also hidden, but when it is visible, the visibility of each layer is determined by its own visibility setting. Similarly, both layer and layerSet elements have opacity attributes. The opacity value is a floating-point number between 0 and 1. An opacity of 0 is completely transparent, and an opacity of 1.0 is completely opaque. When a layer is part of a layer set, the layer element’s own opacity value is interpreted as a percentage of the layer set’s opacity. The colorOverlay element can have an opacity attribute as well. This value determines the degree to which the overlay color replaces the layer color. A value of 1.0 means that it replaces the layer color entirely, and a value of 0 means that the original layer color is unchanged. The layer and layer set opacity values determine how visible the layer is after the color is modified by the color overlay.

96 Dec 19, 2003 Adobe Document Server Developers Guide Flattening Layers Basic Image Manipulations Layer Manipulations 5

EXAMPLE 5.8 Setting layer and layer-set visibility This example hides the entire layer set named set1 by setting the visibility attribute of the layerSet element, and saves the image to a GIF file. After saving the first version, it makes the layer set visible again, but hides one of the member layers.

EXAMPLE 5.9 Setting layer opacity This example sets the opacity of the layer named green to 0.1, making that layer almost transparent.

Flattening Layers You can use the flatten command to compress all image layers into a single layer. When you do this, all visible layers are merged into the background, while hidden layers are discarded. After you flatten an image, you can no longer access individual layers. You typically flatten an image in order to apply a single-layer command to the entire image. For example, you might flatten an image before applying one of the following commands: unsharpMask autoContrast autoLevels applyClipPath

Adobe Document Server Developers Guide Dec 19, 2003 97 Basic Image Manipulations Layers in Images from Other Formats 5 Layer Manipulations

Layers in Images from Other Formats Layers are a feature of PSD images. When you load files from other image formats, or convert them to Raster from a document format (PDF or PostScript), ADS transforms them into the PSD-like internal Raster format, and stores all of the image information in a single, unnamed layer. Even if the image did not originally contain layers, you must refer to this layer to apply some image commands. For example, If you use the set command or any of the explicit layer-manipulation commands such as addLayer to perform layer manipulations on Raster content, you must save the content to the PSD file format to retain the layer information. ADS flattens layers before saving the image to any other file format.

Layer and Layer Set Support in Versions of Photoshop

● Layers were introduced in Photoshop version 3.0. PSD files created in earlier versions contain only one layer. ● Unicode layer names were introduced in Photoshop 5.0. If the file was created in Photoshop 5.0 or later, and if the layer name contains non-ASCII characters, ADS can only locate that layer when it is referenced with an index number, for example, '/psd/layer[3]'. ● Layer sets were introduced in Photoshop version 6.0. You must use Photoshop version 6.0 or later to create and maintain layer sets in the PSD template files. ADS cannot add layer sets to an existing PSD; it can only set the visibility and opacity attributes of existing layer sets. ● Editable text layers first appeared in Photoshop version 5.0. To create PSD files with text layers for ADS to replace, you must use Photoshop version 5.0 or later. Multi-styled, multicolored text was not supported in Photoshop until version 6.0. You can use ADS to add text layer information to an earlier version file for use with a later version of Photoshop. ● The color overlay layer style was added in Photoshop version 5.5. ADS can create a color overlay effect on any layer in any PSD file. However, to modify an existing color overlay effect, you must use Photoshop version 5.5 or later to create the template file. For more information on feature support in older versions of Adobe applications, see “Legacy File Limitations” on page 118.

98 Dec 19, 2003 Adobe Document Server Developers Guide Manipulating Color Profiles Directly Basic Image Manipulations Working with Color 5

Working with Color

An International Color Consortium (ICC) color profile maps pixel data to standard colors for a particular device, so that when an image is displayed on that device, the colors appear correctly. When you create a color image using a digital device, it can have the profile of that device embedded in it. To display it correctly on a different device, you would convert the color pixel data from the original profile to that of the display device. ADS supports the RGB and CMYK color spaces. (It reads grayscale, and converts it to RGB internally.) The RGB color space is used for screen display, and the CMYK color space is used for print images. You can convert an image from one color space to another; for example, you would convert from RGB to CMYK to prepare a screen image for printing. Within color spaces, you can convert pixel data from one profile to another to display or print it on a different device. For example, you might convert between two CMYK profiles to prepare an image intended for printing in Japan for printing on US presses. You can work with color profiles directly, or indirectly while performing certain other image operations. ADS provides a default built-in sRGB profile. You can provide and refer to a color profile specified in an ICC file (which could have the .icc or .icm extension), or use a profile embedded in an image file.

Manipulating Color Profiles Directly The convertProfile command converts the pixel data in an image from one profile to another, so that the colors will appear correctly when displayed using the new profile’s device. You can convert colors within and between color spaces. You can, for example, convert colors between two RGB profiles, or between an RGB profile and a CMYK profile. In order to convert colors correctly, the command must know what profile the original data used, so it can determine what the corresponding color data is in the new profile. The original color profile (that is, the profile for the device that created the image, such as a digital camera) could be embedded in the image. If an image has an embedded profile, the convertProfile command converts from that profile to the new one. If it does not, the command converts from a default profile. Before converting the color data, you can replace the currently embedded profile or add an embedded profile using the assignProfile command. This command does not change the pixel information in any way; it just makes sure that the profile for the current pixel data is associated with the image. You can only assign a new color profile within the same color space as the existing profile; you cannot assign a CMYK profile to an image whose current profile is RGB, or the reverse. An embedded color profile can significantly increase the size of a saved file. For the JPEG format, you can set an attribute (embedICCProfile) in the optimization settings to choose whether an embedded profile should be saved with the file by the saveOptimized command. For more information on optimization settings, see “Saving Optimized Files” on page 112 and the Adobe Document Server XML Grammars Reference.

Adobe Document Server Developers Guide Dec 19, 2003 99 Basic Image Manipulations Manipulating Color Profiles Directly 5 Working with Color

Rendering Intents Converting images to a different color space often involves an adjustment of the colors to accommodate the gamut of the destination color space. Different translation methods use different rules to determine how the source colors are adjusted. For example, colors that fall inside the destination gamut may remain unchanged, or they may be adjusted to preserve the original range of visual relationships as translated to a smaller destination gamut. These translation methods are known as rendering intents because each technique is tuned for a different intended use of color graphics. The result of choosing a rendering intent depends on the graphical content of documents and on the profiles used to specify color spaces. Some profiles produce identical results for different rendering intents. The available rendering intents are: ● perceptual: Tries to preserve the visual relationship between colors in a way that is perceived as natural to the human eye, although the color values themselves may change. This is the same as the Image intent in Adobe PageMaker and Illustrator. This option is suitable for photographic, continuous tone images. ● saturation: Tries to create vivid color at the expense of accurate color. It scales the source gamut to the destination gamut, but preserves relative saturation instead of hue, so that when scaling to a smaller gamut, hues may shift. This is the same as the Graphics intent in Adobe PageMaker and Illustrator. This option is suitable for business graphics and charts, where the exact relationship between colors is not as important as having bright saturated colors. ● absoluteColorimetric: Tries to maintain color accuracy at the expense of preserving relationships between colors. Leaves colors that fall inside the destination gamut unchanged. When translating to a smaller gamut, two colors that are distinct in the source space may be mapped to the same color in the destination space. This option can be more accurate if the color profile of the image contains correct white point (extreme highlight) information. ● relativeColorimetric (default): The same as absoluteColorimetric, except that it compares the white point of the source color space to that of the destination color space and shifts all colors accordingly. Although the perceptual rendering intent has traditionally been the most common choice for photographic imagery, relativeColorimetric (which is the default method) can be a better choice for preserving color relationships without sacrificing color accuracy. For details of the convertProfile command, see the Adobe Document Server Command Reference.

100 Dec 19, 2003 Adobe Document Server Developers Guide Color Profiles in Other Operations Basic Image Manipulations Working with Color 5

EXAMPLE 5.10 Converting image data to a color profile This sample loads a PSD image, assigns the system-default profile, sRGB, to it, then converts the colors from the newly embedded profile to the USWebCoatedSWOP CMYK profile. It uses the perceptual rendering intent, which tries to preserve the relationships between colors.

Color Profiles in Other Operations Color conversion can take place when you are creating new Raster content by converting it from another format, or when you are importing new image data into existing Raster content. Color Conversion During Format Conversion Although the document formats support multiple color spaces, the Raster format supports only a single color space for an image. When you convert content from one of the document formats (PDF or PostScript) to the Raster image format, ADS rasterizes the document—that is, it displays the document (including any embedded images or vector elements) as if to a high- resolution screen, and captures the resulting image information. If there are multiple color spaces in document images, they are converted to a destination color space using a specified profile. The conversion commands convertPDFTORaster and convertPSToRaster have optional attributes that allow you to specify: ● The color space or profile of the new Raster content. If you specify a profile, the command converts colors to the profile’s color space, using that profile. If you specify the RGB or CMYK color space, it converts to the uncalibrated color space. ● The color translation method for colors that outside the gamut of the color profile, or rendering intent. These are the same as those defined for the convertProfile command. For details of these conversion commands, see the Adobe Document Server Command Reference. Color Conversion During Pixel Replacement When you use the replacePixels command to modify image data, you can provide the optional colorConversionRule attribute to specify how to convert the imported image to a color profile. The value of this attribute can be: ● alwaysConvert (the default): Converts all source pixels to the color profile of the target layer’s image, using the relativeColorimetric rendering intent. ● limitConversion: Ignores the color profiles in cases where the color space of the source and target are the same. For example, if the source pixels and the target layer’s image are

Adobe Document Server Developers Guide Dec 19, 2003 101 Basic Image Manipulations Color Space Support in ADS 5 Working with Color

both in the RGB color space, the command copies them without color conversion. However, if the source is in one color space, and the target in the other, the command uses the color profiles for conversion. For more control over the color conversion process, you can use the limitConversion rule with replacePixels, then use convertProfile to explicitly convert the colors in the resulting image. For details of the replacePixels command, see the Adobe Document Server Command Reference.

Color Space Support in ADS The following table shows how ADS reads and converts color spaces when image files are loaded from different formats.

TABLE 5.1 Color space support for image formats

Format Supported color spaces PSD 8-bit RGB 16-bit RGB (converted to 8-bit on load) 8-bit CMYK 16-bit CMYK (converted to 8-bit on load) 8-bit Grayscale (converted to RGB on load) 16-bit Grayscale (converted to 8-bit RGB on load) TIFF 8-bit RGB 16-bit RGB (converted to 8-bit on load) 8-bit CMYK 16-bit CMYK (converted to 8-bit on load) 8-bit Grayscale (converted to RGB on load) 16-bit Grayscale (converted to 8-bit RGB on load) ADS does not support alpha channels for TIFF. GIF 8-bit RGB 16-bit RGB (converted to 8-bit on load) JPEG 8-bit RGB 16-bit RGB (converted to 8-bit on load) 8-bit CMYK (converted to RGB on load) Grayscale (converted to RGB on load) PNG 8-bit RGB 16-bit RGB (converted to 8-bit on load) PDF, PostScript, EPS When converting to Raster, ADS preserves RGB and CMYK, and converts Grayscale to RGB. See “Color Conversion During Format Conversion” on page 101.

102 Dec 19, 2003 Adobe Document Server Developers Guide Changing Image Orientation Basic Image Manipulations Modifying Image Data 5

TABLE 5.1 Color space support for image formats (Continued)

Format Supported color spaces SVG referenced When converting SVG to PDF, ADS does not perform any color images transformation on referenced JPEG images, but embeds them byte-for-byte in the PDF content. Other referenced image formats are converted to Raster (as on load) before being embedded in the PDF.

Modifying Image Data

ADS provides commands for performing simple image manipulations such as rotation, and allows you to perform more comprehensive modifications by completely replacing a pixel or text layer.

Changing Image Orientation The ADS flip and rotate commands are equivalent to their Photoshop and ImageReady counterparts. ● The rotate command rotates an image by any number of degrees or radians, clockwise or counterclockwise. ● The flip command flips an image upside-down or reverses it from left to right. These commands affect an entire image canvas. You cannot rotate or flip individual layers or parts of layers.

EXAMPLE 5.11 Rotating an image This example saves three versions of the original image, rotated by 90 degrees, 45 degrees, and 60 degrees clockwise. Notice that when the image is rotated by anything other than a multiple of 90 degrees, the command must expand the canvas. When it does this, added pixels are opaque white, or transparent if there is no background layer.

Adobe Document Server Developers Guide Dec 19, 2003 103 Basic Image Manipulations Replacing All or Part of an Image 5 Modifying Image Data

The following figure shows the image rotation results:

Replacing All or Part of an Image You can import new image data into a pixel layer of Raster content using the replacePixels command. You might use this command, for example, to insert a product shot into a complicated template that contains drop shadows, overlaid text, and so on. The new pixel data can come from any supported image format (PSD, TIFF, GIF, JPEG, PNG) or from SVG content. If you import an SVG image into Raster content, the SVG content is converted to the Raster format before its pixels are inserted into the target layer in the Raster content. When the command writes the source pixels into the target layer or image, it places them, by default, such that the new image is centered in the target. You can change the position by specifying either or both of the valign and halign attributes such that the new image is aligned with the top, bottom, left, or right of the target layer or image. By default, the command maintains the aspect ratio when it resizes the image (constrainProportions="true"), but you can choose to allow resizing that changes the aspect ratio. When the command copies the source image, you can specify a scaling policy that controls whether the new image data is allowed to shrink or expand to fit the new canvas area. For details of the available policies, see “Scaling Policies” on page 92. An additional policy, doNotScale, is available for the replacePixels command. This prevents the command from either enlarging or shrinking the source image when copying it to the target layer. If the source image is too large for the target, the image is truncated. Finally, you can specify a color conversion rule for when to convert the pixel information in the source image to the color profile of the target image. By default, the command converts all source pixels to the color profile of the target layer’s image, using relativeColorimetric conversion (see “Working with Color” on page 99). You can choose to limit conversion (colorConversionRule="limitConversion") such that the command ignores the color profiles in cases where the color space of the source and target are the same. For example, if the source pixels and the target layer’s image are both in the RGB color space, the command copies them without color conversion. However, if the source is in CMYK, and the target in RGB, the command uses the color profiles for conversion. For more information, see “Color Conversion During Pixel Replacement” on page 101.

104 Dec 19, 2003 Adobe Document Server Developers Guide Replacing All or Part of an Image Basic Image Manipulations Modifying Image Data 5

EXAMPLE 5.12 Replacing pixels to add a product shot to an image This example loads and stores a PSD file containing an image of a guitar (a product shot), and another containing a product image template. It uses the replacePixels command to replace the layer named Product in the product_image file with the guitar image, allowing the command to scale the image freely to the target layer size while maintaining the aspect ratio.

EXAMPLE 5.13 Duplicating one pixel layer out of several layers This example loads a PSD file and hides all layers except one. In the output content named layerToCopy, only the bottommost layer is visible. It adds a new layer immediately above the visible layer, and uses the replacePixels command to copy the image from the one visible layer in the saved content to the new layer.

EXAMPLE 5.14 Applying a layer effect by replacing pixels This example applies the drop-shadow layer effect to an image by copying the image pixels into a template layer that has that effect applied. The example loads an image of a baseball, and retrieves the image information, so that it can use reference(adobe-content) to access the height and width. It then loads a small template with appropriate drop-shadow parameters, and uses the stored image information to enlarge the template to be the same size as the baseball image. It further enlarges the template by 30 pixels to make sure there is room for the drop shadow.

Adobe Document Server Developers Guide Dec 19, 2003 105 Basic Image Manipulations Replacing Text in an Image 5 Modifying Image Data

The replacePixels command replaces the pixels in the newly enlarged template layer with the baseball image pixels, and the trim command trims off any excess pixels from the edges of the canvas. Finally, the example saves the image with the drop shadow to a new PSD file. Preparing Templates in Photoshop for Pixel Replacement When ADS replaces pixels in the layer, it scales the replacement image, by default, to fit within the rectangular area described by the bounds of any non-transparent pixels that already exist on the targeted layer. If the targeted layer has no existing pixels, the replacement image is scaled to the canvas size of the image. To limit the scale size of the replacement image, use Photoshop to draw an initial rectangle or other shape in a layer intended for replacement. Be sure to switch the default of the shape tool from vector to pixel. The replacePixels command reports an error if the target layer is a vector layer rather than a pixel layer.

Replacing Text in an Image You can replace or modify text in an image in several ways: ● Use the replaceText command to replace specific text in a specific PSD text layer. ● Use the ADS variable replacement mechanism: – With a text variable you have defined and bound in Illustrator or ImageReady. – With the ADS-defined variable defaultTextVariable to replace the topmost text layer in any PSD image. For more information and examples, see Chapter 7, “Replacing Variables in SVG and PSD Files.” ● Use the set command to replace or modify the textFlow element in Raster content, or the flowDef element in SVG content. See “Setting Text Characteristics” on page 127.

106 Dec 19, 2003 Adobe Document Server Developers Guide Changing Colors in an Image Basic Image Manipulations Modifying Image Data 5

For more information on the text representation and examples of text replacement methods, see Chapter 6, “Changing Text in Images,” and t h e Adobe Document Server XML Grammars Reference. For text replacements, make sure the required fonts are available to the ADS server. If they are not, ADS uses a default font. For further information about fonts, see the ADS Installation and Configuration Guide.

Changing Colors in an Image You can use the set command to change color attributes of text, such as the fill or stroke color (see Chapter 6, “Changing Text in Images”). If you have defined a color-overlay style for a text or pixel layer in Photoshop, you can replace it using the set command, with the target /psd/layer[n]/style/colorOverlay. Setting a color overlay is useful for dynamically changing a color feature such as a car body or piece of clothing in a catalog. In the colorOverlay element, the color attribute specifies a color as a hexadecimal color value from #000000 to #FFFFFF. The default color is #FF0000, or red. In addition to the new color, attributes control the opacity of the color, which is in the range 0.0 to 1.0 (1.0, the default, means completely opaque), and the blendMode. The blend mode controls how the new color is blended with the original color. The default is to completely replace the old color (normal), but you can choose from many blend modes that allow you to achieve special effects, such as hardlight or softlight, darken or lighten, and so on. For a complete description of the blend modes, see the Adobe Document Server XML Grammars Reference.

EXAMPLE 5.15 Replacing a color overlay in an image layer This example replaces the logo color in an image of a stoplight, which has been specified in a color overlay. It shows the "Caution" layer, hides the "Go" and "Stop" layers, and saves the result to a new PSD file.

Adobe Document Server Developers Guide Dec 19, 2003 107 Basic Image Manipulations Controlling Visual Quality 5 Modifying Image Data

Controlling Visual Quality You can use commands to adjust the contrast or level of an image in RGB Raster content. These commands have the same effect on the image as the similar commands you can apply interactively through the Photoshop and ImageReady menus. The autoContrast and autoLevels commands both use a similar technique to adjust either the contrast or the level of an image. ● Contrast adjustment can improve the appearance of many photographic or continuous-tone images. It does not improve flat-color images. It improves image appearance by making the highlights appear lighter, and the shadows appear darker. ● Level adjustment gives good results for an image with an average distribution of pixel values or for an image with an overall color cast. These commands work on one layer at a time. If the image is not in a single layer, and if you want to adjust multiple layers in a single pass, you must first flatten the image using the flatten command. For more information on these concepts and operations, see the Photoshop documentation.

EXAMPLE 5.16 Automatically adjusting contrast in an image This sample loads an image, flattens the layers so that the entire image can be adjusted, and uses the autoContrast command to automatically adjust the contrast. The sample saves an optimized file; if there are no optimization settings in the original PSD file, the result is a 256-color GIF file.

108 Dec 19, 2003 Adobe Document Server Developers Guide Retrieving Image Information Basic Image Manipulations Accessing Raster Content 5

Accessing Raster Content

The internal Raster format, like the PSD format, is binary. However, ADS defines an XML content, similar to a subset of SVG, that is used to show certain image information in XML, and also provides access to certain features through the set command.

Retrieving Image Information You can use the imageInfo command to retrieve information from Raster content. The information is shown in XML that reflects the Raster content model. The imageInfo result shows default values for any elements that have not been explicitly set to something other than the default (unlike SVG, for example, where elements that have no explicit values are not visible in the file). The imageInfo result is stored as XML content. You can access elements in that XML content using the reference(adobe-content) syntax, as shown in “Applying a layer effect by replacing pixels” on page 105. The command returns the same kind of image information for all Raster content, regardless of the file format from which it was loaded or converted. However, some of the content model elements represent PSD features (layers and layer sets) that are only minimally present in files loaded from other formats. For more information, see “Layers in Images from Other Formats” on page 98. The following sample of Raster content information, as retrieved with the imageInfo command, shows some of the hierarchy of elements and illustrates attribute settings:

Adobe Document Server Developers Guide Dec 19, 2003 109 Basic Image Manipulations Setting Elements of an Image 5 Accessing Raster Content

Setting Elements of an Image You can use the set command to replace or modify certain elements and attributes in Raster content, using an abbreviated XPath syntax to reference the elements and attributes that you want to change. Not all features that you can see using the imageInfo command can be set using the set command. You can set or replace the following properties:

Target for set command Description

/psd/@copyright A copyright message for the content.

/psd/layerSet[n]/@visibility Layer set properties. /psd/layerSet[n]/@opacity

/psd/layerSet[n]/layer[n]/@visibility Layer color and appearance properties, /psd/layerSet[n]/layer[n]/@opacity where layer is in a layer set. /psd/layerSet[n]/layer[n]/style/colorOverlay

/psd/layer[n]/@visibility Layer color and appearance properties, /psd/layer[n]/@opacity where layer is not in a layer set. /psd/layer[n]/style/colorOverlay

/psd[/layerSet[n]]/layer[n]/textFlow Text layer properties. .../flow/p/span (contains text) There are many text attributes you can set .../region/path within a span. .../fonts/font

/psd/optimizationSettings Preferred optimization format and .../GIFFormat properties. .../PNG8Format There are many attributes you can set for .../PNG24Format each format, with different attributes .../WBMPFormat applicable to different formats. .../JPEGFormat

/psd/fileInfo IPTC metadata properties. .../property

110 Dec 19, 2003 Adobe Document Server Developers Guide Setting Elements of an Image Basic Image Manipulations Accessing Raster Content 5

The following figure shows the Raster target hierarchy.

/psd @copyright

/fileInfo /layerSet /optimizationSettings @visibility @opacity

/GIFFormat /PNG8Format /PNG24Format /WBMPFormat /JPEGFormat (many attributes) /layer @visibility @opacity /style /textFlow

/colorOverlay /flow /region /fonts @enabled @color /p /path /font @opacity @blendMode /span (many attributes)

Typically, you will use the set command to adjust features such as the opacity and visibility of layers and layer sets (see “Layer Manipulations” on page 95), and to set the optimization parameters that control how the saveOptimized command saves the content (see “Saving Content” on page 59, “Saving Optimized Files” on page 112, and the Adobe Document Server XML Grammars Reference). You can also use the set command to replace text characteristics and text color overlays. See “Setting Text Characteristics” on page 127.

EXAMPLE 5.17 Using the set command to change copyright information for an image This example uses the set command to set the copyright message for a PSD file, which is referenced as an attribute of the root psd element in the Raster content model.

EXAMPLE 5.18 Copying a value from one Raster content holder to another This example sets the third layer of the current content to the same opacity as the yellow layer of the image in the content named guitar.

Adobe Document Server Developers Guide Dec 19, 2003 111 Basic Image Manipulations Tuning Optimization Settings Outside ADS 5 Treating PostScript and PDF Content as Images

For More information ● The Raster content model and XPath support are described in detail in the Adobe Document Server XML Grammars Reference. ● The set and imageInfo commands are described in detail in the Adobe Document Server Command Reference.

Treating PostScript and PDF Content as Images

You may want to treat a document as an image, because, for example, the document contains only an image, or to convert it for display by an application that does not handle PostScript or PDF. In ADS, you can convert PostScript content to Raster content using the convertPSToRaster command, and PDF content to Raster content using the convertPDFToRaster command. You can convert Photoshop EPS to Raster, but Photoshop-specific information stored in embedded image resources is not retained. Once the information is in Raster content, you can set the optimization parameters, for example, and save it to an optimized format. If you want to store an image as a document, you can convert Raster content to PostScript or to PDF content, using the convertRasterToEPS and convertRasterToPDF commands. The PostScript generated by these commands is Photoshop-compatible EPS. For information on how ADS translates colors in a document when converting them to an image format, see “Color Conversion During Format Conversion” on page 101.

Saving Optimized Files

You can use the saveOptimized command to save Raster or SVG content to one of the optimized files formats GIF, JPEG, PNG, or WBMP. The format, along with other optimization parameters, is controlled by the content’s optimization settings. If you used Save for Web in Photoshop or Illustrator, then loaded the file into ADS, ADS maintains the optimization settings that you specified. You can also create or modify optimization settings in ADS by using the set command to set the optimizationSettings element in Raster or SVG content. For detailed information on optimization settings in Raster content and Save-for-Web settings in SVG content, see the Adobe Document Server XML Grammars Reference.

Tuning Optimization Settings Outside ADS The Save for Web feature of Adobe Photoshop and Adobe Illustrator allows you to fine tune the Web compression settings for a particular image when you create it, and to save those settings with the PSD or SVG file. When you create a variation of the image, by changing the size or text, for example, you can automatically reuse the original compression settings. Having the original artist optimize the Web compression settings for each image is especially

112 Dec 19, 2003 Adobe Document Server Developers Guide Tuning Optimization Settings in ADS Basic Image Manipulations Saving Optimized Files 5

important if you will use ADS to create the variations automatically. You can maintain the original artistic intent over hundreds of reuses. Photoshop 5.5 (July 1999) and Illustrator 9.0 (April 2000) first implemented the Adobe "Save for Web" feature, so some of your legacy files may already have taken advantage of "Save for Web". Your current workflow should include the Save for Web step so that you can realize future benefits. To tune optimization settings for a PSD file in Photoshop, or for an SVG file in Illustrator, use the following general procedure: 1. Create or load the image. 2. From the File menu, choose Save for Web. 3. Decide if the image should be a GIF, JPEG, or PNG. 4. Determine the best compression settings for this particular image. 5. Click OK. This saves a Web-ready copy of the image based on your settings. If you loaded this file into ADS, it would not retain the optimization settings. 6. Save the image as a PSD file (from Photoshop) or an SVG file (from Illustrator). In Illustrator, you must check Include Slicing Data in the Advanced section of the Save as SVG dialog box in order to save the optimization settings with the file. The resulting PSD or SVG file has your compression settings embedded in it. Use this file with ADS, not the file created in step 5.

NOTE: Both the .ai and SVG formats can store your compression settings, but ADS can only work with SVG files. You may want to save both .ai and SVG versions of your files. For full details of saving and tuning in these applications, see the Photoshop and Illustrator documentation.

Tuning Optimization Settings in ADS You can use the set command to create or modify optimization settings in Raster or SVG content. You can address a particular optimization attribute to set its value, or replace all or part of the optimizationSettings element.

EXAMPLE 5.19 Setting an optimization attribute This example uses abbreviated XPath syntax to make the existing attribute the direct target of the set command. This example does not change any other attributes that were already set in the original file.

Adobe Document Server Developers Guide Dec 19, 2003 113 Basic Image Manipulations Tuning Optimization Settings in ADS 5 Saving Optimized Files

This example addresses the existing format element directly as the target, and replaces it with a new format element containing a quality attribute value. All other JPEG attributes are allowed to default, regardless of whether they were specified in the original file. Both of these examples would cause errors if the original file did not already have JPEG as the preferred optimized file format.

EXAMPLE 5.20 Changing the preferred optimization format with set This example loads a PSD file, then replaces all existing optimization settings in that file. The set command replaces the entire target element, , with a new element containing the preferred file format of JPEG, with the quality attribute set to 60. All other JPEG attributes are allowed to default. The example then saves the content to a new JPEG file. Choosing an Optimized Format Automatically For RGB Raster content, you can use the optimizeToSize command to automatically tune the settings to produce an optimized image file that is no larger than a particular file size (see “Changing the Image File Size” on page 115). If you choose, this command can also determine whether GIF or JPEG is a better optimization format for an image, and adjust the settings for that format. (This command does not work for CMYK images.)

EXAMPLE 5.21 Choosing an optimization format automatically This example loads a PSD image, determines whether GIF or JPEG optimization should be applied to the image, adjusts the optimization settings to produce a file size of no more than 30K, and saves the content in the optimized format.

114 Dec 19, 2003 Adobe Document Server Developers Guide Balancing Quality and Size in Optimized Image Files Basic Image Manipulations Saving Optimized Files 5

Balancing Quality and Size in Optimized Image Files When you save image content to an optimized file format, certain optimization settings control the quality of the resulting image. In general, you can choose to preserve quality at the expense of a larger file size, or reduce the file size by sacrificing image quality. See also “Changing the Image File Size” on page 115. ● For the GIF file format, set the lossy attribute to a value from 0 to 100. A lower value results in an image of higher quality with a larger file size. ● For both GIF and PNG8 formats, if the image contains a fixed color table, you can set the autoReduce attribute to true to remove infrequently-used colors from the table, resulting in a smaller file. In addition, you can specify a reductionAlgorithm to be used to decrease file size. ● For the JPEG file format, set the quality attribute to a value from 0 to 100. A higher value results in an image of higher quality with a larger file size. In addition, you can set the optimized attribute to true to create an enhanced JPEG with a slightly smaller file size. Adjusting the blurAmount can affect the file size. Embedding a color profile (embedICCProfile) or metadata (embedMetadata) increases file size. For more information on optimization settings, see the Adobe Document Server XML Grammars Reference.

EXAMPLE 5.22 Adjusting the quality of an optimized file This example loads a PSD file, then replaces all existing optimization settings in that file with a new set. The set command replaces the entire target element, , with a new element containing the preferred file format of JPEG, with the quality attribute set to 60. All other JPEG attributes are allowed to default. The example then saves the content to a new JPEG file.

Changing the Image File Size The optimizeToSize command adjusts optimization settings in an RGB image so that when you save it with the saveOptimized command, the file will be no larger than the file size you specify. This ADS command is similar to the Optimize to File Size command in Photoshop. It reduces the file size at the expense of image quality. (This command does not work for CMYK images.)

Adobe Document Server Developers Guide Dec 19, 2003 115 Basic Image Manipulations Saving Metadata with Optimized Files 5 Saving Optimized Files

The command allows you to quickly achieve a desired file size without having to test different optimization settings. It adjusts the optimal number of colors for GIF or PNG8 format or the optimal color quality for JPEG format that will result in a file below the size that you specify. You can choose to let the command determine whether GIF or JPEG is a more optimal format for the image, and then adjust the optimization settings accordingly. The command selects JPEG for any image that appears to be a photograph and does not use transparency. It selects GIF for all other images. If you choose not to select the output format automatically, the command retains the image’s current optimization settings. The command can tune parameters for the JPEG, GIF, and PNG8 formats. The PNG24 or WBMP formats do not have tunable parameters, so if one of those was the original preferred format, the command reports an error. You must use the set command or a tool outside ADS to select another format (PNG or WBMP) for the optimized file, or to adjust other optimization settings individually. For more information on optimization, see “Saving Content” on page 59, “Saving Optimized Files” on page 112, and the chapter “Accessing Raster Content” in the Adobe Document Server XML Grammars Reference.

EXAMPLE 5.23 Creating a smaller image file This example loads a PSD image, determines whether GIF or JPEG optimization should be applied to the image, adjusts the optimization settings to produce a file size of no more than 30K, and saves the content in the optimized format.

Saving Metadata with Optimized Files In the saveOptimized command, you can use the optional metadata attribute to specify whether to save metadata with an optimized image file, and what metadata formats to save (XMP, EXIF, and/or IPTC). If you do not supply the attribute, no metadata is saved with the file. You can specify any combination of the supported formats; however, the non-XMP formats apply only to JPEG files. If the file is not being written in JPEG format, those values are ignored. ● You can include XMP format metadata for any output file. ● You can specify any combination of XMP, EXIF, or IPTC metadata to be saved with a JPEG file. Upon save, metadata in all formats is guaranteed to be consistent. For more information on metadata formats, see Chapter 4, “Working with File Metadata.” The JPEG optimization settings also contain an attribute, embedMetadata, that you can use to specify IPTC metadata. If you specify this attribute (using the set command), the IPTC

116 Dec 19, 2003 Adobe Document Server Developers Guide Custom Color Palettes in Optimized Files Basic Image Manipulations Saving Optimized Files 5

metadata is included in the saved JPEG file, regardless of the metadata value in the saveOptimized command. For more information on this and other optimization settings, see the chapter “Accessing Raster Content” in the Adobe Document Server XML Grammars Reference.

Custom Color Palettes in Optimized Files You can use custom color palettes with GIF and PNG8 images. You cannot programmatically create a custom color palette within ADS, but ADS loads and preserves custom color palettes previously defined in Photoshop or ImageReady. Each time you use the saveOptimized command to save an image as a GIF or PNG8 in ADS, the Selective, Adaptive, or Perceptual color reduction algorithm creates a new color palette by analyzing the colors present in the image. If you plan to use the same colors for all images (for example, if you are just changing text), you can switch the image to a custom palette in ImageReady. To use a custom palette, use the Selective, Adaptive, or Perceptual algorithm in Save for Web in Photoshop, or the Optimize palette in ImageReady. Select Custom as the Color Reduction Algorithm setting. This “freezes” the current color palette, and allows ADS to skip the color analysis and palette creation steps each time it saves the file, which saves processing time. When you use a custom color palette, only colors contained in the palette are used in the optimized image file. Therefore, if you add pixel data to the file in ADS (for example, if you add a logo to a graphic) you may get unexpected color shifts in the new pixel data.

Saving Dynamic PSD and Animated GIFs ADS does not allow you to manipulate slices, rollovers, image maps, and animations. ADS ignores slicing, rollovers, and image maps when you save Raster content. ADS maintains the animation frames when you load animated PSD files. If you load animated GIFS into ADS, it transforms the GIF animation frames into PSD animation frames. You can save Raster content containing animation frames to produce an animated GIF or PSD result.

Adobe Document Server Developers Guide Dec 19, 2003 117 Basic Image Manipulations Saving Dynamic PSD and Animated GIFs 5 Legacy File Limitations

Legacy File Limitations

Legacy PSD and SVG files that originate in older versions of Adobe Photoshop, ImageReady, Illustrator, and GoLive® may not support features that ADS uses, if those features were not available in the application that created the file. The following tables summarize when key features were introduced in the various applications.

TABLE 5.2 Photoshop feature introductions

Feature 3.0 5.0 5.5 6.0 Copyright Notice X Layer Names X Unicode Layer Names X Editable Text Layers X Layer Effect Color Overlay X Optimization Settings X Layer Sets X

.

TABLE 5.3 ImageReady feature introductions

Feature 1.0 2.0 3.0 7.0 Optimization Settings X Replacement Variables X

.

TABLE 5.4 Illustrator feature introductions

Feature 9.0 10.0 Graphing X .ai format changes from EPS to PDFa X SVG file format X Flow Text X Replacement Variables X

a. ADS can load .ai files from version 7.0 and up.

.

TABLE 5.5 GoLive feature introductions

Feature 5.0 6.0 Replacement Variables X Dynamic Link Palette X

118 Dec 19, 2003 Adobe Document Server Developers Guide 6 Changing Text in Images

This chapter describes how to set, replace, or modify text in Raster or SVG content. You can modify the text itself, using several different techniques, or use the set command to modify text display characteristics, such as the font and color. This chapter contains the following sections:

Changing Text in Images starting on page 119 Changing Text Attributes in Text Flows starting on page 123

Changing Text in Images

Text is stored in text layers in PSD files, and in text flows (the flowDef element) in SVG files. ADS provides several ways to replace or modify text in a PSD or SVG file, automatically or explicitly:

Use the replaceText command to replace See “Replacing Text in Raster Content” on specific text in a specific text layer of a PSD file. page 120 and the Adobe Document Server Command Reference.

Use automatic variable replacement with a See “Replacing Text Variables in PSD Files” on text-type variable that you define in ImageReady page 120 and “Replacing Text Variables in or Illustrator to replace all text in an SVG text SVG Files” on page 122. object or a PSD text layer.

Use automatic variable replacement with the See “Replacing Text Variables in PSD Files” on ADS-defined variable defaultTextVariable to page 120. replace the topmost text layer in any PSD file.

Use the set command to replace or modify the See “Changing Text Attributes in Text Flows” textFlow element in Raster content, or change on page 123. the color of text by modifying the colorOverlay element.

Use the set command to replace or modify the See “Changing Text Attributes in Text Flows” flowDef element in SVG content. on page 123.

For more information on these techniques and formats, see also the Adobe Document Server Command Reference, the chapter “Accessing Raster Content” in the Adobe Document Server XML Grammars Reference, and the SVG specification at the following URL: http://www.w3.org/TR/SVG/paths.html

Adobe Document Server Developers Guide Dec 19, 2003 119 Changing Text in Images Replacing Text in Raster Content 6 Changing Text in Images

For text replacements, make sure the required fonts are available to the ADS server. If they are not, ADS uses a default font. For further information about fonts, see the ADS Installation and Configuration Guide.

Replacing Text in Raster Content In Raster content, replaceable text is always in a text layer. (Bitmapped text in a pixel layer is not replaceable as text, although you can replace the image with another image containing different bitmapped text.) You can use the replaceText command to replace all of the text in a text layer, or to replace a specific string with another string.

EXAMPLE 6.1 Replacing all text in a layer This example replaces all of the text in the layer named Title with the replacement text The National Pastime, and all of the text in the layer named Description with the replacement text 1997 National League Championship Series.

EXAMPLE 6.2 Replacing specific text in a layer This example replaces the text string 69.99 in the layer named Base Price with the text 400, and the text string 50 in the layer named Percentage with the text 40. Replacing Text Variables in PSD Files You can define a text-type variable in ImageReady 7, bind it to a text layer, and use the ADS automatic or explicit variable replacement facility to replace the variable value. Text variables can only be bound to the entire text layer, so you must replace all the text in the layer with this method. You can replace only the text, not any of the text attributes, such as the font or style. For details of how to specify replacement values for variables and how to apply replacement values, see Chapter 7, “Replacing Variables in SVG and PSD Files.”

120 Dec 19, 2003 Adobe Document Server Developers Guide Replacing Text in an SVG Text Flow Changing Text in Images Changing Text in Images 6

For any PSD file with one or more text layers, ADS automatically defines a text-type variable named defaultTextVariable and binds it to the topmost text layer (that is, the one with the highest index number). To replace the text in the topmost text layer automatically or explicitly, specify the new text value for the default variable named defaultTextVariable in the XML replacement data: new text

EXAMPLE 6.3 Replacing the automatic text variable value The following example performs an explicit variable replacement, using XML replacement data that it loads inline in the loadContent command. It replaces the text in the topmost layer of the PSD file imageWithCaption with the string “Clearance!” Clearance!

Replacing Text in an SVG Text Flow You can use the set command to replace the flowDef element or one of its subelements in SVG content. Depending on how you specify the target, you can replace just the text, or the text and its attributes, such as the font or style. See “Changing Text Attributes in Text Flows” on page 123. The following is an example of a text flow in an SVG file:

product name

Adobe Document Server Developers Guide Dec 19, 2003 121 Changing Text in Images Replacing Text in an SVG Text Flow 6 Changing Text in Images

0.0

EXAMPLE 6.4 Replacing text in an SVG text flow This example uses the set command to replace the text in the sample SVG text flow.

EXAMPLE 6.5 Replacing an entire text flow in SVG content This example uses the set command to replace the whole flow, both text and attributes, for the same SVG sample.

My Product

Replacing Text Variables in SVG Files You can define a text-type variable in Illustrator 10, bind it to a text flow, and use the ADS automatic or explicit variable replacement facility to replace the variable value. The replacement value can contain attribute values that affect format and style, as well as the text itself. A text variable can be replaced at four different levels of the text flow hierarchy: ● If the replacement data value is a flow element, ADS replaces the flow element in the source content with the new flow element. ● If the replacement data value is text only, ADS replaces the text of the first span child of the first p element (or the text of the first p element, if it has no span) of the flow element in the source content with the new text. It removes all other span and p elements.

122 Dec 19, 2003 Adobe Document Server Developers Guide The Structure of a Text Flow Changing Text in Images Changing Text Attributes in Text Flows 6

● If the replacement data value is a p element, ADS replaces all the child elements of the flow element with the new p element. ● If the replacement data value is a span element, ADS replaces all the child elements of the first p element of the flow element with the new span element. For details of how to specify replacement values for text variables and how to apply replacement values, see Chapter 7, “Replacing Variables in SVG and PSD Files.”

Changing Text Attributes in Text Flows

This section explains the XML structure of text flows in PSD and SVG files. Understanding this structure allows you to change the text in text flows in SVG and Raster content using the set command. By setting elements and attributes of a text flow, you can affect the style and appearance of text, as well as the actual text. When you replace simple text bound to a text variable or use the replaceText command, you change only the text itself; the style is not affected.

The Structure of a Text Flow A text flow is represented by a hierarchy of elements. A text flow hierarchy is defined by the SVG specification. For complete information, see the SVG specification at http://www.w3.org/TR/SVG/paths.html. ADS defines a similar hierarchy for Raster content, extended for PSD text information. Figure 6.1 shows the hierarchical structure of the elements in a text flow, and specifies which elements apply to Raster and to SVG content.

FIGURE 6.1 XML structure of text flows in Raster and SVG content

Raster structure SVG structure

1 or more 1 or more order is significant order is significant

label label label label w w

w

w h h h h

1 or more 1 or more order is significant order is significant

label label label label w w w w h h h h

Adobe Document Server Developers Guide Dec 19, 2003 123 Changing Text in Images The Structure of a Text Flow 6 Changing Text Attributes in Text Flows

As you can see from this figure, the element hierarchies for PSD and SVG text flows are very similar; they differ only in the name of the top element and the absence of the font elements in the SVG case. The fonts element can optionally provide a more reliable way of locating fonts for PSD files. The actual text content of a text flow is specified in the flow element or its subelements. The other elements provide attributes, but no content. The region and path elements define a position or shape for the text. ADS supports two types of text in a text flow, area text and point text: ● Area text — The area for area text is defined by a rectangle, drawn according to instructions in the path element. Area text wraps within the defined rectangle. You create area text in Photoshop or Illustrator by clicking and dragging the cursor with the Text tool to create a rectangular area in a document and then typing text in that rectangle. Within a text area, the p elements correspond to paragraphs. The number of p elements are determined by how many Return characters the text contains. When entering area text, pressing the Return key creates a new paragraph. If you press the Return key twice, you have three paragraphs, each of which is represented by its own p element. ● Point text — The area for point text is defined by a single origin point expressed in the path element. Point text contains a single line of text that does not wrap. You create point text in Photoshop or Illustrator by clicking in a document with the Text tool and typing the text. The text flow for point text has only one p element. Each PSD text layer in a PSD file has one and only one text flow. If an image contains six text layers, there are six text flows in the image. SVG images do not have the notion of layers, but an SVG image can contain multiple text flows. Table 6.1 gives a brief summary of each of the elements in Figure 6.1. For complete details of these elements and their attributes, see the chapter “Accessing Raster Content” in the Adobe Document Server XML Grammars Reference.

124 Dec 19, 2003 Adobe Document Server Developers Guide The Structure of a Text Flow Changing Text in Images Changing Text Attributes in Text Flows 6

TABLE 6.1 Summary of elements and attributes in PSD and SVG text flows Element & description Attributes PSD SVG (PSD) or (SVG) None Required The root of the text flow element hierarchy. writing-mode ✔✔ Required textMatrix ✔ Contains one subelement that describes the position of point text, or the rectangular region of area text. Its attribute determines the direction of the text in the region (left-to-right or top-to-bottom), and region transformations (rotation, scaling, and coordinate translation). d ✔✔ Required Describes the origin point of point text or outline of area text. None ✔ Optional A collection of all fonts used in the flow. adobe-font-name ✔ Optional adobe-font-script ✔ Identifies a single font that may be used in the text flow. adobe-font-synthetic ✔ adobe-font-technology ✔ adobe-fractional-widths ✔✔ Required All attributes for p and span elements can also be Contains subelements that contain the specified on this element. Values specified in the p and actual text for the text flow. Attributes span elements override those set at this level. set at this level affect all text in the flow. Can contain text.

Adobe Document Server Developers Guide Dec 19, 2003 125 Changing Text in Images The Structure of a Text Flow 6 Changing Text Attributes in Text Flows

TABLE 6.1 Summary of elements and attributes in PSD and SVG text flows (Continued) Element & description Attributes PSD SVG

adobe-auto-leading-percent ✔✔ Required adobe-burasagari ✔✔ Defines a paragraph. Its attributes define the paragraph style. adobe-consecutive-hyphens ✔✔ Contains one or more span adobe-every-line-composer ✔✔ subelements that contain the actual adobe-hanging-roman ✔✔ text. Each paragraph contains a style-span for each style of text in the adobe-hyphenate-capitalized ✔✔ paragraph. adobe-hyphenate-word-size ✔✔ Can contain text. adobe-hyphenation-zone ✔✔ adobe-justification-glyph-scaling-desired ✔ adobe-justification-glyph-scaling-max ✔ adobe-justification-glyph-scaling-min ✔ adobe-justification-letter-spacing-desired ✔✔ adobe-justification-letter-spacing-max ✔✔ adobe-justification-letter-spacing-min ✔✔ adobe-justification-word-spacing-desired ✔✔ adobe-justification-word-spacing-max ✔✔ adobe-justification-word-spacing-min ✔✔ adobe-kinsoku-set ✔

adobe-leading-type ✔✔ (cont’d) adobe-mojikumi-set ✔ adobe-preferred-kinsoku-order ✔ end-indent ✔✔ hyphenate ✔✔ hyphenation-push-character-count ✔✔ hyphenation-remain-character-count ✔✔ space-after ✔✔ space-before ✔✔ start-indent ✔✔ text-align ✔✔ text-align-last ✔✔ text-indent ✔✔ All span attributes can be specified on this element. Values set in the span element override those set here.

126 Dec 19, 2003 Adobe Document Server Developers Guide Setting Text Characteristics Changing Text in Images Changing Text Attributes in Text Flows 6

TABLE 6.1 Summary of elements and attributes in PSD and SVG text flows (Continued) Element & description Attributes PSD SVG adobe-baseline-direction ✔ Required adobe-faux-bold ✔✔ The attributes define a character style that applies to the contained text. adobe-faux-italic ✔✔ Can contain text. adobe-font-baseline-option ✔✔ adobe-horizontal-scale ✔✔ adobe-ligatures ✔ adobe-no-break ✔✔ adobe-old-style-figures ✔ adobe-tsume ✔ adobe-vertical-scale ✔✔ adobe-y-underline ✔ baseline-shift ✔✔ fill ✔✔ font-family ✔✔ font-size ✔✔ font-variant ✔ kerning ✔✔ letter-spacing ✔✔ line-height ✔✔ (cont’d) stroke ✔ text-decoration ✔✔ text-transform ✔

Setting Text Characteristics You can use the set command to address individual attributes at any level of the text flow hierarchy, or to replace an entire element in the hierarchy, including both the attributes and text. For details of how to use the set command, see the Adobe Document Server Command Reference.

Adobe Document Server Developers Guide Dec 19, 2003 127 Changing Text in Images Setting Text Characteristics 6 Changing Text Attributes in Text Flows

EXAMPLE 6.6 Changing a font size This example loads a PSD file that contains a text layer named caption. It changes the font size in the first span of the text flow to 36 points.

EXAMPLE 6.7 Changing the fill color for text This example sets the fill attribute to #FF0000 (red) at the level of the flow element. Although fill is actually an attribute of span, when you set it at the higher level, the value applies to any span subelements that do not define a different value for it.

EXAMPLE 6.8 Changing the overlay color in a text layer This example loads a PSD file that contains a text layer named caption, for which the creator defined a color overlay style in Photoshop. It changes the color overlay for the entire text layer to yellow. For more information on color overlays, see “Changing Colors in an Image” on page 107.

128 Dec 19, 2003 Adobe Document Server Developers Guide Setting Text Characteristics Changing Text in Images Changing Text Attributes in Text Flows 6

EXAMPLE 6.9 Replacing an entire text flow in Raster content This example loads a source PSD file with a text layer named caption, and replaces the entire textFlow element in that layer. The new text flow provides the text “Now 30% off!,” changing the font size so that “30%” is bigger than the rest of the text.

Now

30%

off!

Adobe Document Server Developers Guide Dec 19, 2003 129 Changing Text in Images Setting Text Characteristics 6 Changing Text Attributes in Text Flows

EXAMPLE 6.10 Replacing text flow attributes in SVG content This example uses the set command to replace both an entire flow and specific text flow elements for SVG content.

Mr. Smart

100 Main Street

City, ST 90000

Notice that the target XPath includes the identifier. You could use an absolute path to the element: target="/svg/g/switch[2]/foreignObject/flowDef/flow/p[2]/span[1]/text()"

130 Dec 19, 2003 Adobe Document Server Developers Guide Replacing Variables in SVG and PSD 7 Files

This chapter describes the variable replacement facility in ADS. It contains the following sections:

Overview of Variable Binding and Replacement starting on page 131 Automatic Variable Replacement starting on page 133 Replacing Variables Explicitly starting on page 134 Specifying Replacement Data starting on page 136

Overview of Variable Binding and Replacement

Variables provide a convenient and portable way to replace elements of a file. You can define and replace variables in SVG and PSD source files. When you define variable bindings, you create a definition in the file that associates a variable name with a particular element in the file. You can bind a variable to a major element such as an entire text flow in a PSD file or the contents of a graph in an SVG file, or to a very specific feature such as the fill attribute of a circle in an image. To replace the element, all you need to know is the name of the variable. Variables give graphic designers the flexibility to make modifications to images without invalidating already existing code in ADS command sets. A designer can change the structure of a template file, and, as long as the variable names remain constant, there is no need to modify or update the associated ADS command set that uses that template. ADS provides a very flexible mechanism for automatic variable replacement in various circumstances, and also provides a command that you can use to explicitly replace variables at any point in the execution of a command set. To use the variable replacement facility in ADS, you must first create template SVG and PSD files. Use Adobe Illustrator 10 and Adobe ImageReady 7 (the Web-authoring application that ships with Photoshop 7) to define named variables and bind them to those portions of the file that you want to replace or fill with run-time data. You cannot create new variables or change their bindings with ADS. ● To create an SVG file that contains variable bindings, use the Variables palette in Adobe Illustrator. When you save the SVG file in Illustrator 10, you must export the variable bindings information by checking "Include Extended Syntax for Variable Data" in the "Save as SVG" dialog. Illustrator 10 can create SVG file variables of type visibility, graph, text, and image replacement. ADS can recognize and replace all of these variable types.

Adobe Document Server Developers Guide Dec 19, 2003 131 Replacing Variables in SVG and PSD Files 7 Overview of Variable Binding and Replacement

● To create a PSD file that contains variable bindings using the Variables palette in ImageReady 7. ImageReady 7 can create PSD file variables of type visibility, text replacement, and image replacement.

NOTE: In Adobe GoLive version 6.0, you can bind only text and visibility variable types. ADS can replace an element bound to a variable with new data that you supply in XML format. ADS can replace variables automatically when you load a file, or you can use the applyVariables command to replace variables explicitly in the course of executing a command set. To replace variables in a file, you load two separate source files into ADS: the replacement data, and the SVG or PSD file containing the variables. You can load either or both of the files as part of the ADS request (from the command line or API), a command file can load the files using the loadContent command, or you can combine these methods. You can also load the replacement data inline in the loadContent command. You can use the same replacement data for several source files, or replace variables in the same source file with several sets of data. The automatic variable replacement behavior depends on how the files are loaded and how the replacement data is named. You can do any of the following: ● Replace variables completely automatically, passing both source files in the request, without specifying a command set. ● Replace variables automatically, passing in both source files, then continue processing with a command set. ● Provide only the replacement data file with the request. ADS uses that data to replace variables automatically as commands load different source files containing variables. ● Load the replacement data using the loadContent command, giving it the special content name data. ADS uses that data to replace variables automatically as commands load different source files containing variables. ● Load and name both the data and variable source files using the loadContent command, and replace variables explicitly using the applyVariables command.

132 Dec 19, 2003 Adobe Document Server Developers Guide Replacing Variables in SVG and PSD Files Automatic Variable Replacement 7

Automatic Variable Replacement

You can cause ADS to replace variables in an SVG or PSD file automatically (without an explicit command) in a number of ways. Automatic replacement depends on how and when you load the SVG or PSD source file containing variables and the XML file containing the replacement data. For ADS to perform automatic variable replacement, the replacement data must be loaded and named with the reserved name data, before the file containing the variables. You can load the XML variable replacement data in any of these ways: ● Use an explicit loadContent operation to load the file or inline data and name it data using the out attribute. ● On the command line, specify the data file in the -data option to the ADS command. ● When constructing a request with one of the ADS APIs, use the addVariable method to add each variable name and replacement value to the request. ADS collects all of the values into an XML content holder called “data” before executing the command set. You can pass in or load the data and source files in any combination. ADS automatically replaces variables in an SVG or PSD file whenever there is an XML content holder named data available. This happens in any of the following circumstances: ● You pass in both an SVG or PSD source file (using the -source option) and XML replacement data (using the -data option) on the command line. If you also specify a command set, ADS performs the variable replacement before executing any of the commands. If you do not specify a command set, ADS performs the replacement and saves the updated file with the name Untitled. ● You pass in XML replacement data on the command line or with the request, then in the command set use the loadContent command to load an SVG or PSD file. The variable replacement is performed immediately after the file containing the variables is loaded. The variable data is accessible from ADS as XML content named data, and will be used to replace variables for any subsequently loaded SVG or PSD files as well. ● In the command set, you load an XML data file (or inline data) containing the replacement values using the loadContent command, name it data using the out attribute, then use the loadContent command to load an SVG or PSD file. The variable replacement is performed immediately after the file containing the variables is loaded. The XML content named data will be used to replace variables for any subsequently loaded SVG or PSD files as well. If there is no XML content named data when an SVG or PSD file is loaded, automatic variable replacement does not occur and any original variable values remain unchanged.

Adobe Document Server Developers Guide Dec 19, 2003 133 Replacing Variables in SVG and PSD Files 7 Replacing Variables Explicitly

EXAMPLE 7.1 Automatic variable replacement on load In this example, the variables in sales.svg are automatically replaced by the data values in myData.xml.

EXAMPLE 7.2 Automatic variable replacement from the command line This command replaces the variables in the SVG file template.svg, then saves it to a new file named "Untitled." It does not execute any other commands. ADS -source template.svg -data myData.xml

Replacing Variables Explicitly

Use the applyVariables command to replace variable values explicitly at any point during the execution of the command set, after loading and naming both the replacement data and the file containing the variables. If you load the replacement data using the loadContent command (rather than passing it in as part of the request) you must name it using the out attribute: ● If you use the reserved name data, it is the same as passing the replacement data on the command line or with the request; ADS automatically applies that data to any SVG or PSD file that you load. The name data is also the default data content name for the applyVariables command. If you have named the content data, you need not specify the data attribute in the command. ● If you use any name other than the reserved name data, you must pass the name in the data attribute of the applyVariables command in order to apply those values to SVG or PSD content. It is not necessary to name the source file containing the variables, as long as it is the current content when the applyVariables command executes. However, if you name it with the out attribute of the loadContent command, you can make it current by specifying that name with the in attribute of the applyVariables command. When you replace variables explicitly, you can load the files in any order, and perform other manipulations before or after the variable replacement. This differs from automatic variable replacement, where the data file must be loaded first, and the replacement is performed immediately after the file containing variables is loaded.

NOTE: When setting up the template file and data file loads, take automatic replacement into account to avoid replacing variable values twice with the same data. For further information on the applyVariables command, see the Adobe Document Server Command Reference.

134 Dec 19, 2003 Adobe Document Server Developers Guide Replacing Variables in SVG and PSD Files Replacing Variables Explicitly 7

EXAMPLE 7.3 Loading multiple data sets for a single template file This example loads a single SVG template file, then replaces the variables with three different sets of data, writing out a new GIF file each time.

EXAMPLE 7.4 Streaming in replacement data In this example, a command set loads replacement data inline in a loadContent command, naming the XML content newData. It then loads the source PSD file containing the variables, and uses the applyVariables command to explicitly replace the variable values in the file with the new data. This example replaces variables of types image replacement and text replacement. Great guitar sale guitar.psd $100 Now 30% off!

Adobe Document Server Developers Guide Dec 19, 2003 135 Replacing Variables in SVG and PSD Files Variable Replacement Error Behavior 7 Specifying Replacement Data

Specifying Replacement Data

A replacement data file is an XML file containing variable replacement values inside a data element. Each replacement value is contained in a subelement named for the variable. For example: value For details of what kind of replacement data to provide for each type of variable, see “SVG Variable Replacement Syntax” on page 136 and “PSD Variable Replacement Syntax” on page 141.

Variable Replacement Error Behavior ADS expects the source SVG or PSD file to contain a variable definition to match every replacement value found in the data. ● If the data file contains a variable name that is not defined in the destination SVG or PSD file, ADS reports an error. ● If any variable value is missing from the data file, ADS reports a warning, and the variable value in the destination file remains unchanged. The data file need not replace every variable defined in the destination file. Any variable that is not mentioned in the replacement data remains unchanged. You are responsible for providing data in the correct format for the file format and variable type that you want to replace. ADS does not distinguish between SVG and PSD replacement data, or validate the replacement data. If you specify an existing variable in the replacement data, ADS replaces the bound element with the provided replacement value. If the replacement value is not in the correct format, the resulting file may be syntactically incorrect.

SVG Variable Replacement Syntax You can set variables that reference standard elements of the SVG file, as well as variables that allow easy and convenient modification of the graphing, text flow, and image replacement Adobe foreign object extensions. In a source SVG file, variable definitions are stored in the metadata portion of the file. A set of variable bindings defines the attributes and elements that can be replaced with specific data. Variable replacement data in an XML file is enclosed in a data element. The file contains an element for each variable to be replaced, where the name of the element corresponds to the

136 Dec 19, 2003 Adobe Document Server Developers Guide SVG Variable Replacement Syntax Replacing Variables in SVG and PSD Files Specifying Replacement Data 7

name of the variable. You set the variable names outside ADS, in Illustrator. The replacement value that you provide must be appropriate to the variable type: ● For a simple variable bound to an attribute, the replacement value is the new attribute value. ● The replacement value for a visibility variable is the new visibility value, true or false. ● The replacement value for an image replacement variable is the new embedded image data, or a file reference to the new referenced image file. ● For text and graph variables, the variable-name element contains the new element and its subelements with which to replace the original element, as shown in the examples below. A graph variable can be replaced by new graph data in the full graph syntax, as shown in “Replacing a graph variable” on page 139, or in an abbreviated syntax, as shown in “Abbreviated graph syntax data” on page 140. A text variable can be replaced at four different levels of the text flow hierarchy: – If the replacement data value is a flow element, ADS replaces the flow element in the source content with the new flow element. – If the replacement data value is text only, ADS replaces the text of the first span element of the first p element (or the text of the first p, if it has no span) of the flow element in the source content with the new text. It removes all other span and p elements. – If the replacement data value is a p element, ADS replaces all the child elements of the flow element with the new p element. – If the replacement data value is a span element, ADS replaces all the child elements of the first p element of the flow element with the new span element. It is possible to generate replacement data files programmatically by queries to a database, or by wrapping a series of user inputs into an XML file in the correct format.

EXAMPLE 7.5 Basic variable replacement The source SVG file contains a simple variable named fillcolor1 that is bound to the fill attribute of a circle. The following replacement data specifies a value of red for the variable: red

Adobe Document Server Developers Guide Dec 19, 2003 137 Replacing Variables in SVG and PSD Files SVG Variable Replacement Syntax 7 Specifying Replacement Data

EXAMPLE 7.6 Replacing a visibility variable The source SVG file contains a variable of type visibility with the name showimage, bound to the element Image1. In the SVG, this trait is actually controlled by the display attribute, which has a value of inline or none. This replacement data specifies a value of true for the variable showimage, which causes ADS to set the value of Image1/@display to inline. true

EXAMPLE 7.7 Replacing an image variable with an image file reference The source SVG file contains a variable of type image replacement with the name newimage, bound to the element Image2. images/ducky.png This replacement data specifies a URI as the value of the newimage variable, which causes ADS to set the value of /Image2/foreignObject/imageReplacement/@xlink:href to that URI. When the image is displayed, the relative path will be interpreted with respect to the SVG file location.

EXAMPLE 7.8 Replacing an image variable with embedded image data The source SVG file contains a variable of type image replacement with the name newimage, This example replaces the image with base-64 encoded image data, which the command writes to an optimized format and embeds in the file. data:image/gif;base64, R0lGODlhBQAFAIAAABsbG09PTyH5BAAAAAAA LAAAAAAFAAUAAAIHjB9woItXAAA7

138 Dec 19, 2003 Adobe Document Server Developers Guide SVG Variable Replacement Syntax Replacing Variables in SVG and PSD Files Specifying Replacement Data 7

EXAMPLE 7.9 Replacing a graph variable The source SVG file contains a variable of type graph with the name newsalesdata, bound to the graph object named Sales1. This replacement data specifies data and values subelements as values of the newsalesdata variable. ADS uses that information to replace the values of /Sales1/foreignObject/graphdata and /Sales1/foreignObject/graph/values. Seattle San Jose Minneapolis Sun 0 1 2 Mon 2 0 1 Tue -3 0 2 Wed 0 0 1 Thu 1 0.5 1.5 Fri 4 1 5

Adobe Document Server Developers Guide Dec 19, 2003 139 Replacing Variables in SVG and PSD Files SVG Variable Replacement Syntax 7 Specifying Replacement Data

Sat 3 0 1 For further information on graphing, see Chapter 9, “Creating Dynamic Graphs in SVG Files.”

EXAMPLE 7.10 Abbreviated graph syntax data Here is an example of abbreviated data file syntax, shown for the variable newsalesdata from the previous example. Note that there must be a comma preceding the first line of data, which reserves a spot for the name of a row title. Semicolons delimit the values. ,Seattle,San Jose, Minneapolis;Sun,0,1,2;Mon,2.0,1; Tue,-3,0,2;Wed,0,0,1;Thu,1,0.5,1.5;Fri,4,1,5;Sat,3,0,1

EXAMPLE 7.11 Replacing text using a text variable The source SVG file contains a variable of type text with the name newcaption, bound to the text object named Caption1. Hello, ADS! This replacement data specifies the value of the newcaption variable. ADS sets the value of "/Caption1/foreignObject/flowDef/flow" (or its first

or subelement) to that value.

EXAMPLE 7.12 Replacing text attributes using a text variable The source SVG file contains a variable of type text with the name newSamples, bound to the text object named SampleColors.

Sample 1:

Red

140 Dec 19, 2003 Adobe Document Server Developers Guide PSD Variable Replacement Syntax Replacing Variables in SVG and PSD Files Specifying Replacement Data 7

This replacement data provides an entire flow element, with subelements and attributes that define the text style, as well as the text itself. When ADS replaces the element, the text in the SVG content changes to the two paragraphs “Sample 1:” and “Red” while the fill color of the text “Red” changes to the color red: Sample1: Red For further information on text flows, see Chapter 6, “Changing Text in Images.”

PSD Variable Replacement Syntax Unlike SVG, PSD is a binary format. When you load a PSD file into ADS, you can access and manipulate certain features using an abbreviated XPath syntax with the set command. ADS translates the elements and attributes that you set in this way to and from their PSD-format equivalents. Only a limited set of features are accessible through the set command. You can use ImageReady 7 to create and bind variables of the following types: ● visibility: The variable can be bound to an image, a layer, or a layer set. The replacement value is true or false. ● text replacement: The variable can be bound to the text flow in a text layer. The replacement value is simple text, which replaces all of the text in the layer. Text attributes such as the font are unchanged. For more information on text replacement methods and text flows, see Chapter 6, “Changing Text in Images.” ● pixel replacement: The variable can be bound to an image in an image layer. The replacement value is a new image file specification, where the file is accessible to the ADS server process, or the new image in base-64 encoded format. When ADS replaces an image value for a pixel-replacement variable, it uses the same mechanism as the replacePixels command, but with position and scaling settings that match those set in the Variables dialog box in ImageReady.

EXAMPLE 7.13 Replacing a visibility variable The source PSD file contains a variable of type visibility with the name showimage. This replacement data sets the value to true. true

Adobe Document Server Developers Guide Dec 19, 2003 141 Replacing Variables in SVG and PSD Files PSD Variable Replacement Syntax 7 Specifying Replacement Data

EXAMPLE 7.14 Replacing a text variable The source PSD file contains a variable of type text replacement with the name caption. This replacement data sets the value to "new title". "new title"

EXAMPLE 7.15 Replacing a pixel variable using a file reference The source PSD file contains a variable of type pixel replacement with the name product. This replacement data sets the value to the contents of the referenced JPEG file. ADS resolves the relative path to that file with respect to the base input URI. images/guitar.jpg

EXAMPLE 7.16 Replacing a pixel variable with an embedded image The source PSD file contains a variable of type pixel replacement with the name product. This example loads a replacement image in base-64 encoded format, giving it the reserved name data. When it loads the source PSD file, the pixel value is replaced automatically with the new image data. The example then saves the file with the new image value to an optimized format (as determined by its optimization settings). data:image/gif;base64, R0lGODlhGAAcALMAAP/u7v+7u/8REf93d/8iIv/d3f9mZv9VVf+ qqv9ERP+IiP+Zmf/MzP8zM/8AAP///yH5BAAAAAAALAAAAAAYABwAAA TJ8MlJq70YA0aT+5/SgaEycJIHCgAVkI6yDMWkfoZFkGJ1OyiKgme 5JS4AAag3+iwmrYlhWfwIhIEJg+oLUQg5m7frqEkWH/MDHasemsyHMp5y ZCVbq7DtI1CmIE8SBXwdcQGIDQ5HEwd0DwdRFWxBAY+CFkkOYWeZGQy IFJIZpKWmpCY2HacHVxIOFLCmCQQFA4oACQ2ECQO5uxYBAwkvDzEKy LAxCQmPCgQEQ8bIyXIKBwFqUggIB7cEAA0NAAQNvg0JQafr7BcRADv=

142 Dec 19, 2003 Adobe Document Server Developers Guide PSD Variable Replacement Syntax Replacing Variables in SVG and PSD Files Specifying Replacement Data 7

The Automatic Text Variable For any PSD file with one or more text layers, ADS defines a PSD variable named defaultTextLayer. This allows you to automatically replace the text in the topmost text layer upon loading the file into ADS, without having to first define such a variable outside ADS. (The topmost layer is the one with the highest index number.) For more information, see the Adobe Document Server Command Reference.

EXAMPLE 7.17 Replacing the default text variable To replace the text in the topmost text layer, specify the new text value for the default variable named defaultTextVariable in the XML replacement data: "new text"

Adobe Document Server Developers Guide Dec 19, 2003 143 Replacing Variables in SVG and PSD Files PSD Variable Replacement Syntax 7 Specifying Replacement Data

144 Dec 19, 2003 Adobe Document Server Developers Guide 8 Operations Specific to SVG Files

This chapter covers a series of topics relating to the manipulation of SVG files. It includes the following sections:

Overview starting on page 145 Foreign Objects starting on page 145 SVG Font Considerations starting on page 148 Illustrator SVG Template Tips starting on page 149 Converting SVG to Raster starting on page 151 Converting SVG to PDF starting on page 151

Overview

To successfully use SVG files with ADS, you need to understand the concept of foreign objects in SVG and the way that Adobe uses the concept within ADS. Foreign objects require corresponding SVG renderers, which may handle graphing, text flows, or images. There are some considerations about fonts within SVG files that you need to be aware of to ensure that fonts are properly referenced and/or embedded and that the references are resolved. In addition, there are techniques you can use with Illustrator that will simplify the task of creating ADS command sets to manipulate the SVG file. One of the primary destinations for SVG source material is to convert them into PDF. The convertSVGToPDF command, described in “Converting SVG to PDF” on page 151, accomplishes this. For details of how individual SVG elements are converted to PDF, see the Adobe Document Server Command Reference.

Foreign Objects

ADS uses the concept of a foreign object from the SVG specification to extend the functionality of basic SVG. A foreign object is used to describe an object outside the SVG specification. A foreign object is an XML description of an object, such as a graph. The SVG specification defines a plug-in type of rendering architecture. If an SVG renderer encounters a reference to a foreign object in an SVG file, it searches its list of pluggable extensions. If the renderer finds a proper rendering extension, it calls the plug-in to render the foreign object. When an SVG renderer such as ADS encounters a foreign object, it looks in its list of renderers for one that can render the object.

Adobe Document Server Developers Guide Dec 19, 2003 145 Operations Specific to SVG Files Graph Foreign Object 8 Foreign Objects

Foreign objects are typically wrapped in a switch element in an SVG file. As the SVG renderer processes the file, when it encounters a switch containing a foreign object, the renderer determines whether or not it can interpret that foreign object. The renderer will render the first foreign object within the switch that it recognizes. If the renderer cannot interpret any of the foreign objects in the switch, it will render the default group of the switch. This means that even complex files with multiple foreign objects can still be rendered with even the most basic SVG renderers. For instance, if you exported a file from Illustrator that contained a graph, a third-party renderer (for example, an SVG viewer not provided by Adobe) might not be able to render the Illustrator-generated foreign object. Therefore, a traditional SVG representation of the graph is included as the last branch of the switch element. When the third-party renderer fails to render the Adobe foreign object, the SVG renderer resorts to rendering standard SVG. The syntax and structure of using a switch element in this way is described in more detail in “Graph Objects in ADS” on page 159. When ADS interprets the foreign object and makes data and format transformations on that object, it substitutes the resulting SVG description for the original default. Thus the resulting SVG file can be rendered in its transformed form by standard SVG renderers. Adobe has defined foreign objects that describe sophisticated graphing, flexible text handling capability (text flows), and enhanced image replacement. Adobe provides renderers that handle these types of foreign objects.

Graph Foreign Object ADS supports a specialized graph foreign object for SVG files. A graph foreign object is used for graphs that contain data replaced through variable replacement. A graph foreign object specifies a set of data to be graphed and a set of formatting instructions that describe how the data should be converted into a graph. A graph foreign object is described in an SVG file within a foreignObject element, usually embedded inside of a switch element. The graph replacement foreignObject contains two elements: ● The graph element. This element describes how to render the graph. It usually includes separate data and format sub-elements. ● The targetRef element. This element references the target element, which is the default SVG version, such as the template image created by Illustrator. The requiredExtension attribute of the graphing foreignObject is set to the “http://ns.adobe.com/Graphs/1.0/” namespace. The graphdescr element is defined in this same namespace. For more information on graphs and to view an example, refer to the “XML Grammar for Graphing” chapter in the Adobe Document Server XML Grammars Reference. The targetRef element is in the “http://ns.adobe.com/Extensibility/1.0/” namespace. For further information, see the “XML Grammar for Object Extensibility” chapter in the Adobe Document Server XML Grammars Reference.

146 Dec 19, 2003 Adobe Document Server Developers Guide Text Flow Foreign Object Operations Specific to SVG Files Foreign Objects 8

Text Flow Foreign Object ADS supports a specialized text flow foreign object for source SVG files. A text flow foreign object is typically used for text flows replaced via variable replacement. A text flow foreign object is described in an SVG file within a foreignObject element embedded inside of a switch element. The text flow replacement foreignObject contains two elements: ● The flowDef element — This element describes how to render the text flow. ● The targetRef element — This element references the target element, which is a text element, that is to be modified per the definition of the flowDef element. The requiredExtension attribute of the image replacement foreignObject is set to the “http://ns.adobe.com/Flows/1.0/” namespace. The flowDef element is defined in this same namespace. For more information on text flows and to view an example, refer to the “Accessing Raster Content” chapter in the Adobe Document Server XML Grammars Reference. The targetRef element is in the “http://ns.adobe.com/Extensibility/1.0/” namespace. For further information, see the chapter “XML Grammar for Object Extensibility” in the Adobe Document Server XML Grammars Reference.

Image Replacement Foreign Objects ADS supports a specialized image replacement foreign object for source SVG files. An image replacement foreign object is typically used for images replaced via variable replacement. An image replacement foreign object can control more than just the image to use as a replacement. It also controls how the image is to be replaced, such as whether to use fit, fill, or ratio replacement. In addition, the object controls where to position the new image relative to the original image. An image replacement foreign object is described in an SVG file within a foreignObject element embedded in a switch element. The image replacement foreign object contains two elements: ● The imageReplacement element. This element describes how to render the image. ● The targetRef element. This element references the target element, which is an image element, that is to be modified per the definition of the imageReplacement element. The requiredExtension attribute of the image replacement foreignObject is set to the “http://ns.adobe.com/ImageReplacement/1.0/” namespace. The imageReplacement element is defined in this same namespace. For more information on image replacement, and to view an example, refer to the “XML Grammar for Image Replacement” chapter in the Adobe Document Server XML Grammars Reference. The targetRef element is in the “http://ns.adobe.com/Extensibility/1.0/” namespace. For further information, refer to the “XML Grammar for Object Extensibility” chapter in the Adobe Document Server XML Grammars Reference.

Adobe Document Server Developers Guide Dec 19, 2003 147 Operations Specific to SVG Files Embedded Fonts in SVG 8 SVG Font Considerations

SVG Font Considerations

This section discusses font behavior and caveats with regard to the SVG file format. This section discusses: ● Embedded fonts in SVG ● Resolving font references within SVG For information on installing and configuring fonts, refer to the ADS Installation and Configuration Guide.

Embedded Fonts in SVG SVG files can reference external fonts, or they can contain the required font information in embedded fonts. Embedded fonts might not include font information for all glyphs within a font, which can affect results if the text is changed to require additional glyphs. Embedded fonts can be referenced by text within text and span elements. If you are manipulating text that is not part of a text flow (that is, text that is not contained within a flowDef foreign object), ADS uses and preserves any embedded fonts. In case you make changes in the text that requires additional glyphs not previously embedded, make sure the fonts required are available and indicated to ADS. For further information on installing and configuring fonts, refer to the ADS Installation and Configuration Guide. Embedded fonts cannot be used by text within text flow elements. If you are manipulating a text flow that uses embedded fonts, the embedded fonts are ignored. If you plan to manipulate flow text in an SVG file, do not embed any fonts, since the fonts are never used and only add extraneous bytes to the file size.

Resolving Font References within SVG Any font references made from within an SVG file are resolved relative to the location of the SVG file itself. Once inside the SVG file, the location of the ADS commands is no longer relevant. This behavior mirrors what happens in HTML. When you open a new page in your browser, all relative references on that new page are resolved relative to the location of the new page. For example, assume you have a command file located in /my/directory/location/ADS/commands.xml. Your command file contains the following:

148 Dec 19, 2003 Adobe Document Server Developers Guide Naming Shapes and Layers Operations Specific to SVG Files Illustrator SVG Template Tips 8

Also assume that the file referenced in the loadContent command is an SVG file residing in /my/directory/location/svg/mysvg.svg. The relative path in the command file properly accesses this file. An excerpt of this file is shown here. Note the relative location for the fonts.

Illustrator SVG Template Tips

The following recommendations will help you prepare SVG files that are easy to work with in ADS.

Naming Shapes and Layers Illustrator converts layers to g (group) elements when it exports them to SVG. If you want to use ADS to manipulate group elements within an SVG file, name the corresponding layer within Adobe Illustrator before you save out the SVG file so that you can refer to the group by name. When you create an image that has multiple shapes on one layer, name each shape with a descriptive name, so that you can address it by name with the ADS set command. Illustrator converts object names to identifiers when it exports them to SVG. In the target of a set command, you can refer to layers or shapes using the id() function in the XPath. For more information on the abbreviated XPath syntax that ADS supports, see the Adobe Document Server XML Grammars Reference.

Adobe Document Server Developers Guide Dec 19, 2003 149 Operations Specific to SVG Files Using Crop Marks 8 Illustrator SVG Template Tips

Variable replacement is an efficient and easy way to have ADS do text replacement, visibility, and image replacement. You can assign one variable to multiple objects on one layer, which allows you to change a feature (such as the visibility) of all of the objects at one time.

Using Crop Marks When ADS rasterizes SVG into an image, it uses any existing crop marks to define the image bounds. If crop marks are not set, it uses the bounding box to determine the crop area. Using the bounding box could result in inadequate white space or margins around an object, depending on its content, placement, the placement of other elements on the finished page, and whether or not it has replaceable content. If a template has replaceable content that might vary in size, it is important that you export a template that is large enough to hold the results of the replacement data. For example, if you replace data in a graph and the data set is larger than the original data set, it could extend the graph outside its original bounds. Similarly, replacement text strings might be longer than the original ones, or replacement images larger than the original images. In addition to careful planning, you can avoid these problems by using crop marks. For best results, set crop marks in Illustrator for SVG template objects. To set the size of a template in Illustrator, draw a rectangle the size and position of the template, select the rectangle, and choose Object > Crop Marks > Make. This makes the template the size of the crop marks, regardless of the size of current content. For further information on setting crop marks, see the online help in the Illustrator application.

Saving SVG for ADS Compatibility When you save an SVG file from Illustrator, use the following Advanced options in the Save as SVG dialog box to make the SVG file compatible with ADS: ● Set CSS Properties to Presentation Attributes. The other options save style data that ADS does not need. ● Set Encoding to UTF-8. ● To save variable or flowDef information, select Include Extended Syntax for Variable Data. ● To save slice data and optimization settings, select Include Slicing Data. ADS processes requests faster if you turn off Preserve Illustrator Editing Capabilities in the Save as SVG dialog main window. This option adds data that ADS does not use.

150 Dec 19, 2003 Adobe Document Server Developers Guide Saving SVG for ADS Compatibility Operations Specific to SVG Files Converting SVG to Raster 8

Converting SVG to Raster

Depending on how you intend to handle the SVG image, it may be desirable to convert the ADS internal SVG representation to a raster image representation. The convertSVGToRaster command will do this conversion for you. See the Adobe Document Server Command Reference for details, including available options. The convertSVGToRaster command rasterizes the SVG file, creating raster content with a single layer, marked to be saved as a PSD file. If the SVG file contains variables, use the ADS commands described in Chapter 7, “Replacing Variables in SVG and PSD Files” to replace their values after the SVG file is loaded. The convertSVGToRaster command converts the current values of any variables at the time it executes. When the command completes, it makes the generated raster content current.

Converting SVG to PDF

ADS allows you to convert SVG content into PDF content. The resulting PDF content may be used as-is, or may be merged with other components to create a full PDF document. The convertSVGToPDF command takes a currently active SVG content holder and converts it to PDF. The resulting PDF content can be manipulated with any of the other PDF manipulation commands, including combining the converted image with text or other images into a larger PDF document. Typically, you or a designer create an SVG template in Illustrator and use the Variables palette to identify what text, image components, and chart data are to be substituted by ADS. An XML data file is tagged according to the ADS rules described in Chapter 9, “Creating Dynamic Graphs in SVG Files.” You then write commands that read the SVG template and the XML data, apply the variables to the template, and perform other manipulations of the SVG template. When the variables have been applied to the template, you can use the convertSVGToPDF command on that modified SVG template to create PDF content. You can save the resulting image as a PDF file by itself, or you can merge it with other PDF pieces to create a finished document. Each SVG template defines an individual image as a single page, not where that image appears in the resulting document. Multiple templates may be substituted, converted, and included in single or multiple output document pages. Other formatting, such as other contents of the page and assembly of multiple pages into a complete document, is controlled by other ADS commands.

Adobe Document Server Developers Guide Dec 19, 2003 151 Operations Specific to SVG Files Saving SVG for ADS Compatibility 8 Converting SVG to PDF

152 Dec 19, 2003 Adobe Document Server Developers Guide Creating Dynamic Graphs in SVG 9 Files

This chapter describes the graphing capabilities of ADS. ADS provides tools that dramatically extend the graphing capabilities of Adobe Illustrator to create dynamic, programatically updatable graphs, that include graph formats that cannot be made in Illustrator. This chapter provides a working introduction to dynamic graphs by first looking at a set of sample files provided with the product. It then takes you through the details of the components of graphs, and shows you how to produce graphs with Illustrator and then modify them in a variety of ways with ADS. For more information, refer to the Adobe Document Server Command Reference and the Adobe Document Server XML Grammars Reference. This chapter includes the following sections:

Overview starting on page 154 A Working Sample starting on page 155 Graphing Basics starting on page 158 Graph Formatting Overview starting on page 160 ADS Graphing Features Not Supported by Illustrator starting on page 163 ADS Features Applicable to All Graph Types starting on page 166 ADS Graph Features by Graph Type starting on page 167 Data Sets starting on page 169 XML Representation of Graph Data starting on page 172 Formatting a Graph starting on page 179 Graphing Data Columns starting on page 181 Sample Graph Format starting on page 184 Graph Transformations (Xforms) starting on page 186 String Substitutions starting on page 189 Strict and Lenient Graphing Modes starting on page 192 Graph and XML Examples starting on page 192 Graphing Template Guidelines starting on page 213

Adobe Document Server Developers Guide Dec 19, 2003 153 Creating Dynamic Graphs in SVG Files 9 Overview

Overview

With ADS and Adobe Illustrator 10, you can create a wide variety of dynamically generated graphs. You can create chart templates in a wide variety of styles using design tools that they are comfortable with — namely, Illustrator. Then, you can use ADS to apply dynamic data values to those templates, and even render the output in multiple formats and resolutions. ADS achieves this capability through its manipulation of SVG files containing variables, such as those created by using the Illustrator Variables palette. Using the Illustrator Variables palette, you can create individual SVG template pages that have graphically-defined areas into which text, images, and graph data content can be substituted. Alternately, because SVG is a text-based, ASCII format, a knowledgeable user who understands SVG format and syntax could edit an existing SVG file to include variables, or could create an SVG file from scratch. Many graphing features were introduced in Illustrator 9, and Illustrator 10 includes additional graphing features, plus support for Flow Text and Replacement Variables. The Replacement Variables feature is required to produce an SVG file for an automatically changeable, dynamic graph. For more information on substituting variables with real values, see Chapter 7, “Replacing Variables in SVG and PSD Files” and the applyVariables command in the Adobe Document Server Command Reference. Illustrator 10 allows you to create a subset of the graph formats that ADS is capable of interpreting and generating. The rest of the broad range of graph formats that ADS supports must be coded in XML. Whether you start with Illustrator or your own XML code, you can change the data being graphed, the formatting instructions, or both. The variable substitution mechanism in ADS is the simplest way to change the data being graphed. There are also ADS commands that allow you to change or replace the formatting instructions. This chapter describes how to write XML code to create and modify graphs — including adding graph elements that cannot be made in Illustrator and modifying elements that cannot be made into variables in Illustrator.

154 Dec 19, 2003 Adobe Document Server Developers Guide Creating Dynamic Graphs in SVG Files A Working Sample 9

A Working Sample

Using Illustrator, you or a designer first choose a graph type from the Charts palette and drags an instance of it onto a document. This step creates the basic chart object that will be customized. For instance, if you have chosen a column graph, you can create sample data columns and labels, change colors and fonts, and perform other transformations on the chart object. A sample column graph is included in the product’s samples folder, in the file: samples/ImageManipulation/test_files/templates/Column.ai It is shown in Figure 9.1.

FIGURE 9.1 A graph template created in Illustrator

You should consider creating sample data sets containing the minimum and maximum number of sample data columns that may appear in the chart. Because ADS can automatically change the scale of the graph axis to accommodate a varying number of data points, creating sample columns gives you a good idea how a graph appears as the data changes. Similar considerations of minimum and maximum limits in sample data sets apply to other graph designs. After the basic look and feel of the graph is created, you must select the graph in Illustrator and then choose to make it dynamic by using the Illustrator Variables palette, shown in Figure 9.2. This step assigns an SVG variable to the graph format and data. ADS uses this variable to render the graph with the dynamic data. Note that you can’t directly assign variables to many of the elements that make up the final appearance of a chart or graph. Changing these attributes requires a different approach that does not require Illustrator variables. That approach is discussed starting with “Graph Formatting Overview” on page 160 and continuing in the following sections.

Adobe Document Server Developers Guide Dec 19, 2003 155 Creating Dynamic Graphs in SVG Files 9 A Working Sample

FIGURE 9.2 The Illustrator Variables palette

For complete instructions, refer to the Illustrator 10 documentation. For your convenience, here is a summary: 1. Create a graph. 2. Select the graph and click Make Dynamic in the Variables palette. 3. In the Variables palette, click Capture Data Set. 4. From the Main menu, choose Save As > SVG. The SVG file created by Illustrator from the template in Figure 9.1 is available in the samples folder, in: samples/ImageManipulation/test_files/templates/Column.svg You can open this file in a text editor to examine the SVG file structure. The Illustrator-generated SVG file starts with some elements that identify the format and then has an svg element containing a hierarchy of elements: metadata, variableSets, variableSets, variables, variable. This variable element has a varName of Variable1, the name specified in Illustrator, shown in Figure 9.1. This variable element also contains the attribute docRef="id('XMLID_22_')". If you search the file for that ID string, you will find that it is the ID of a switch element further on in the file. The first sub-element of switch id="XMLID_22_" is a foreignObject. Within that foreign object is a graph element, and within that is a data element which specifies that it has four columns. In the SVG template, ADS expects a graph description to be embedded within a switch element, such as the switch element switch id="XMLID_22_" in Columns.svg. One branch of the switch contains a foreign object that includes data and format elements of the graph. The other branch contains the original template image. This switch and foreignObject structure gives SVG renderers something that they can display even if they cannot interpret the foreignObject. See “Foreign Objects” on page 145 for more details. The new data for this sample is found in the file samples/ImageManipulation/test_files/templates/column_data.xml. If you examine this file you will see that it consists of a single data element that contains a single element called Variable1. Within the Variable1 element is a structure intentionally similar to the structure found in Column.svg. Notice that in this instance, both the Column.svg template and the data in column_data.xml have four columns. This is not required; the value of numDataColumns is simply changed in the data file as needed.

156 Dec 19, 2003 Adobe Document Server Developers Guide Creating Dynamic Graphs in SVG Files A Working Sample 9

The commands to apply the new data to the template are in: samples/ImageManipulation/tasks/DynamicGraph.xml If you examine this file you will see that it consists of four simple ADS commands that: 1. Load the template file and give the result the internal name of template. 2. Load the data file and give the result the internal name of newData. 3. Apply the variables in newData to the template. 4. Save the result in a file called DynamicGraph. The file references in DynamicGraph.xml are relative to the tasks folder where the file is found. To actually run these commands requires invoking the ADS command line, giving the command file name as an argument. In this case, the command, run from within the tasks directory, is: altercast -commands DynamicGraph.xml Because the output file, DynamicGraph.xml, also comes with the product, it already exists and by default will not be overwritten. To force ADS to overwrite an existing file, add the option -resultOverwrite true to the preceding invocation. The resulting file is shown in Figure 9.3. For more details on the command line options, see the Adobe Document Server Command Reference.

FIGURE 9.3 A graph template with variables inserted

Adobe Document Server Developers Guide Dec 19, 2003 157 Creating Dynamic Graphs in SVG Files Parts of a Graph 9 Graphing Basics

Graphing Basics

This section discusses graphing basics such as parts of a graph, basic types of graphs, and the specific types of graphs supported in ADS.

Parts of a Graph Most graphs contain the following parts: ● Data objects ● Legend ● Major axis ● Minor axis The data objects are the main contents of the graph and compare the values being graphed. There are two ways of grouping the data objects: ● As series ● As clusters A series is a set of data objects that share common display characteristics. A series corresponds to a column in the tabular graph data. A cluster is a set of data objects that are graphed together. A cluster corresponds to a row in the graph data. For example, in a pie graph that has multiple pies, a series contains one wedge from each pie, and a cluster contains all the wedges that make up one pie. The legend identifies the series in a graph. Each series gets a graphical object and a label in the legend. The major axis (called a category axis in Illustrator) is the main layout axis for a graph. Points on the major axis are usually identified with labels. For example, in a bar graph, the major axis is the axis along which multiple bars are laid out. The minor axis (called a value axis in Illustrator) is the axis that measures values in the graph. Points on the minor axis are usually identified with numbers. For example, in a bar graph, the minor axis is the axis along which each bar extends. Not all graphs necessarily have all these parts, and some graphs have multiple parts. For example, a pie graph does not have a minor axis, and a radar graph has multiple minor axes.

Basic Graph Types ADS supports three basic types of graphs: ● Bar graphs compare one or more sets of values by using rectangles that have lengths proportional to the values. The ADS bar type includes Illustrator column, stacked column, bar, and stacked bar graphs.

158 Dec 19, 2003 Adobe Document Server Developers Guide Graph Objects in ADS Creating Dynamic Graphs in SVG Files Graphing Basics 9

● Point graphs use points to represent one or more sets of values, and can connect or fill sets of points in each set. The ADS point type includes Illustrator line, area, scatter, and radar graphs. ● Pie graphs are circular and use wedges to represent the relative percentages of the values compared. The ADS pie type includes Illustrator pie graphs.

Graph Objects in ADS ADS expects a graph description embedded in an SVG file within a switch element. One branch of the switch element is the graph foreign object, and the other branch is the rendered graph. If a foreign object renderer, such as ADS, is capable of interpreting the foreign object branch of the switch, it does so. Other SVG renderers, such as an SVG-compatible browser plug-in, might use the non-foreign, basic group branch. For more details on foreign objects and renderers, refer to “Foreign Objects” on page 145. When a graph switch element is generated in Illustrator, the default branch contains an SVG representation of the graph based on the sample data set in the template. When you use ADS to modify an Illustrator-created graph, the results of your manipulations replace the original SVG representation. The code template in Example 9.1 shows the basic structure of an SVG switch element, as might be created by Adobe Illustrator, or that you might create by hand. If you create this by hand, you do not need to create a default rendering of the graph, but you do need to create the group with the proper identifier, in this case “XMLID_2_”. This group will be replaced by ADS with the rendered graph.

EXAMPLE 9.1 XML structure of the switch element

Adobe Document Server Developers Guide Dec 19, 2003 159 Creating Dynamic Graphs in SVG Files Graph Layout 9 Graph Formatting Overview

Note in the above syntax that “i” is the prefix for the Illustrator namespace and “x” is the prefix for the extensibility namespace. You must define these namespaces elsewhere in your XML code. For more information on the extensibility namespace, refer to the Adobe Document Server XML Grammars Reference. The switch ids and g ids provided by Illustrator have a form like those used in the example; you may use your own format. Note that the group ID is used as the targetRef in the foreign object side of the switch. The transform matrix defines the position at which the generated graph appears. In the example, the first four numbers specify no scaling and no rotation. The last two values specify the X and Y positions of the lower-left corner of the graph. It is important to understand the difference between the graph data set and the graph format specification. The graph data set is described within a data element. The graph data set is that part of the input information that is independent of the graph format. The data set stays the same if you want to graph the same data in a different way. The data set is the part that changes if you want to graph different data. The graph format specification is described within a format element. The graph format specification is that part of the input information that is independent of the input data. The format is the part that changes if you want to graph the data in a different way. The format stays the same if you want to graph different data in the same way. The output from the graph library is an object tree, a set of type and path objects that represent the graph. When ADS creates an instance of a dynamic graph, it translates the object tree into SVG elements, and then replaces the original XML graph description with those SVG objects. When the SVG graph has been generated, the image format can be converted to any of the output formats supported by ADS.

Graph Formatting Overview

There are several basic formatting options you can apply to the various graph types in ADS. These options include layout and stacking options.

Graph Layout Graphs can have either a cartesian or a polar layout. Not all types of graphs support all layouts. Bar graphs can only be cartesian. Point graphs can be cartesian or polar, but if the point graph is polar, the major axis must be around the circumference and the minor axis along the radius. Pie graphs can have any layout, but having the major axis along the radius is not particularly useful. Axes can be set up for either cartesian or polar graphs so that the axes increases to the left or right for horizontal axes, up or down for vertical axes, clockwise or counterclockwise for circumference axes, and towards or away from the center for radius axes.

160 Dec 19, 2003 Adobe Document Server Developers Guide Stacking Options Creating Dynamic Graphs in SVG Files Graph Formatting Overview 9

Cartesian Layout A cartesian layout has perpendicular major and minor axes. For cartesian layout, the major axis can be horizontal with a vertical minor axis, or the major axis can be vertical with a horizontal minor axis. Specify the graph layout with the axisLayout attribute of the format element. For example, the syntax below specifies a cartesian layout: Polar Layout A polar layout has major and minor axes along the radius and circumference of a circle. For polar layout, the major axis can be along the radius or around the circumference, and the minor axis can be around the circumference or along the radius.

Stacking Options Stacking refers to whether the different objects in a cluster are stacked on top of each other. For a bar graph, if the graph is unstacked, the bars are next to each other. If the graph is stacked, the bars are stacked up one atop the other. If the graph is normalized, it is stacked, and each column is scaled to the full height or width of the graph. Graphs can have the following stacking options: ● Unstacked ● Stacked ● Normalized stack Unstacked graphs have independent values for each series. Stacked graphs have the values for the second and subsequent series being cumulatively added to the values for the first series. Normalized graphs are stacked, and the values for each cluster are adjusted so that the total for each cluster is the same, usually 100%. Normalized graphs are also known as “100% graphs” in some graphing packages. The default for bar and point graphs is unstacked, and normalized for pie graphs, but all graph types support all stacking options. Stacking is specified with the stacking attribute of the graphDesc element, as shown below:

Graph Type-Specific Formatting Options Different graph types have additional formatting options. For example, bar graphs have options to control the width of the bars. Point graphs have special options to control whether the points are connected, whether the area between the points and the axis is filled, and whether the points have markers drawn on them. Pie graphs have options to control the relative sizes and positions of the pies. The chapter “XML Grammar for Graphing” in the Adobe Document Server XML Grammars Reference includes a complete list of all available formatting options.

Adobe Document Server Developers Guide Dec 19, 2003 161 Creating Dynamic Graphs in SVG Files Specific Graph Types 9 Graph Formatting Overview

Specific Graph Types The graph types in Illustrator correspond to the following ADS formatting options:

Graph type Description Column A column graph is an unstacked cartesian bar graph. The major axis is horizontal. The horizontal axis increases in value from left to right. The minor axis is vertical. The vertical minor axis increases in value from the bottom to the top. Stacked Column A stacked column graph is a stacked cartesian bar graph. The major axis is horizontal. The horizontal axis increases in value from left to right. The minor axis is vertical. The vertical axis increases in value from the bottom to the top. Bar A bar graph is an unstacked cartesian bar graph. The major axis is vertical. The vertical axis increases in value from the top to the bottom. The minor axis is horizontal. The horizontal axis increases in value from left to right. Stacked Bar A stacked bar is a stacked cartesian bar graph. The major axis is vertical. The vertical axis increases in value from the top to the bottom. The minor axis is horizontal. The horizontal axis increases in value from left to right. Line A line graph is an unstacked cartesian point graph. The major axis is horizontal. The horizontal axis increases in value from left to right. The minor axis is vertical. The vertical axis increases in value from the bottom to the top. There may or may not be connecting lines and markers. The area below the points is not filled. Area An area graph is a stacked cartesian point graph. The major axis is horizontal. The horizontal axis increases in value from left to right. The minor axis is vertical. The vertical axis increases in value from the bottom to the top. There are no connecting lines or markers. The area below the points is filled. Scatter A scatter graph is an unstacked cartesian point graph. The major axis is horizontal. The horizontal axis increases in value from left to right. The minor axis is vertical. The vertical axis increases in value from the bottom to the top. There may or may not be connecting lines and markers. The area below the points is not filled. Pie A pie graph is a normalized cartesian pie graph. The major axis is horizontal and increases in value to the right. Radar A radar graph is an unstacked polar line graph. The major axis follows the circumference of the radar circle. The value of the major axis increases in a clockwise direction. The minor axis follows the radius. The value of the minor axis increases as it approaches the circumference. There may or may not be connecting lines and markers. The area between the points and the center is not filled.

162 Dec 19, 2003 Adobe Document Server Developers Guide General Graph Layout Creating Dynamic Graphs in SVG Files ADS Graphing Features Not Supported by Illustrator 9

ADS Graphing Features Not Supported by Illustrator Some graph features available in ADS are not available in Illustrator 10. You can take advantage of the additional graphing functionality within ADS by hand-editing an XML file, or generating the XML file with another program.

IMPORTANT: The graphing features described here have been tested extensively against SVG files generated in Adobe Illustrator 10. Use of these features with your hand- generated SVG graph files cannot be tested and may yield unpredictable results, depending on the organization and completeness of your hand-generated SVG graph files. Features supported in ADS that are not supported in Illustrator include features in the following categories: ● General graph layout ● Graph data ● Legends ● Ticks and labels ● Axes ● Explicit maps support ● String substitutions ● Sophisticated Xforms ● General additional graph features applicable to all or some graph types

General Graph Layout Additional features supported by ADS for general graph layout include: ● Setting axis direction ● Arranging polar graphs ● Setting origin direction Setting the Direction of the Major and Minor Axis ADS can draw any graph with the major axis vertical, and the minor axis horizontal. The only kinds of graphs with a vertical major axis that Illustrator can create are stacked and unstacked bar graphs. You can specify the axis direction by setting the direction attribute on the majorAxis and minorAxis elements when the axisLayout is cartesian on the graph element. ADS can set the major and minor axes to increase in either direction. In Illustrator, the major axis always increases to the right, down, or clockwise, and the minor axis always increases to the right, up, or out from the center. You can specify the axis orientation by setting the orientation attribute on the majorAxis and minorAxis elements. Refer to the chapter “XML Grammar for Graphing” chapter in the Adobe Document Server XML Grammars Reference for more details.

Adobe Document Server Developers Guide Dec 19, 2003 163 Creating Dynamic Graphs in SVG Files Legends 9 ADS Graphing Features Not Supported by Illustrator

Arranging Polar Graphs ADS can arrange pie graphs in a polar fashion, with the pies either arranged along the radius (not very useful) or around the circumference (useful). The only polar graphs that Illustrator exports are point graphs, with the major axis around the circumference (radar graphs). This is controlled by setting the direction attribute on the majorAxis and minorAxis elements when axisLayout attribute is polar on the graph element. Setting Origin Direction In ADS, both pie and point polar graphs can set the zero angle to any direction by setting the originDegrees attribute on the format element. Illustrator always has the origin pointing straight up (ninety degrees). Graph Data ADS provides additional control over graphed data, including the ability to ignore data columns and graphing conflicting data values. Ignoring Graph Data ADS can completely ignore a column of graph data. Ignoring data columns is done by including an ignoredDataColumns element in the format element. Illustrator never generates a graph with ignored data columns. Handling Conflicting Data ADS can handle graphing multiple data points with conflicting major axis values when two rows contain the same major value. If more than one data point in a series has the same value along the major axis, Illustrator always graphs the points separately. In addition to graphing the conflicting values separately, ADS can graph the sum, product, maximum, minimum, average, or count of the conflicting values. You can control the handling of conflicting data by setting the valueConflict attribute on the majorAxis element. For further information on graphing elements and attributes, refer to the “XML Grammar for Graphing” chapter in the Adobe Document Server XML Grammars Reference. To view an example graph and its XML, see “Graph with Conflicting Data” on page 204.

Legends In ADS, you can position a legend to the top, right, left, or beneath a graph by setting the position attribute on the legend element. In Illustrator, positioning a legend is limited to the top or right, and for pie graphs, only to the inside. Additional legend features accessible only in ADS include reversing legend order, and adding more text to legend strings. You can reverse the normal order of legends by setting the order attribute on the legend element. For further information on the legend element and its attributes, refer to the Adobe Document Server XML Grammars Reference.

164 Dec 19, 2003 Adobe Document Server Developers Guide String Substitutions in Axis and Legend Labels Creating Dynamic Graphs in SVG Files ADS Graphing Features Not Supported by Illustrator 9

String Substitutions in Axis and Legend Labels Another convenient feature is the ability to include additional text in the legend string. You can add more text to a legend string by including the text within the legendString attribute on the graphDesc element. Insert the additional text after “%p:name”. The extra text can be static, as in “%p:name (in inches)”, or it can use strings defined in the data set, as in “%p:name (in %P:units)”. You can also substitute strings in axis labels. For more information on string substitutions, “String Substitutions” on page 189. To view an example graph and its XML, see “Accumulation and Multiple Graph Descriptions” on page 197.

Ticks and Labels You can set labels and ticks on an axis independently of one another in ADS. In Illustrator, ticks and labels must be set together. In ADS, you can give ticks a numeric length rather than just long and short. Subticks can have different lengths than major ticks. For more information, see the tickLength and subTickLength attributes of the axis element as described in the Adobe Document Server XML Grammars Reference.

Axes In ADS, you can display arbitrarily many axes in a graph. You can also repeat axes throughout a graph by setting the repeat attribute on the axis element as described in the Adobe Document Server XML Grammars Reference. Illustrator only allows repetition of axes for radial axes in radar graphs. ADS also allows you to position axes in various places in the graph. You can position the axes by specifying values for the positionBase and positionOffset attributes on the axis element. The positionBase attribute value can be a number, or it has a variety of special values like "minEdge", "dataMin", and "dataAbsMin". The positionOffset attribute is a number and, if specified, its value is added to whatever value the positionBase resolves to. The attributes are described in the Adobe Document Server XML Grammars Reference.

Maps ADS provides two ways to specify per-column maps in the data element section: implicit or explicit. The explicit map feature allows more flexibility in the representation of data sets. Illustrator only uses implicit maps. For more information on maps, see “The Impact of Maps on Graph Data” on page 169.

Adobe Document Server Developers Guide Dec 19, 2003 165 Creating Dynamic Graphs in SVG Files Transformations 9 ADS Features Applicable to All Graph Types

Transformations After a graph is created, its appearance can be changed by graph transformations, called xforms for short. ADS provides a wide variety of ways to specify which objects in a graph are modified by xforms; Illustrator only uses a subset. Xforms are described in detail beginning on page 186. The following values for xformBase in the what element are not used by Illustrator: ● graphics ● fill ● stroke ● axis The following elements in a whichSeries or whichPoint element are supported in ADS but are not used by Illustrator: ● nthFromEnd ● nthFromStart ● nthRepeat ● nthRepeatFromEnd ● nthRepeatFromStart Illustrator never creates whichPoint elements without also specifying a single series in a whichSeries element. ADS supports whichPoint elements that apply to all series. Illustrator does not use what elements that contain intersections or differences and only uses union. ADS supports intersection, differences, and unions.

ADS Features Applicable to All Graph Types

This section discusses basic graph features supported by ADS regardless of graph type. There are examples of some of these features at the end of this chapter. The following graph features are applicable to all graph types: ● Stacking and normalizing ● Accumulating graph points ● Multiple graph descriptions

Stacking and Normalizing ADS can stack or normalize any kind of graph. In Illustrator, bar graphs can be stacked, area graphs are always stacked, and pie graphs are always normalized. Normalized stacking is stacking in which each column of data is scaled so that all the columns reach the same height. Some other graph programs call these “100% graphs”. This is controlled by setting the stacking attribute on the graphDesc element. If you choose to normalize the stacking, you can set the total to something other than 100 to by setting the normalizedStackTotal attribute on the graphDesc element. Refer to the section on “Stacking Options” on page 161 for more information.

166 Dec 19, 2003 Adobe Document Server Developers Guide Accumulating Graph Points Creating Dynamic Graphs in SVG Files ADS Graph Features by Graph Type 9

Accumulating Graph Points ADS can accumulate successive points instead of graphing the points separately. For example, if you had graph data that was the amount of rainfall on each day, you could set it so that the value graphed for each day is the sum of all the values thus far instead of being the amount for that day. This is controlled by setting the accumulation attribute on the graphDesc element. To view an example graph and its XML, see “Accumulation and Multiple Graph Descriptions” on page 197.

Multiple Graph Descriptions ADS allows an SVG graph template to contain multiple graph descriptions that all use the same data. All of the graph descriptions must use the same basic layout (cartesian or polar, and the orientation and increasing direction of the axes) but they can have different formatting options and can even be different graph types. For example, a template could contain two graph descriptions, one that displays the first series as a bar graph and one that displays the second series as a point graph. ADS allows you to specify multiple graphs by defining more than one graphDesc element. If there is more than one, the order the graphs are drawn is controlled by setting the order attribute on the graphDesc elements. For example, you could have a graph that displays the rainfall for each day as a bar, and behind that a filled point graph showing the cumulative rainfall. To view an example graph and its XML, see “Accumulation and Multiple Graph Descriptions” on page 197.

ADS Graph Features by Graph Type

This section lists features pertinent to each type of graph.

Bar Graph Features Additional ADS bar graph features include cluster granularity and sorting of graphed values. Cluster Granularity ADS can set the data ranges for each cluster in a bar graph to be something other than one (1). This is controlled by setting the granularity attribute on the graphDesc element. For example, if the data along the major axis had values of 10, 20, and 30, setting granularity to 10 would give 3 clusters, while setting it to 5 would give 6 clusters (3 of the clusters empty) and setting it to 1 would give 30 clusters (27 empty clusters). Sorting Values ADS can sort the values in bar graphs. This is controlled by setting the sorting attribute on the graphDesc element.

Adobe Document Server Developers Guide Dec 19, 2003 167 Creating Dynamic Graphs in SVG Files Point Graph Features 9 ADS Graph Features by Graph Type

Point Graph Features ADS allows any combination of stroking the connecting line, filling the area below, and drawing data points. This is controlled by setting the points, fill, and lineStyle attributes on the graphDesc element of a point graph. Illustrator cannot combine filling with anything else. Additional features for point graphs include setting point size and shape and setting stroke width. Setting Point Shape and Size ADS can draw round data points instead of square ones by setting the points attribute value to round on the graphDesc element. ADS allows you to set the size of the points by setting the pointSize attribute on the graphDesc element of a point graph. Setting Stroke Width ADS allows you to set the stroke width for a stroked point graph by setting the value of the lineWidth attribute on the graphDesc element of a point graph. Illustrator can only do this if the stroke is set to be a filled path. Sorting Values ADS provides more options for sorting the values in pie graphs than Illustrator does. This is controlled by setting the sorting attribute on the graphDesc element.

Editing Exported Templates Illustrator cannot directly export graph templates with options supported only by ADS, but you can edit the resulting XML to enable non-standard options.

IMPORTANT: Any changes to the XML will be lost if the template is imported back into Illustrator. As described in the previous sections, some of the graph types you can create through manual template editing include: ● Normalized bar graphs. ● Point graphs that combine filling with connecting lines or point markers. ● Unstacked filled point graphs, perhaps using transparency to allow partially-hidden filled areas to be seen. ● Point graphs with a vertical major axis. ● Pie graphs with the major axis being vertical to arrange pies vertically, or around the circumference to arrange pies in a circle. ● Filled or stacked radar graphs.

168 Dec 19, 2003 Adobe Document Server Developers Guide The Impact of Maps on Graph Data Creating Dynamic Graphs in SVG Files Data Sets 9

Data Sets

A graph displays a multi-dimensional data set. The graph data format for ADS is an ordered set of n-tuples. Each n-tuple loosely corresponds to a table row, if you arrange your data in a tabular format. The set of entries in any single position of the n-tuple are called a data column, and correspond to a column in a tabular format. For example, a graph might depict the number of cups of coffee and donuts sold each weekday. Assume the following statistics shown in the traditional tabular format:

FIGURE 9.4 Sample sales data set

(Column 0) (Column 1) (Column 2) Day Coffee Donuts Mon 100 60 Tue 150 80 Wed 110 90 Thu 120 70 Fri 130 80

NOTE: The column number is meant to be used for reference here, and is not part of the graph table. Data columns have a zero-based index, so counting the columns begins with (column) zero and not (column) one. The n-tuples would be triples of the form (day, coffee, donuts): {(1, 100, 60), (2, 150, 80), (3, 110, 90), (4, 120, 70), (5, 130, 80)} Unlike a tabular format, which normally contains both graph data and labels, the data for graphs in ADS is strictly numeric. ADS uses name properties and maps to associate labels with the data. In the above tabular format example, the titles for the columns are represented by ADS as name properties defined for each column. Column 0 has the name property “Day”, c o l u m n 1 h a s t h e name property “Coffee”, a n d c o l u m n 2 h a s t h e name property “Donuts”. Column 0 in the example would also have a map to associate its numeric values with strings for the day of the week. The map for the above example would associate the value 1 with the string “Mon”, t h e v a l u e 2 with the string “Tue”, and so on.

The Impact of Maps on Graph Data Numeric values give you more control over positioning data in sparse data sets. The values 1, 2, 3, 4, and 5 in the first column (shown in bold above) not only identify the tuples, these values also control where the data is graphed. If the values Mon, Tue, Wed, etc., were actually in the

Adobe Document Server Developers Guide Dec 19, 2003 169 Creating Dynamic Graphs in SVG Files The Impact of Maps on Graph Data 9 Data Sets

tuples rather than the numeric values, and you chose to omit the Tuesday tuple, there would not be any way to indicate a placeholder space for the omitted tuple. For example, assume Tuesday was a holiday, and no coffee or donuts were sold, but the result graph still requires a placeholder for Tuesday. One way to achieve this is to include the triple (2, 0, 0) in the graph data. Another way to create a placeholder is to leave out altogether the triple for Tuesday. Since the days of the week that follow Tuesday have values 3, 4, and 5, ADS positions the existing n-tuples as if data for Tuesday was present. While maps are most commonly used for the first column of data, you can also use a map for other columns, or a globalMap for all columns. For example, a graph of student grades might have a global grade map that associates the value 4 with “A”, 3 with “B”, 2 with “C”, a n d s o o n , a s in Figure 9.5.

FIGURE 9.5 Sample grades data set

(Column 0) (Column 1) (Column 2) (Column 3) Student Exam 1 Exam 2 Final Larry343 Curly443 Moe243.5

Here is code that defines the global grade map: A B C D F To see an example of the grade map, see “String-Labelled Minor Axis” on page 201. This map could be used in the labelString element of a minor axis so that the labels on the axis display letter grades instead of numbers: %M:grade Maps and Intermediate Values The most important use of the map is to provide string values for labels on the minor axis. The grade map allows you to label the minor axis with letter grades instead of just with numbers. However, the height of the bars or position of the points is still controlled by the numeric values. For example, an entry of “3” creates a bar (or point) at the position labelled “B” on the minor axis. You can still have values that do not match the labels. Note the intermediate value of “3.5” for Moe’s Final in Column 3. There is no corresponding entry in the grade map for any intermediate values. In this case, “3.5” indicates a bar or point midway between “B” and “A”.

170 Dec 19, 2003 Adobe Document Server Developers Guide Properties for Graph Data Creating Dynamic Graphs in SVG Files Data Sets 9

If labels in the Column 0 were the only use for maps, there would not be much point in having separate globalMap and map elements. A map also enables you to specify entries in values elements using map string values instead of numbers. Using a globalMap allows you to do this for all columns. For example, instead of specifying a value in your XML data file as: 3 you could specify the value as: B since the global grade map “maps” the value of “3” to the string value “B”. However, you can only do this for values that correspond exactly to entries in the map. You cannot specify intermediate values such as “3.5” in this manner since they do not have corresponding entries in the map.

Properties for Graph Data Properties can provide additional information about the data in a graph. For example, a data set for rainfall could include a units property that describes whether the numbers in a column of the graph are inches or centimeters. Properties can either be associated with a single column of data, or they can be global and be used everywhere. A units property for a column could provide a units string that applies just to that column, while a global units property could provide a units string that applies to all columns. Although Illustrator cannot export graph templates that can make use of these additional properties, your XML templates can include the property values in the legends or axis labels of the graph. Properties and maps are identified with arbitrary strings. By convention, the property for a column that identifies the column is named “name”, and the principal map for the first column is also named “name”.

Adobe Document Server Developers Guide Dec 19, 2003 171 Creating Dynamic Graphs in SVG Files The Data Element 9 XML Representation of Graph Data

XML Representation of Graph Data

This section describes each child element of the data element within an SVG graph. This data element may be generated by Adobe Illustrator, or it may be in your own XML file. Following these descriptions is an XML example of a complete data element,“Sample Graph Format” on page 184.

The Data Element A data set is contained within a data element. The data element must contain a single child values element, and can also optionally contain zero or more propertyRow, property, map, and globalMap elements. The Values Element The values element contains the values to graph. The parent data element must have one and only one values element. The values element contains a series of row elements, each of which defines one tuple of data. Each row contains a series of value elements. Each value element can contain a number, a string, or nothing at all (null). If a value element contains either nothing or a string that does not have a corresponding map, it is treated as missing data. If there are fewer value elements than there are columns of data, the missing value elements are treated as missing data. Missing data is simply not graphed, allowing you to graph sparse data sets.

EXAMPLE 9.2 The values element 11798798 25001500 320030 410005 550003000 A value element is treated as a number if it can be interpreted as such. To force ADS to treat a value element as a string, add a type="string" attribute to the value element. This allows you to map these string values. For instance, you would want the name of the year 1998 to be treated as text, not as sparse data with nearly 2000 missing columns. You can force Illustrator to treat a number as a string by putting quotes around the numeric value in the data table. The Property Row Element Properties for columns are provided within a data element in an optional propertyRow element. The propertyRow element has a required attribute, key, that gives the name of the property, and contains a value element for each column giving the value of that property for the column.

172 Dec 19, 2003 Adobe Document Server Developers Guide The Data Element Creating Dynamic Graphs in SVG Files XML Representation of Graph Data 9

EXAMPLE 9.3 The propertyRow element The following example shows a sample propertyRow element that identifies the columns of a data set: Student Exam 1 Exam 2 Final This creates four column-specific properties with the key “name”: one for column 0, one for column 1, one for column 2, and one for column 3. Semantically, this identifies the column 0 as listing the student names, column 1 as displaying data for Exam 1, column 2 as displaying data for Exam 2, and column 3 as displaying data for the Final. The value elements within a propertyRow element are always treated as strings, even if they could be interpreted as numbers.

NOTE: The propertyRow name value for column 0 is frequently empty, since it corresponds to the blank upper-left table cell often found in graph data tables. In the above example, the first value line would read simply: Property Element A property that applies to an entire data set is provided within an optional property element in the data element. The property element requires the key attribute. The contents of the property element are the value of the property. A value element is not necessary.

EXAMPLE 9.4 A property element that defines units The following example shows a sample property element giving units: grade points In the above example, the contents of the property element, and therefore its value, is “grade points”. Map Element A map for a data set is provided in an optional map element. A map behaves like a translation table — each entry matches a key number with a row value. The map element has two required attributes: column, which gives the number of the column to which the map applies, and key, which gives the name of the map. The first column is column 0. The map element contains a series of entry elements, each of which has a key attribute. The key attributes for entry elements must be numbers, and correspond to the values used in a graph (e.g., 1, etc.).

Adobe Document Server Developers Guide Dec 19, 2003 173 Creating Dynamic Graphs in SVG Files The Data Element 9 XML Representation of Graph Data

EXAMPLE 9.5 An explicit map element The following example shows a sample map element for the first column of the data set shown in Example 9.7: Global Map Element A globalMap element provides a map available for use by all columns. It is nearly identical to a map element, except the global map does not contain a column attribute.

EXAMPLE 9.6 The globalMap element A B C D F Note that the map for a single column overrides the global map, if both use the same key.

EXAMPLE 9.7 A complete data element The following example puts all the elements in perspective. It shows a complete data element for a grade data example: Student Exam 1 Exam 2 Final A B D D F

174 Dec 19, 2003 Adobe Document Server Developers Guide The Data Element Creating Dynamic Graphs in SVG Files XML Representation of Graph Data 9

1 3 4 3 2 4 4 3 3 2 4 3.5 If a map exists for a column, the values element can hold values from a map instead of numeric values. The use of the map is indicated by using a key attribute on the value element. So given the grade value map shown in Example 9.6, the first row of data could be written as shown in this example:

EXAMPLE 9.8 Mapped values for data Larry B A B ADS first looks for a column-specific map with the given key, and if there is none, looks for a global map with the given key. If the map is not unique (it has more than one key that corresponds to the given value), which entry is used is undefined. Numeric value elements and key-lookup value elements can be mixed together arbitrarily. For example, if key-lookup data were specified for the grade example, it would still be necessary to specify Moe’s final grade using 3.5 since there is no map value that corresponds with 3.5. If a value element specifies a key that does not correspond to any map, a column map is automatically created for that column with the specified key. An entry is added to the map with its key taken from the row number, starting with 1, and its value taken from the specified value. This is called an implicit map, compared to the explicit map that is directly coded.

Adobe Document Server Developers Guide Dec 19, 2003 175 Creating Dynamic Graphs in SVG Files The Data Element 9 XML Representation of Graph Data

Thus if the first grade row in Example 9.8 had its value key misspelled, for example: B a new column map will be created, named graed, that looks like the next example.

EXAMPLE 9.9 A generated map The column is “1” because the map was generated from the first grade column. The key is the misspelled key name. The entry key is taken from the row number, and the value is the original value. This automatic generation of an implicit map can be used to avoid having to explicitly hand code a map. The following two example data elements are equivalent, but the first specifies its map explicitly and the second specifies its map implicitly. The second example automatically generates an implicit map that is identical to the explicit map in the first example.

EXAMPLE 9.10 A data element with an explicit map Day Coffee Donuts 1 100 60 2 160 80 3 110 90

176 Dec 19, 2003 Adobe Document Server Developers Guide The Data Element Creating Dynamic Graphs in SVG Files XML Representation of Graph Data 9

4 120 70 5 130 80

EXAMPLE 9.11 A data element with an implicit map Day Coffee Donuts Mon 100 60 Tue 160 80 Wed 110 90 Thu 120 70 Fri 130 80

Adobe Document Server Developers Guide Dec 19, 2003 177 Creating Dynamic Graphs in SVG Files Abbreviated Graph Data Syntax 9 XML Representation of Graph Data

The implicit map form is the most common map form for a data element. In most cases, and in all cases generated by Illustrator, there is only one propertyRow, and only the first column has an implicit map (i.e., key="name").

Abbreviated Graph Data Syntax If you are using the implicit map form, you may use the ADS abbreviated data set syntax that allows a briefer format for your data for variable replacement of graph data. The format is simple: columns are separated by commas; rows are separated by semicolons. The first row gives the labels for the columns in the data. The first row contains the values that would be used in the form of the full format. For most graph types, these are the column titles used in the legend. The subsequent rows contain the row data. The first value in all the subsequent rows is the title for that row. The first value in the first row (the propertyRow) must be null. Null values are indicated by no characters (including spaces) between commas, a row start and a comma, or the last comma and the row end (semicolon or just the end of the row set). The last row may exclude the final semicolon. The abbreviated form for the data set shown in the coffee and donuts “Sample sales data set” on page 169 is shown here: ",Coffee,Donuts;Mon,100,60;Tue,160,80;Wed,110,90;Thu,120,70;Fri,130,80;" An example of using abbreviated syntax on the ADS command line is shown in the example below. This example uses the template in Figure 9.1 and should be run in the samples/ImageManipulation/test_files/templates folder. It loads the template graph file Columns.svg on the command line and replaces the Illustrator-created variable named Variable1 with the data set specified within straight quotation marks. Note that the long command line is broken here for readability, but it should be typed all on one line. It may be easier to create an executable script file that can be run from the command line to execute this command:

EXAMPLE 9.12 Command line variable substitution altercast -source Column.svg -Variable1 ",Good Stock,Poor Stock;1998,25,100;1999,60,15;" -resultLocation "./" Again, the above command must be typed all on one line. The first entry of the first row must be empty, or an error results. This means that the first row must begin with a comma (shown here in bold) and thus must have one fewer data values than the other rows. The empty entry would be the name of the first column of data. This name is rarely displayed in a graph, and it cannot be included in the abbreviated syntax. The above data set begins with the column labels “Good Stock” and “Poor Stock”. Note also the specification of the result location. If you omit this, ADS will not know where to save the resulting graph. It does not default to the current directory. The notation used in the example explicitly sets the current directory. By default, the result is saved in a file named Untitled.gif. The result of the above command is shown in Figure 9.6.

178 Dec 19, 2003 Adobe Document Server Developers Guide Abbreviated Graph Data Syntax Creating Dynamic Graphs in SVG Files Formatting a Graph 9

FIGURE 9.6 Command line variable substitution

The abbreviated form does not support any additional propertyRow elements, any globalMap elements, any property elements, any explicit maps, any implicit maps for columns other than the first, or a name for the first column of data. It can be convenient to use the abbreviated graph data syntax when you replace the data set on the command line. Although the file can contain multiple graph data sets, you can specify only one XML data file with the -data option on the ADS command line. This method allows you to replace multiple data sets simply by using multiple variable names and associated abbreviated data.

Formatting a Graph

The format element determines the format of a graph. The format element can contain the following child elements: ● majorAxis ● minorAxis ● axis ● legend ● graphDesc ● xforms The majorAxis and minorAxis elements describe the layout of the graph and describe which data columns can be graphed on the major axis and which can be graphed on the minor axis. The next section, “Graphing Data Columns” starting on page 181, explains these elements in detail.

Adobe Document Server Developers Guide Dec 19, 2003 179 Creating Dynamic Graphs in SVG Files Abbreviated Graph Data Syntax 9 Formatting a Graph

The axis element describes an axis drawn in a graph. It is optional, but usually present. There are often multiple axis elements, each corresponding to one drawn axis. Each axis element must have a unique name attribute to identify it. The legend element describes the position and layout of the legend. The legend is optional. If there is no legend element, the graph does not have a legend. The graphDesc element describes the formatting of a bar, point, or pie graph for the graph data. There must be at least one graphDesc element in a template. If there are multiple graphDesc elements, there are multiple graphs superimposed upon each other. For example, you could have one graphDesc element that shows rainfall during a week separately for each day, and a second graphDesc element showing the cumulative rainfall throughout the week. You could also graph one column of data as a point graph and other columns as a bar graph. The xforms element contains a list of style changes to apply to a graph after it is created. Many kinds of changes are possible, including changing the font and size of graph labels, changing the colors of bars and other data objects, and replacing bars or markers with other pieces of artwork. The section “Graph Transformations (Xforms)” on page 186 describes xforms in more detail.

EXAMPLE 9.13 The basic structure of the format element This example shows the basic structure of a format element. Attributes are omitted for clarity.

180 Dec 19, 2003 Adobe Document Server Developers Guide Major and Minor Data Columns Creating Dynamic Graphs in SVG Files Graphing Data Columns 9

Graphing Data Columns

In Illustrator, the columns of data are always graphed in a fixed manner. For most types of graphs, the value in column 0 (the first column) is graphed against the values in each of the other columns. For scatter graphs, the value in column 1 is graphed against the value in column 0, the value in column 3 is graphed against the value in column 2, and so on.

Major and Minor Data Columns ADS requires an explicit description of the data column usage in the graph format. This takes the form of a majorDataColumns and a minorDataColumns element in the graphDesc element, each of which lists the columns of the data that fill that role in the graph. The XML for a graph that displays column 0 against column 1 and column 2 against column 3 would look like this: 0 2 1 3 The graphing library requires the majorDataColumns and minorDataColumns elements to contain the same number of elements, although you do not have to explicitly specify each one. If one of the major or minor data columns contains a single element, the graphing library duplicates that single element as many times as necessary to match the number of elements in the other. The XML for a graph that displays column 0 against columns 1 and 2 could specify column 0 twice: 0 0 1 2 In the above syntax, column zero is specified twice to match the number of majorDataColumns with the number of minorDataColumns.

Adobe Document Server Developers Guide Dec 19, 2003 181 Creating Dynamic Graphs in SVG Files Major and Minor Data Columns 9 Graphing Data Columns

Or you can specify column zero once as shown below and the graphing library duplicates the int: 0 1 2 The “Other” Element Either the majorDataColumns or minorDataColumns element can contain the child element other, which means every column of data that is not otherwise specified. Illustrator-generated templates that graph column 0 against each of the other columns use the following XML, which is the most common specification: 0 Creating Columns with the Base and Repeat Attributes The majorDataColumns and minorDataColumns elements can contain a description of a base and repeat calculation that yields a list of columns. The description is part of the child calculated element. Illustrator-generated templates for scatter graphs use the following XML: This states that every other column, starting at base 1, is graphed along the major axis, and every other column, starting at base 2, is graphed along the minor axis. (Illustrator also generates an empty, ignored column 0 for scatter graphs.) The majorDataColumns and minorDataColumns elements are required for each graphDesc element in a template. The template must also include a majorAxis and minorAxis element outside of the graphDesc elements. Each contains a dataColumns element that lists all of the columns of data that can be used as major or minor data columns in the template. If a format element contains only one graphDesc element, the dataColumns element in the majorAxis is usually a duplicate of the majorDataColumns element in the graphDesc, and the dataColumns element in the minorAxis is usually a duplicate of the minorDataColumns element in the graphDesc. ADS graphing is much more flexible about column usage than Illustrator graphing. Assume the table of data in Figure 9.7 that includes the name of a contractor, the day of the week, and how many hours the contractor worked that day.

182 Dec 19, 2003 Adobe Document Server Developers Guide Major and Minor Data Columns Creating Dynamic Graphs in SVG Files Graphing Data Columns 9

FIGURE 9.7 Sample contractor data set

(Column 0) (Column 1) (Column 2) Contractor Day Hours Bob Mon 3 Bob Tue 4 Bob Thu 6 Carol Tue 7 Carol Wed 5 Carol Fri 3 Ted Tue 1 Ted Wed 4 Alice Fri 8

This data can be used to display a graph of contractors and distribution of hours worked by each contractor.

EXAMPLE 9.14 Graphing conflicting values separately This example uses the valueConflict attribute of the majorAxis element to demonstrate graphing multiple data points sharing the same value: 0 2 Note that the syntax omits any mention of column “1”, which means that column one will not be graphed. If valueConflict were “sum” instead of “separate”, the result would be the total hours that person worked that week; if it were “mean”, the result would be the average number of hours that person worked that week; if it were “count”, the result would be the number of days that person worked that week. You could use different templates for the same data set to create graphs based on the day of the week instead of on the person. The only difference in the template would be that the dataColumns entry for majorAxis would specify column “1” instead of column “0”. D i f f e r e n t values for the valueConflict attribute could produce graphs showing the average number of hours worked that day or the number of people who worked that day. To view an example, see “Graph with Conflicting Data” on page 204.

Adobe Document Server Developers Guide Dec 19, 2003 183 Creating Dynamic Graphs in SVG Files Major and Minor Data Columns 9 Sample Graph Format

Sample Graph Format

A complete graph element that creates a bar graph of attractions in Seattle and Minneapolis is shown in the following example:

EXAMPLE 9.15 A complete graph element for a bar graph Attraction Seattle Minneapolis key="name">coffee shops 1798 98 garage bands 500 1500 brew pubs 200 30 software companies 1000 50 baseball teams 1 0

0

184 Dec 19, 2003 Adobe Document Server Developers Guide Major and Minor Data Columns Creating Dynamic Graphs in SVG Files Sample Graph Format 9

%m:name %v 0 x y %p:name For further information on graphing XML grammar, including the DTD and namespace information for graphing, refer to the Adobe Document Server XML Grammars Reference.

Adobe Document Server Developers Guide Dec 19, 2003 185 Creating Dynamic Graphs in SVG Files The what and which Elements 9 Graph Transformations (Xforms)

Graph Transformations (Xforms)

Basic graphs in ADS are rather plain by default. You can enliven graphs considerably by applying style changes to the result. These changes are called graph transformations, or xforms. Xforms are included in the xforms child element of the format element. The xforms element contains a series of child xform elements, each of which describes a single change. ADS applies each xform to the graph in the order listed in the xforms element. An xform element consists of two parts: ● A description of the graph component being changed (a what element) ● A description of the change (a change element; see “The Change Element” on page 188 for a list) Illustrator generates xform elements to reflect any changes a user makes to a graph after its creation. For full details on xforms, see the Adobe Document Server XML Grammars Reference.

The what and which Elements The what element has an attribute xformBase that describes the component being changed. Values for the xformBase attribute include: ● everything, which changes the entire graph ● axis, which changes an axis along with its labels and ticks ● legendText, which changes the text associated with a legend ● point, which changes point markers in the graph or legend A what element can contain various which elements that restrict the objects being changed. There are four different which elements: whichSeries, whichPoint, whichAxis, and whichAxisSubpart. Different which elements apply, depending upon the value of the xformBase attribute. A missing which element makes the change apply to all objects that match the xformBase attribute and any other which elements that are present. Here are some example what elements that change point markers in a graph:

EXAMPLE 9.16 Changing point markers with the what element 2 1

186 Dec 19, 2003 Adobe Document Server Developers Guide The what and which Elements Creating Dynamic Graphs in SVG Files Graph Transformations (Xforms) 9

EXAMPLE 9.17 Changing all point markers for the second series 2

EXAMPLE 9.18 Changing point markers for the first cluster 1

EXAMPLE 9.19 Changing all point markers

EXAMPLE 9.20 Set operations on what elements If a what element does not have an xformBase attribute, it must contain a union, intersection, or difference element. These contain a series of what elements, and perform a set operation on the elements. The set operation refers to elementary math set operations and is not to be confused with the set command. Here are some sample what elements with set operations:

188 Dec 19, 2003 Adobe Document Server Developers Guide Graph Designs and the symbol Element Creating Dynamic Graphs in SVG Files String Substitutions 9

EXAMPLE 9.21 A symbol definition for a graph design The following example shows a symbol definition for a graph design. It represents a 100x100 unit red box that contains the value being graphed as a text string, followed by a percent sign. This assumes that “graph” is the XML prefix for the graphing namespace: %

String Substitutions

You can substitute strings in axis and legend labels. The syntax for string substitutions begins with a percent sign (%). Graph templates normally include several elements that specify strings appearing in a graph. The two graph elements where strings occur are the: ● legendString element in a graphDesc element. ● labelString element in an axis element. The values specified in these elements can use substitutions to change the resulting string within a graph.

EXAMPLE 9.22 Basic string substitution As an example, the labelString element shown below makes the labels along an axis be the value at the label followed by a space and the string “cm”: %v cm Indicating a Global vs. Specific Property A global property is indicated with an uppercase “P”. A property that applies a unique value for each specific column is indicated with a lowercase “p”.

EXAMPLE 9.23 String substitution with a global units property The graph data section described how to define maps and properties as part of the graph data. You can include these maps and properties in legend and label strings through appropriate string substitutions. If a graph data set includes a global property named “units”, t h e labelString element shown below makes the labels along an axis assume the value at the label followed by a space and the value of the units global property: %v %P:units

EXAMPLE 9.24 Column-specific substitution of a units property If a propertyRow element in a data set provides a units property for each column of the data, the units property can be used by a column-specific substitution: %v %p:units

Adobe Document Server Developers Guide Dec 19, 2003 189 Creating Dynamic Graphs in SVG Files Graph Designs and the symbol Element 9 String Substitutions

EXAMPLE 9.25 Map string substitution Data columns used on a major axis usually have maps, and there are substitutions that take values from these maps. If a data column includes a map called “name”, t h e labelString element shown below makes each label along an axis be the map entry that corresponds to the value at that label: %m:name For instance, a map entry of “Monday” would be placed at the appropriate label instead of the original data column label of “1”. Name Termination The name that follows a property or map substitution is terminated by any of the following: ● A space; ● Another percent sign; ● The end of the string. Specifying Alternative Property Names for a Substitution Property and map substitutions can contain a series of question-mark separated property names. This means to use the first of the properties that is actually defined in the data set. For example, “%p:legendName?name” in a legend label means to use the legendName property if it exists, otherwise, use the name property. The following table lists and describes the string substitutions allowed in graphing XML:

TABLE 9.1 Allowed string substitutions

String substitution Description

%v A numeric value displayed in a default format. This is only useful in an axis labelString element. In a legendString element, it evaluates to an empty string. Example usage: %v%p:units The example represents the actual value followed by the units property.

%P Represents the value of a global property in the data set. The %P is followed by a colon and the name of the property. Example usage: %v %P:units

%M Represents the value of a global map in the data set. The %M is followed by a colon and the name of the map. This is only useful in an axis labelString element, and the index into the map is the value of the axis at that point. In a legendString element, it evaluates to an empty string. Example usage: %M:grade

190 Dec 19, 2003 Adobe Document Server Developers Guide Graph Designs and the symbol Element Creating Dynamic Graphs in SVG Files String Substitutions 9

TABLE 9.1 Allowed string substitutions (Continued)

String substitution Description

%p Represents the value of a column-specific property in the data set. The %p is followed by a colon and the name of the property. Example usage: %p:name

%m Represents the value of a column-specific map from the data set. The %m is followed by a colon and the name of the property. This is only useful in an axis labelString element, and the index into the map is the value of the axis at that point. In a legendString element, it evaluates to an empty string. Example usage: %m:name

%n Represents a null substitution. You can use this substitution to terminate a substitution with a name and immediately follow it with other text. Example usage: %p:name%ndata This evaluates to the name attribute, immediately followed by the string “data” with no intervening spaces.

%% Represents a percent sign. You can use this to add a percent sign to a value or label. Example usage: %v%% This evaluates to the value followed by a percent sign.

Map Substitutions Map substitutions (%M and %m) are only useful in labelString elements, and the value along the axis is used as an index into the map. If the map does not include the index value, a special rule applies that the entire string being substituted into does not appear. For example, if the name map maps integers to days of the week, the substituted value for “%m:name morning” would be “Monday morning” for an axis label at the value “2”, and the null string for an axis label at the value “2.5”.

Adobe Document Server Developers Guide Dec 19, 2003 191 Creating Dynamic Graphs in SVG Files SVG Template 9 Strict and Lenient Graphing Modes

Strict and Lenient Graphing Modes

You can set graphing to run in either strict or lenient mode. The modes are intertwined with the ADS errorBehavior attribute, which you can specify either on the command line, on the opening commands tag, or in the API. For more information about command line use, see the Adobe Document Server API Reference. For more information about attributes on the commands tag, see the Adobe Document Server XML Grammars Reference. The default errorBehavior for ADS is to stop processing a request when an error occurs. Strict mode enforces that all necessary graphing element and attribute values have been supplied and treats any missing or erroneous values as errors. Lenient mode enables the graphing library to substitute default values for any missing or erroneous values. Strict mode checks for certain directives to ignore. For example, the tick and label positioning attributes are only relevant if the ticksAndLabels attribute is set to “explicit”. In strict mode, you receive an error if you specify the individual tick and label attributes but do not correctly specify the ticksAndLabels attribute as “explicit”. Va l i d v a l u e s f o r t h e tickLength attribute are “short”, “ long”, o r a n u m b e r. I f tickLength is erroneously specified as “logn”, the graphing library generates an error in strict mode, and uses the default value, “short”, in lenient mode. For further information on the ticksAndLabels attribute, refer to the Adobe Document Server XML Grammars Reference. Use strict mode when testing graphing templates. You might want to consider using lenient mode in a production system.

Graph and XML Examples

This section gives example of graphs and the XML that produced the graphs.

SVG Template The following is a minimum SVG template that may be used with the following examples. In each case, insert the example switch element at the location of the comment that says: In this template, the graph data is identified as Variable1, the Illustrator default name. You may change that if you prefer.

NOTE: This template does not support all ADS features — definitions of namespaces not needed in these examples have been omitted. These omitted namespaces include support for image replacement and text flows. The sample SVG file shown in Figure 9.1 has a larger header that includes these namespaces.

192 Dec 19, 2003 Adobe Document Server Developers Guide SVG Template Creating Dynamic Graphs in SVG Files Graph and XML Examples 9

EXAMPLE 9.26 SVG template for samples ]> ADS interprets the SVG foreign object and renders the graph when it loads the SVG file. To generate an SVG file with the graph rendered, you only need to load the file and save it. The commands in the following example accomplish this.

EXAMPLE 9.27 XML load and save With the above commands in the file loadsave.xml, the following command will render your SVG image. altercast -commands loadsave.xml

Adobe Document Server Developers Guide Dec 19, 2003 193 Creating Dynamic Graphs in SVG Files Polar Pie Graph 9 Graph and XML Examples

Polar Pie Graph Figure 9.8 and Example 9.28 show a polar pie graph. The axisLayout attribute of the format element makes the graph layout polar instead of cartesian. The direction attributes of the majorAxis and minorAxis elements make the major axis follow the circumference and the minor axis along the radius. The example also includes xform elements that change the fill colors of the three series into yellow, red, and blue.

FIGURE 9.8 Polar pie graph Fresno Lemon

Cherry

Oxnard Milpitas Blueberry

Bakersfield Yreka

EXAMPLE 9.28 XML code for a pie graph Blueberry Cherry Lemon Fresno 5 3 2

194 Dec 19, 2003 Adobe Document Server Developers Guide Polar Pie Graph Creating Dynamic Graphs in SVG Files Graph and XML Examples 9

Milpitas 3 4 4 Yreka 3 3 2 Bakersfield 1 3 5 Oxnard 4 2 4

0 %m:name

Adobe Document Server Developers Guide Dec 19, 2003 195 Creating Dynamic Graphs in SVG Files Polar Pie Graph 9 Graph and XML Examples

%p:name 0 labels 2 1 0

196 Dec 19, 2003 Adobe Document Server Developers Guide Accumulation and Multiple Graph Descriptions Creating Dynamic Graphs in SVG Files Graph and XML Examples 9

Accumulation and Multiple Graph Descriptions Figure 9.9 and Example 9.29 show a graph that includes multiple graphDesc elements, one of which uses accumulation. The order attributes on the two graphDesc elements places the filled, accumulated graph behind the stroked, non-accumulated graph. Note that the labelString element in the value axis element uses the substitution “%P:units” to make the units property defined in the data element appear in the labels.

FIGURE 9.9 Multiple graph description, accumulation, and substitution

10 inches Snowfall

8 inches (cumulative)

6 inches

4 inches

2 inches

0 inches Sun Mon Tue Wed Thu Fri Sat

EXAMPLE 9.29 XML code for the multiple graph figure Snowfall inches Sun 1 Mon 2

Adobe Document Server Developers Guide Dec 19, 2003 197 Creating Dynamic Graphs in SVG Files Accumulation and Multiple Graph Descriptions 9 Graph and XML Examples

Tue 1.5 Wed 1.25 Thu .5 Fri 1.5 Sat 1

0 %m:name %v %P:units

198 Dec 19, 2003 Adobe Document Server Developers Guide Accumulation and Multiple Graph Descriptions Creating Dynamic Graphs in SVG Files Graph and XML Examples 9

%p:name 0 category value (cumulative) 0 value

Adobe Document Server Developers Guide Dec 19, 2003 199 Creating Dynamic Graphs in SVG Files Applying a New Data Element 9 Graph and XML Examples

Applying a New Data Element Figure 9.10 shows the result of substituting in a different data element, shown in Example 9.30. The format element remains exactly the same. Note that there are a different number of points along the major axis, the range of the minor axis has changed to accommodate the new data, and a different unit string has been substituted into the axis labels.

FIGURE 9.10 Applying a new data element

8 feet Snowfall 7 feet (cumulative) 6 feet 5 feet 4 feet 3 feet 2 feet 1 feet 0 feet Nov Dec Jan Feb Mar

EXAMPLE 9.30 XML code for the new data element figure Snowfall feet Nov .7 Dec 1.6 Jan 2.8 Feb 1.4

200 Dec 19, 2003 Adobe Document Server Developers Guide String-Labelled Minor Axis Creating Dynamic Graphs in SVG Files Graph and XML Examples 9

Mar .5

String-Labelled Minor Axis Figure 9.11 and Example 9.31 show the grade example described earlier in this chapter. Note that the labelString element in the value axis element uses the substitution “%M:grade” to show the labels along the minor axis as letter grades instead of numbers.

FIGURE 9.11 Minor axis with string labels

A Final

Exam 2 B Exam 1

C

D

F Larry Curly Moe

EXAMPLE 9.31 XML code for the minor axis with string labels figure Exam 1 Exam 2

Adobe Document Server Developers Guide Dec 19, 2003 201 Creating Dynamic Graphs in SVG Files String-Labelled Minor Axis 9 Graph and XML Examples

Final A B C D F Larry B A B Curly A A B Moe C B 3.5

0 %m:name

202 Dec 19, 2003 Adobe Document Server Developers Guide String-Labelled Minor Axis Creating Dynamic Graphs in SVG Files Graph and XML Examples 9

%M:grade %p:name 0 category value

Adobe Document Server Developers Guide Dec 19, 2003 203 Creating Dynamic Graphs in SVG Files Graph with Conflicting Data 9 Graph and XML Examples

Graph with Conflicting Data Figure 9.12 and Example 9.32 show the contractor hours example described earlier in the chapter. The valueConflict="separate" attribute on the majorAxis element causes the conflicting data points to be graphed separately.

FIGURE 9.12 Graphing conflicting data points separately

8

7

6

5 4 3 2 1 0 Bob Carol Ted Alice

EXAMPLE 9.32 XML code for the conflicting data points figure

204 Dec 19, 2003 Adobe Document Server Developers Guide Graph with Conflicting Data Creating Dynamic Graphs in SVG Files Graph and XML Examples 9

Thu Fri 1 1 3 1 2 4 1 4 6 2 2 7 2 3 5 2 5 3 3 2 1 3 3 4 4 5 8

Adobe Document Server Developers Guide Dec 19, 2003 205 Creating Dynamic Graphs in SVG Files Graph with Conflicting Data 9 Graph and XML Examples

0 2 %m:name %v %p:name 0 2 horizontal vertical

206 Dec 19, 2003 Adobe Document Server Developers Guide Applying a New Format Creating Dynamic Graphs in SVG Files Graph and XML Examples 9

Applying a New Format Figure 9.13 shows the result of substituting in a different format element. The XML is shown in Example 9.33. The data element remains exactly the same. The new format element graphs the data as a bar graph, and the valueConflict="sum" attribute on the majorAxis element make the values graphed be the total of the conflicting values. Note that the range of the minor axis has changed to accommodate the different conflict resolution policy.

FIGURE 9.13 New graph format

15

12

9

6

3

0 Bob Carol Ted Alice

Adobe Document Server Developers Guide Dec 19, 2003 207 Creating Dynamic Graphs in SVG Files Applying a New Format 9 Graph and XML Examples

EXAMPLE 9.33 XML code for the new format element figure 0 2 %m:name %v 0 2 horizontal vertical

208 Dec 19, 2003 Adobe Document Server Developers Guide Graph Design Creating Dynamic Graphs in SVG Files Graph and XML Examples 9

Graph Design Figure 9.14 and Example 9.34 show a graph that uses a graph design on the point markers. The graph design is defined by the symbol named “shield” (its path data has been omitted for brevity). The symbol definition shows the fitBox and hasSubstitution attributes. Note the valueSubstitution element within the text element and how it has been replaced with the values being graphed in the resulting graph. The graph designs are applied by the first xform element, which says to apply the design to all the point objects in the graph. There are additional xform elements that change the fill color of the stroke objects to white, blue, and red.

NOTE: This example is the only graph example that can be created completely in Illustrator. All other examples in this section must have additional editing of the XML and require ADS functionality.

FIGURE 9.14 Interstate graph design

8 Motorcycles

6.5 Trucks 6

5.0 Cars 4.5 4.5 4.2 4 3.8 3.9 3.5

2.0 2 1.8 1.5 1.2

0 1998 1999 2000 2001

EXAMPLE 9.34 XML code for the Interstate Graph Design figure

Cars Trucks Motorcycles 1998 4.5 3.5 1.2 1999 3.8 4.5 1.5 2000 5 4.2 1.8 2001 6.5 3.9 2

210 Dec 19, 2003 Adobe Document Server Developers Guide Graph Design Creating Dynamic Graphs in SVG Files Graph and XML Examples 9

axisLayout="cartesian">

0 %m:name %v %p:name 0 labels category value

Adobe Document Server Developers Guide Dec 19, 2003 211 Creating Dynamic Graphs in SVG Files Graph Design 9 Graph and XML Examples

2 1 0

NOTE: Be careful when formatting the value substitution that you do not include any extra space or line breaks between and the surrounding > and <. If you did, that space would be treated as string content of the text element.

212 Dec 19, 2003 Adobe Document Server Developers Guide Graph Design Creating Dynamic Graphs in SVG Files Graphing Template Guidelines 9

Graphing Template Guidelines

In addition to setting crop marks for graphing templates (described in “Using Crop Marks” on page 150), here are some additional tips when you create graph templates in Illustrator 10. ● Set crop marks to accommodate replacement graph data — If you replace data in a graph and the data set is larger than the original data set, it could extend the graph outside its original bounds. To make sure the graph has adequate white space or margins around it, set crop marks for the graph object in Illustrator. Draw a rectangle with the size and position of the largest area you expect, select the rectangle, and choose Object > Crop Marks > Make. ● Apply SVG filters with a named style — To apply an SVG filter, create a named style that contains the effect, and apply that named style to the graph or elements in the graph. (If you apply SVG filters directly through the Effects menu in Illustrator, without the filters being part of a named style, the effects do not appear in the template.) The named style can specify a single SVG filter, a fill, a stroke, and transparency settings. The fill and stroke can have their own optional transparency settings. ● Make sure that changes that you make to graph attributes directly in Illustrator are exported to SVG — You can change fill and stroke in a graph directly, without encapsulating the change in a style. When you change the appearance of a graph or an element in a graph, do not use multiple fills or strokes, or reorder the stroke to be above the fill. These types of changes do not appear in the template. Do not change the type attributes of text in a graph except to change the font and the size. Other changes, such as justification and kerning, do not appear in the template. Make sure that the entire graph is selected before you change the graph attributes through the Object > Graph > Type menu. Changes made when the entire graph is not selected (even if all of the graph’s data objects are selected) do not appear in the template. Illustrator 10 does not export mixed-type graph templates — for example, where one column is a bar graph and another column is a line graph — to SVG. Although ADS can create these by including multiple graphDesc elements in a single graph, you cannot use Illustrator to create mixed-type graph templates for ADS. ● Note that patterns and gradients may change — Graph designs that contain a pattern or gradient do not always appear exactly the same in ADS as in Illustrator. If a graph element has a pattern or gradient applied, and is then scaled, sheared, or rotated, the results in ADS may not always match the results in Illustrator. ● Be careful when altering SVG code directly — Illustrator 10 generates symbol definitions for any graph designs used in an SVG graph template. If you hand code graph design symbol elements for sliding graph design applications, you must specify all paths as path elements, avoiding SVG shape elements like rect and polygon. ADS has to be able to go in and look for paths in order to be able to modify them. Other elements may be misinterpreted and will not be scaled with the data. If you hand-code SVG files to implement XML features that are not supported by Illustrator, do not re-import those files into Illustrator. The XML is lost upon import.

Adobe Document Server Developers Guide Dec 19, 2003 213 Creating Dynamic Graphs in SVG Files Graph Design 9 Graphing Template Guidelines

214 Dec 19, 2003 Adobe Document Server Developers Guide Part IIIII

Documents

Adobe Document Server Developers Guide Dec 19, 2003 215 216 Dec 19, 2003 Adobe Document Server Developers Guide 10 Creating PDF Files from XSL-FO

This chapter describes how to create PDF documents from Extensible Stylesheet Language Formatting Objects (XSL-FO) content. XSL-FO is a mark-up language that consists of a rendering vocabulary of formatting information for paginated presentation. As you read this chapter, it is helpful if you are familiar with XML and XSL-FO. You can also refer to the XSL 1.0 W3C Recommendation available on the W3C site at http://www.w3.org/TR/2001/REC-xsl-20011015/. The chapter includes an overview of how Adobe Document Server formats XSL-FO content, with or without a FrameMaker template. It also describes some of the tasks that you will want to achieve as you develop your XSL-FO content for processing with ADS. An example is provided with each task to illustrate how ADS formats the XSL-FO content. You can also use the samples provided with the installation to learn how ADS formats XSL-FO content. There is a sample for all elements and most attributes in the /samples/XSL-FO directory. Each sample includes an XSL-FO file and corresponding ADS commands. Some samples also include the FrameMaker template used to format the XSL-FO content. You can run ADS to look at the resulting PDF document for each of the samples. This chapter contains the following sections:

Overview starting on page 217 Supported Elements and Attributes starting on page 218 Formatting With a FrameMaker Template starting on page 219 Formatting Without a FrameMaker Template starting on page 232 Common Formatting Tasks starting on page 239

Overview

You use the formatXSL command to format the data from the current XSL-FO content and produce a PDF document. You can further manipulate the resulting PDF document with other commands such as insertTOC and assemblePDF. For information on the ADS commands, see the Adobe Document Server Command Reference. You can format content from other schemas by first transforming it to an XSL-FO document. For example, you may have a repository of XML content that already has transformations in place to create XSL-FO content. If your data is in another schema such as HTML, you can use your preferred XSL Transformations (XSLT) tool to transform the data into XSL-FO. Any transformations must be accomplished before submitting the content to ADS. You can define master pages and page sequencing information either in the XSL-FO document or in a FrameMaker template. For details on formatting XSL-FO content without a FrameMaker template, see “Formatting Without a FrameMaker Template” on page 232.

Adobe Document Server Developers Guide Dec 19, 2003 217 Creating PDF Files from XSL-FO 10 Supported Elements and Attributes

When you provide a FrameMaker template, ADS ignores the master page definition in the XSL-FO document and formats the data based on the layout and formatting properties defined in the template. ADS extracts the content of the flow in the XSL-FO document and replaces the main text flow in the FrameMaker template. For details on using a FrameMaker template, see “Formatting With a FrameMaker Template” on page 219. ADS transfers any XMP metadata included in the XSL-FO document or FrameMaker template (if there is no metadata in the XSL-FO document) to the resulting PDF document. For more information on metadata, see “Specifying XMP Metadata” on page 242. The ADS installation includes the Acrobat Distiller® job options file, formatXSL.joboptions, which resides in the /required/Settings directory. The formatXSL command uses the default job option settings in this file when it creates a PDF document. You can modify the file, if required. Keep in mind that the formatXSL command ignores the image compression settings in the formatXSL.joboptions file. Instead, the formatXSL command embeds the graphics in the PDF document without altering their compression.

Supported Elements and Attributes

ADS supports a subset of the elements and attributes described in the XSL-FO 1.0 W3C Recommendation. There are areas where ADS differs from the implementation described in the XSL-FO W3C Recommendation. The list of supported elements and attributes as well as the implementation variations are described in the Adobe Document Server XML Grammars Reference. ADS also introduces a number of extensions to XSL-FO to add functionality not available with the standard XSL-FO elements and attributes. You can use the extended elements and attributes in your XSL-FO files together with a FrameMaker template to format the XSL-FO content. You must declare the XSL-FO elements and attributes in the XSL-FO document as part of the XSL-FO namespace: http://www.w3.org/1999/XSL/Format By convention, this document refers to XSL-FO elements using the XSL-FO namespace prefix "fo:". To take advantage of the additional formatting features available with the extended XSL-FO elements and attributes, you must declare these as part of the Adobe Extended Formatting namespace. This document identifies elements and attributes in the Adobe Extended Formatting namespace using the namespace prefix "ext-fo:", by convention. ADS 6.0 provides specific extended elements and attributes in support of multiple flows and complex layouts. These extended elements and attributes are identified in the “Multiple Flows and Complex Layouts” section of the Adobe Document Server XML Grammars Reference. Since ADS 6.0 adds new extended elements and attributes that were not part of the previous version, XSL-FO files containing these extended elements and attributes should use the Adobe Extended Formatting namespace identifier: http://ns.adobe.com/Extended-XSL-FO/20031030/

218 Dec 19, 2003 Adobe Document Server Developers Guide Identifying the Template Creating PDF Files from XSL-FO Formatting With a FrameMaker Template 10

If your XSL-FO file contains only ADS 5.0 extended elements and attributes, ADS honors the ADS 5.0 namespace identifier: http://ns.adobe.com/Extended-XSL-FO/20020116/ All extended elements and attributes in the previous version of ADS are allowed in the new namespace identifier.

Formatting With a FrameMaker Template

You may find it easier to define the master pages and formatting properties in FrameMaker instead of defining these in your XSL-FO documents. When you create a template in FrameMaker, you can define the page layout, master pages, paragraph format properties, and character format properties that ADS uses to process the XSL-FO content. Throughout this section, the content often refers to one of the installed samples, to illustrate the process of formatting XSL-FO documents with a FrameMaker template. The sample consists of these files: ● The command file “block_First.xml” in /samples/XSL-FO/templates/block ● The XSL-FO document “block.fo” in /samples/XSL-FO/templates/block ● The FrameMaker template file “First.fm” in /samples/XSL-FO/fmtemplates

Identifying the Template You identify the FrameMaker template that ADS uses to format the XSL-FO content by including the "template" attribute in the formatXSL command. The template can be either a native binary FrameMaker (.fm) file or a FrameMaker Interchange Format (.mif) file. Sample Command File “block_First.xml” The first loadContent command in the sample command file “block_First.xml” loads the FrameMaker template file “First.fm” and stores it as the named content holder “First”. The second loadContent command loads the XSL-FO file “block.fo”. The formatXSL command then formats the data into the template document and produces PDF content; during this step, the formatXSL command replaces the content of the main text flow in the template document with the content of the flow from the XSL-FO file “block.fo”. The new PDF content becomes current, and is saved to a new PDF file “block_First.pdf”.

Adobe Document Server Developers Guide Dec 19, 2003 219 Creating PDF Files from XSL-FO Identifying the Template 10 Formatting With a FrameMaker Template

Sample XSL-FO Document “block.fo” When you identify the FrameMaker template in the command file, ADS uses the page layout and master page information in the template. The fo:layout-master-set element and the master page selection rules in the fo:page-sequence element in the sample XSL-FO document are therefore ignored. This is a fragment of the sample XSL-FO document “block.fo“: ... The fo:flow element in the XSL-FO document holds the content and uses the flow-name attribute to identify the content flow. The most common flow-name in an XSL-FO document is "xsl-region-body", while the default flow tag in a FrameMaker template is “A”. The flow- name in the XSL-FO document must match the flow tag in the FrameMaker template. You can either change the flow-name in the XSL-FO document or the flow tag in the FrameMaker template so that they both match. Notice the flow-name attribute value "A" on the fo:flow element in the sample XSL-FO document “block.fo”. The value for this attribute matches the flow tag “A” in the sample FrameMaker template “First.fm” described on page 221.

NOTE: If you remove the fo:layout-master-set element and its contents, ADS produces an error unless you use the ext-fo:fragment-root element (which indicates an XSL-FO fragment file) instead of the fo:root element. For additional information, see “Using ext-fo:fragment-root” on page 231.

220 Dec 19, 2003 Adobe Document Server Developers Guide Defining the Master Pages Creating PDF Files from XSL-FO Formatting With a FrameMaker Template 10

Defining the Master Pages FrameMaker documents can contain different types of pages, including: ● Master pages that specify the page layout, the background graphics, and background text (for example, page headers and footers) for document pages. ● Body pages that show the background graphics and text from the corresponding master page, and contain the main text flow of the document which ADS replaces with the XSL-FO content during formatting. You can set-up your template as a double-sided document, which contains at least two default master pages: one for left pages and one for right pages. Or you can set-up your template as a single-sided document, which uses the default “Right” master page only. You can also create custom master pages, for example, for the first page in the document. For more information on creating FrameMaker templates, see the FrameMaker documentation. Sample FrameMaker Template “First.fm” The sample FrameMaker template “First.fm” is defined as follows: ● The page size uses portrait settings, with a width of 8.5 inches and height of 11 inches. ● The template is intended for double-sided documents and contains three master pages: “Right”, “Left”, and “First”. ● The “Right” and “Left” master pages are the default master pages for a double-sided document. The master page “First” is a custom master page that was applied to the body page in the template. The sample uses the master page “First” to format the first page of the document, then alternates between the default “Left” and “Right” master pages to format succeeding pages. ● A text flow is a series of connected text frames through which the text flows in a document. The three master pages contain template text frames that have the flow tag “A”, with the Autoconnect setting turned on. The master page “First” uses two template text frames that are connected and have the flow tag “A”: the first template text frame at the top of the page uses a single-column layout, while the second template text frame uses a two-column layout. ● The “Right” and “Left” master pages contain a single template text frame connected to the flow tag “A” and use a two-column layout. Both master pages also contain background text frames at the top and bottom of the page. Unlike template text frames, background text frames do not have a flow tag. The “Running H/F1” and “Running H/F2” system variables in these background text frames enable the display of running headers and footers in the header and footer region. The “Current Page #” system variable displays the page number in the footer region. ● The master pages also contain background graphics (company logo, horizontal lines, and the word “DRAFT”). ● The body page is the page on which the content is output during the creation of the PDF document.

Adobe Document Server Developers Guide Dec 19, 2003 221 Creating PDF Files from XSL-FO Defining Formats 10 Formatting With a FrameMaker Template

Defining Formats When you create your master pages in a FrameMaker template, you also define the paragraph and character format properties in the Paragraph Designer and Character Designer. You then apply the same paragraph and character formats to elements in your XSL-FO document. To do this, you use the ext-fo:apply-property-set attribute. The attribute value is case-sensitive and corresponds to a paragraph tag or character tag in the FrameMaker Paragraph or Character Catalog. ADS then uses the format properties in the appropriate FrameMaker catalog to format the XSL-FO content.

NOTE: You cannot use the ext-fo:apply-property-set attribute to extract the table format properties from the FrameMaker Table Catalog. This attribute applies only to paragraph and character format properties. When you specify a FrameMaker template to format XSL-FO content, you define the table format properties in the XSL-FO document. Applying the Formats to the XSL-FO Content The sample XSL-FO document “block.fo” uses the ext-fo:apply-property-set attribute to apply paragraph and character formats to XSL-FO elements (only a few elements are shown): Title of the Document This is a block. First Level Subtitle This is a block. Second Level Subtitle This is a block. ... ● For each fo:block element, the ext-fo:apply-property-set attribute value must match the name of a paragraph tag in the FrameMaker Paragraph Catalog. For example, the first fo:block element contains the attribute value "Title", which corresponds to the paragraph tag “Title” in the FrameMaker Paragraph Catalog. ● For each fo:inline element, the ext-fo:apply-property-set attribute value must match the name of a character tag in the FrameMaker Character Catalog. For example, the fo:inline element contains the attribute value "Emphasis", which corresponds to the character tag “Emphasis” in the FrameMaker Character Catalog. You can open the FrameMaker template “First.fm” for this sample, to look at the paragraph and character formats defined in the Paragraph Catalog and Character Catalog. When formatting the XSL-FO document, ADS applies the paragraph or character format properties from the corresponding FrameMaker catalog to the text of each element that contains the ext-fo:apply-property-set attribute.

222 Dec 19, 2003 Adobe Document Server Developers Guide Formatting the XSL-FO Content Creating PDF Files from XSL-FO Formatting With a FrameMaker Template 10

Overriding FrameMaker Character Formats An XSL-FO document may contain inline formatting attributes such as "bold" and "italics". This example uses the font-style attribute on a fo:inline element instead of the ext-fo:apply-property-set attribute. ADS italicizes the text “inline” based on the font-style specified in the XSL-FO content. Here is an inline element on page .

Formatting the XSL-FO Content In the sample XSL-FO document “block.fo” shown on page 220, the flow-name attribute value “A” f o r t h e fo:flow element corresponds to the flow tag “A” in the FrameMaker template “First.fm”. When formatting begins, ADS replaces the content in the flow tag “A” on the body pages of the FrameMaker template with the content of the fo:flow element. The body pages together with the content length of the fo:flow element determine which master page to use to format each page in the document. ADS also retains any background text and graphics inserted on the master pages in the FrameMaker template. By default, the FrameMaker pagination property “Delete Empty Pages” is set. During formatting, if the FrameMaker template contains more body pages than required to format the content, extra body pages are removed provided that: ● The extra body pages use the “Left” or “Right” master page, and ● There are no layout overrides in the template. If the content exceeds the space available in existing body pages in the template, during formatting, ADS appends new pages to the document, as necessary. For a double-sided document, new pages are selected alternately from the “Left” and “Right” master pages. For single-sided documents, only the “Right” master page is used. When using a single-sided FrameMaker template, the XSL-FO options to break to the next odd or even page are treated as breaking to the next page, whether odd or even.

NOTE: A FrameMaker template may contain more than one text flow to create multiflow documents, however, the content from the XSL-FO document may only replace one text flow in the template.

Adobe Document Server Developers Guide Dec 19, 2003 223 Creating PDF Files from XSL-FO Verifying the Formatting Results 10 Formatting With a FrameMaker Template

Verifying the Formatting Results You can run ADS from the command line to see the formatting results for the sample you looked at throughout this section. To do this: 1. Go to the directory that contains the sample command file “block_First.xml”: /samples/XSL-FO/templates/block 2. At the command prompt, type the following: altercast -commands block_First.xml ADS formats the XSL-FO content based on the FrameMaker template and outputs the PDF document in the same directory as the command file. 3. Open the PDF document to view the formatting results. The PDF document contains two pages: – The first page uses the custom master page “First” from the FrameMaker template. – The second page uses the “Left” master page from the FrameMaker template. The “Right” master page is not used because there is not enough content in the sample XSL-FO document to output a third page. Notice that the title of the document and other contents appear at the top of the first page in the PDF document. This is because the two template text frames on the master page “First” are connected and have the flow tag “A” in the FrameMaker template. The output also displays the text in the body region in two columns, as specified on each master page in the FrameMaker template. The second page of the PDF document contains a header and a footer. The headings in the header and footer regions correspond to the running header and footer system variables “Running H/F2” and “Running H/F1” on the “Left” master page. These variables were inserted in background text frames on the master page. The page number in the footer region corresponds to the system variable “Current Page #” defined in a background text frame on that same master page. ADS retains any content in background text frames defined in the FrameMaker master pages. Also notice the company logo, horizontal pages, and the word “DRAFT” in the PDF document. These correspond to the background graphics contained in the master pages of the FrameMaker template. ADS retains any background graphics defined in the FrameMaker master pages.

224 Dec 19, 2003 Adobe Document Server Developers Guide Creating a Table of Contents Creating PDF Files from XSL-FO Formatting With a FrameMaker Template 10

Creating a Table of Contents When you specify a FrameMaker template to format XSL-FO content, you can use other ADS commands such as insertTOC in addition to the formatXSL command to create a table of contents for any of your XSL-FO documents. There is a sample provided with the installation that demonstrates how to insert a title page and table of contents into the resulting PDF document. The sample consists of these files: ● The command file “insertTOC.xml” in /samples/XSL-FO/tasks/insertTOC ● The XSL-FO documents “block.fo” and “title.fo” in /samples/XSL-FO/tasks/insertTOC ● The FrameMaker template files “Title.fm”, “SampleTOC.fm”, and “DoubleSided.fm” in /samples/XSL-FO/fmtemplates Templates for Title Page and TOC Sample The sample uses three FrameMaker templates to produce the PDF document: ● The template, “Title.fm”, has a double-sided layout and uses a lowercase roman page numbering format in the footer region. The formatXSL command uses this template to format the title page and copyright page content from the XSL-FO document “title.fo”. The assemblePDF command in the command file uses this template to insert a title page and copyright page in the PDF document.

NOTE: The title page template also includes a graphic imported by copy. For details on using graphics with FrameMaker master pages, see “Importing Graphics” on page 230. ● The template, “SampleTOC.fm”, contains the three master pages: “First”, “Left”, and “Right”. The insertTOC command in the command file uses these master pages to create the table of contents. The template uses a lowercase roman page numbering format in the footer region, which starts at page iii on the “Right” master page. This is because there is also a title page and copyright page to insert before the table of contents in the resulting PDF document. The insertTOC command recognizes the paragraph formats “TOC-###” as table of contents entries. The “###” is the nesting level of entries, which starts at “TOC-001” for the top level entries, “TOC-002” for the next level, and increments by one for successive levels. For the TOC sample, the FrameMaker Paragraph Catalog contains different paragraph formats, including “TOC-001” and “TOC-002”. The insertTOC command uses these two paragraph formats to format the first and second level headings in the table of contents. The tab stop definition for these paragraph formats outputs a series of leaders between the headings and page numbers in the resulting PDF document. ● The template, “DoubleSided.fm”, is for double-sided documents and also contains the three master pages: “First”, “Left”, and “Right”. It is similar to the template “First.fm” described in the previous example on page 221. The formatXSL command in the command file uses the “DoubleSided.fm” template to format the XSL-FO content from the XSL-FO document “block.fo” and place the content onto the body pages of the PDF document.

Adobe Document Server Developers Guide Dec 19, 2003 225 Creating PDF Files from XSL-FO Creating a Table of Contents 10 Formatting With a FrameMaker Template

XSL-FO Documents for Title Page and TOC Sample The title page and TOC sample uses two XSL-FO documents: ● “block.fo” which is the main content of the document ● “title.fo” which contains the title page and copyright information The sample XSL-FO document “block.fo” is similar to the one described in the previous example on page 222. It uses the ext-fo:apply-property-set attribute to apply paragraph format properties from the FrameMaker Paragraph Catalog to text in the resulting PDF document. This is a fragment of that sample file: Title of the Document This is a block. First Level Subtitle This is a block. Second Level Subtitle This is a block. ... This is a fragment of the sample file “title.fo”, which contains the title page and copyright information. It also uses the ext-fo:apply-property-set attribute to apply paragraph format properties from the FrameMaker Paragraph Catalog to the text that appears on the title and copyright pages in the PDF document: Blocks and XSLFO An easy to use guide to Blocks and XSLFO Add copyright information here. Copyrights and trademarks are listed for each product mentioned in this document.

226 Dec 19, 2003 Adobe Document Server Developers Guide Creating a Table of Contents Creating PDF Files from XSL-FO Formatting With a FrameMaker Template 10

Command File for Title Page and TOC Sample The sample command file “insertTOC.xml” contains several PDF manipulation commands to output the resulting PDF document: The command file assembles the PDF document as follows: ● The first series of commands produce the main PDF content “block_pdf”, which contains the result of formatting the XSL-FO content from the XSL-FO document “block.fo”. ● The second series of commands produce the title page and copyright page PDF content, “title_pdf”, which contains the result of formatting the XSL-FO content from the XSL-FO document “title.fo”. ● The third series of commands produce the PDF content “assembled_pdf”, which includes the content of “title_pdf” and “block_pdf”. ● The last series of commands generate the table of contents after the copyright page in the PDF content “assembled_pdf”. The resulting PDF document that contains the title page, copyright page, table of contents, and the main content is saved as “insertTOC.pdf”. To view the resulting PDF document, you can run the sample from the command line. See “Verifying the Formatting Results” on page 224 for instructions on doing this. For more information on the commands such as assemblePDF and insertTOC, see the Adobe Document Server Command Reference.

Adobe Document Server Developers Guide Dec 19, 2003 227 Creating PDF Files from XSL-FO Creating Tagged PDF Documents 10 Formatting With a FrameMaker Template

Creating Tagged PDF Documents When you use FrameMaker templates to format XSL-FO content, you can create tagged PDF documents from XSL-FO files. Tagged PDF lets you create PDF documents from FrameMaker with logical document structure and extensive metadata for repurposing content. Logical structure refers to the organization of the document, such as the title page, chapters, sections, and subsections. The logical structure can indicate the precise reading order and improve navigation, particularly for longer, more complex documents. Since the formatXSL command uses the FrameMaker tagged PDF generation functionality, a number of conditions must be met in preparing the XSL-FO content and templates: 1. You must use a FrameMaker template to format the XSL-FO content. You identify the FrameMaker template that ADS uses to format the XSL-FO content by including the "template" attribute in the formatXSL command. For instructions on defining the "template" attribute, see “Identifying the Template” on page 219. 2. In your FrameMaker template, define the paragraph formats in the Paragraph Designer. You must then apply the same paragraph formats to elements in your XSL-FO file. To do this, you use the ext-fo:apply-property-set attribute. For instructions on defining formats and using the ext-fo:apply-property-set attribute, see “Defining Formats” on page 222. 3. In the FrameMaker template, make sure that you select the Generate Tagged PDF option. To select this option: –Choose Format > Document > PDF Setup – In the PDF Setup dialog box, choose Tabs from the pop-up menu (UNIX) or click the Tags tab (Windows). –Select the Generate Tagged PDF option. – Set up the paragraph structure level. –Click Set. See the FrameMaker online help for more information on setting up tagged PDF documents. When it formats the XSL-FO content, ADS uses the format properties from the appropriate catalog and the options in the PDF Setup dialog box to produce the tagged PDF document. Example There is a sample provided with the installation that demonstrates how to create tagged PDF documents. The sample consists of these files: ● The command file “block_TaggedPDF.xml” in /samples/XSL-FO/templates/block ● The XSL-FO document “block.fo” in /samples/XSL-FO/templates/block ● The FrameMaker template file “TaggedPDF.fm” in /samples/XSL-FO/fmtemplates

228 Dec 19, 2003 Adobe Document Server Developers Guide Creating Running Headers and Footers Creating PDF Files from XSL-FO Formatting With a FrameMaker Template 10

Creating Running Headers and Footers You can use markers in an XSL-FO document to mark text in the content of a body region that you want to appear in a different region of a document. For example, you can use a marker to create a running header to insert the document’s title from the body region in the header or footer region of a page. To do this, in the XSL-FO file, you use the fo:marker element and the marker-class-name attribute to mark the text below the fo:flow element that you want to appear in the header or footer region of the document. In the FrameMaker template, you then insert either of the following two system variables in background text frames in the header or footer on the appropriate master page: ● “Running H/F 3” (whose default variable definition <$marker1> corresponds to the marker-class-name attribute value "header-1") ● “Running H/F 4” (whose default variable definition <$marker2> corresponds to the marker-class-name attribute value "header-2") These variables will extract the text out of markers whose marker-class-name is "header-1" and "header-2" respectively.

NOTE: It is not necessary to use a fo:retrieve-marker element since this element can only appear in static-content and all static-content is ignored when a FrameMaker template is provided.

EXAMPLE 10.1 Running headers and footers with a FrameMaker template This example demonstrates the use of the fo:marker element to insert running headers and footers in the header and footer region of the page. The text “Heading 1” and “Heading 2” will appear in the header or footer region because the FrameMaker template uses the corresponding “Running H/F3” and “Running H/F4” system variables. Heading 1 Heading 2

Adobe Document Server Developers Guide Dec 19, 2003 229 Creating PDF Files from XSL-FO Development Considerations 10 Formatting With a FrameMaker Template

Development Considerations This section describes certain items that you should be aware of when you create a FrameMaker template that ADS uses to format XSL-FO content. Importing Graphics It is recommended that you import graphics by copy instead of by reference in your FrameMaker template. When you import a graphic by copy with File > Import > File, then select the Copy Into Document option, the graphic is embedded in the FrameMaker template. If a FrameMaker template contains graphics that are imported by reference, the file location information must be an absolute pathname, and the pathname must be on the server where the ADS process is running. In FrameMaker, when you import a graphic by reference with File > Import > File, then select the Import By Reference option, the pathname to the graphic can be either absolute or relative. A relative pathname begins at a current folder or one folder up the hierarchy and specifies the graphic file’s location from there. An absolute pathname begins at the root of the file system and fully specifies the graphic file’s location from there. For example, the FrameMaker template is located in the directory c:\work\templates (on Windows) or /usr/work/templates (on UNIX®). If the graphic that you want to import by reference is in c:\graphics (on Windows) or /usr/graphics (on UNIX), the pathname is absolute. If the graphic is located in c:\work\pictures (on Windows) or /usr/work/pictures (on UNIX), the path is relative. You can verify the pathname for a selected graphic with Graphics > Object Properties. Using Graphic Insets When you place a graphic directly on a page or in an unanchored frame in FrameMaker, the text can follow the contours of the graphic, or it can align vertically at the edge of an imaginary box bounding the graphic. By default, FrameMaker sets the runaround property to “Run around Contour.” For best performance, it is recommended that you avoid using the “Run around Contour” property unless needed. You can change the runaround property to “Run around Bounding Box”, “Don’t Run Around”, or “As Is” for the selected graphic with Graphics > Runaround Properties. Converting Colors XSL-FO only supports specifying colors in RGB with the sRGB color profile. FrameMaker natively represents colors in CMYK. It uses a transformation to produce CMYK values when RGB values are provided. By default, the formatXSL command produces PDF documents that use the RGB color representations for text and line art. To use CMYK colors in the PDF document, you can change the color conversion setting in the Acrobat Distiller PDF formatXSL.joboptions file provided with ADS. This job options file resides in /required/Settings, below the ADS installation directory.

230 Dec 19, 2003 Adobe Document Server Developers Guide Development Considerations Creating PDF Files from XSL-FO Formatting With a FrameMaker Template 10

Changing Color Conversion Setting in Job Options File To change the color conversion setting in the Acrobat Distiller PDF formatXSL.joboptions file: 1. Locate the formatXSL.joboptions file, in the /required/Settings directory below the ADS installation directory. 2. Open the job options file in a text editor. 3. Locate the color conversion parameter /FMForcePDFColorSpace. The default setting for this parameter is /UseRGB. 4. To force the use of CMYK colors, change the setting /UseRGB to /UseCMYK. 5. To control the color space from a FrameMaker (.mif) template, you can delete the line /FMForcePDFColorSpace /UseRGB def. This allows the MIF statement in a .mif template to control the colorspace used in the PDF document. Using ext-fo:fragment-root If you do not want to specify the fo:layout-master-set and fo:page-sequence elements in the XSL-FO file, you must use the ext-fo:fragment-root element as the root node instead of the fo:root element. This is useful when you define the master pages in a FrameMaker template. Keep in mind that if you plan to use the same XSL-FO file with a formatter other than ADS, the other formatter will not be able to process the XSL-FO content because it will not recognize the ext-fo:fragment-root element or any of the other extended XSL-FO elements.

EXAMPLE 10.2 Using ext-fo:fragment-root This is an example of an XSL-FO fragment file that uses the ext-fo:fragment-root element and produces the text “Hello, world!”: Hello, world!

Adobe Document Server Developers Guide Dec 19, 2003 231 Creating PDF Files from XSL-FO Defining the Master Pages 10 Formatting Without a FrameMaker Template

Formatting Without a FrameMaker Template

This section provides examples of formatting XSL-FO documents without a FrameMaker template.

Defining the Master Pages When you do not specify a FrameMaker template, ADS formats the XSL-FO content based on the master page definition and formatting properties specified in the XSL-FO data. This processing is basically similar to that of using XSL-FO with other XSL-FO to PDF processors, with the exception that the ext-fo extensions are not available in those processors.

EXAMPLE 10.3 Command file without a FrameMaker template This example first loads the XSL-FO file “hello.fo”. The formatXSL command then formats the XSL-FO data and produces PDF content. The PDF content is saved to a new PDF file.

EXAMPLE 10.4 Basic XSL-FO document with a single page master This example contains a fo:layout-master-set and fo:page-sequence element. The fo:simple-page-master element describes the master page on which to place the content. In this example, there is one master page named "letter", with a page size of 8.5 x 11 inches. The fo:page-sequence element has a master-reference attribute that references the master page. The fo:flow element holds the content that ADS places on that master page. The text “Hello, world!” is output in the body region of the resulting PDF document. Hello, world!

NOTE: Within a given XSL-FO file, ADS supports only a single fo:page-sequence element.

232 Dec 19, 2003 Adobe Document Server Developers Guide Defining the Master Pages Creating PDF Files from XSL-FO Formatting Without a FrameMaker Template 10

EXAMPLE 10.5 XSL-FO document with different regions In this example, the master page layout includes margins and different regions: before, after, and body. The before region is the header and the after region is the footer. The fo:region-before and fo:region-after elements have an extent attribute that defines the height of the header and footer region. The space-before and space-after attributes set the top and bottom margins of the body region. The fo:flow element holds the content that ADS places on the master page. The fo:static-content elements contain the text that will appear in the header and footer regions on each page in the PDF document. The flow-name attribute identifies the region in which to place the text. In this example, the text “region-before” is centered in the header region, and the text “region-after” is centered in the footer region. The text for both fo:block elements under the fo:flow element is output in the body region of the PDF document. region-before region-after This is the first block. This is the second block.

Adobe Document Server Developers Guide Dec 19, 2003 233 Creating PDF Files from XSL-FO Formatting Text 10 Formatting Without a FrameMaker Template

Formatting Text You can specify a number of attributes in your XSL-FO document to format the text in the resulting PDF document. Some attributes apply to entire paragraphs, while others apply to a portion of the text within a paragraph. This XSL-FO fragment uses several attributes to format the text: This is a block with a font-size=20pt and color=red and more text. This is a block with a font-style=italic and text-decoration.overline=true and more text. This is a block with a font-weight=bold baseline-shift=3pt and more text. This is a block with a font-stretch-ratio of "0.5". This is the last block with a font-stretch-ratio of "3.5" in this document. The attributes to format the text are: ● font-family: This attribute applies the font family “Minion Pro” to all fo:block elements below the fo:flow element. ● font-size and color: These attributes on the first fo:inline element set the font size to 20pt and the color of the text to red within the first fo:block element. ● font-style and text-decoration.overline: The second fo:inline element uses these attributes to italicize and draw a line over the text. ● font-weight and baseline-shift: The third fo:inline element uses these attributes so that the text appears in bold and superscript. ● ext-fo:font-stretch-ratio: This attribute on the fourth fo:block element condenses the font size to 50% of the normal font size, while the one on the last fo:inline element stretches the font size to 350% of the normal font size.

234 Dec 19, 2003 Adobe Document Server Developers Guide Using Leaders and Rules Creating PDF Files from XSL-FO Formatting Without a FrameMaker Template 10

Using Leaders and Rules In XSL-FO, a leader is often used in a table of contents to generate sequences of glyphs between headings and page numbers. Although a leader is usually made up of dots, you can use any character such as spaces or dashes. A rule is a horizontal line that you can use as a separator between text. For example, you may want to insert a rule between different regions in a document such as between the header and body regions. To create leaders and rules in an XSL-FO document, you use the fo:leader element. Examples This example uses the fo:leader element to produce leaders with different patterns. The first four fo:leader elements use the leader-pattern attribute to insert dots, spaces, a dotted rule, or a dashed rule between the text “One” and “Two”. The first four leaders are of fixed-length. The leader-length attribute for these leaders sets the distance between the text to either 3 inches or 1 inch. The last fo:leader element contains the use-content attribute value "•", which is a Unicode bullet character. The last leader is a variable-length leader, which generates a sequence of characters between the text, in this example, bullets. OneTwo OneTwo OneTwo OneTwo One •Two This example uses the fo:leader element to produce a solid horizontal rule (the default rule-style for a fixed-length leader) that is 8.5 inches wide between the text in the header region and the body region: My Document Title The first paragraph in my document. ...

Adobe Document Server Developers Guide Dec 19, 2003 235 Creating PDF Files from XSL-FO Creating Running Headers and Footers 10 Formatting Without a FrameMaker Template

Creating Running Headers and Footers You can use markers in an XSL-FO document to mark text in the content of a body region that you want to appear in a different region of a document. For example, you can use a marker to create a running header to insert the document’s title in the header or footer region of a page. You use the fo:marker element and marker-class-name attribute under the fo:flow element to mark the text that you want to appear in the header or footer region. You then use the fo:retrieve-marker element and retrieve-class-name attribute as a descendant of the fo:static-content element to insert the marked text in the header or footer region. As per the XSL-FO W3C Recommendation, you can only specify the fo:retrieve-marker element as a descendant of a fo:static-content element, as shown in the example below.

EXAMPLE 10.6 Running headers and footers without a FrameMaker template This example demonstrates the use of the fo:marker element to insert running headers and footers in the header and footer region of the page. The text “Heading 1” will appear in the header region and the text “Heading 2” in the footer region of the PDF document. Heading 1 Heading 2

236 Dec 19, 2003 Adobe Document Server Developers Guide Balancing Text Across Columns Creating PDF Files from XSL-FO Formatting Without a FrameMaker Template 10

Balancing Text Across Columns In a layout that uses a multicolumn text flow, you can use the ext-fo:column-balancing attribute to balance the text across columns so that the text appears even across the columns.

EXAMPLE 10.7 Balancing text across columns This example demonstrates the use of the ext-fo:column-balancing attribute to balance the text across two columns: This is a block. This is a block. This is a block. This is a block-container. This is a block-container. This is a block-container. This is a block-container. This is a block. This is a block. This is a block. This is a block. This is a block. This is a block.

Adobe Document Server Developers Guide Dec 19, 2003 237 Creating PDF Files from XSL-FO Generating Page # of ## Folios 10 Formatting Without a FrameMaker Template

Generating Page # of ## Folios You can use the fo:page-number and ext-fo:page-number-last-citation elements in an XSL-FO document to generate “Page # of ##” folios in the resulting PDF document.

EXAMPLE 10.8 Generating page # of ## folios This example uses ext-fo:page-number-last-citation elements to output the last page number on each page of the document. For the first block, the fo:page-number and ext-fo:page-number-last-citation elements produce “Page # of #” in the footer region of the document. The remaining ext-fo:page-number-last-citation elements output the last page number (3) in the body region on each page. of This block contains a page-number-last-citation: . The page-number-last-citation is the page number of the last page. Page 2 page-number-last-citation: . Page 3 page-number-last-citation: .

238 Dec 19, 2003 Adobe Document Server Developers Guide Referencing Other Content Holders Creating PDF Files from XSL-FO Common Formatting Tasks 10

Common Formatting Tasks

This section describes some of the formatting tasks that you can accomplish with or without a FrameMaker template.

Referencing Other Content Holders ADS supports the formatting of PSD, SVG, PDF, EPS, GIF, TIFF, JPEG, and PNG graphics content referenced in fo:external-graphic elements. You can use an "adobe-content:" URI to reference graphics content that is already loaded into ADS. This example demonstrates the use of an "adobe-content:" URI to reference a raster graphic that is already loaded into ADS: ● The command file loads a raster graphic and an XSL-FO file, then uses the formatXSL command to output the PDF file: ● The XSL-FO file imports the raster graphic by using an "adobe-content:" URI that references the LOGO content holder:

Embedding Graphics You can use the fo:instream-foreign-object element to embed graphics in an XSL-FO file. The fo:instream-foreign-object element can only reference an SVG file. The SVG file, however, may also contain embedded graphics of any other format that ADS supports when referencing graphics content in fo:external-graphic elements (PSD, PDF, EPS, GIF, TIFF, JPEG, and PNG).

Adobe Document Server Developers Guide Dec 19, 2003 239 Creating PDF Files from XSL-FO Defining Variables 10 Common Formatting Tasks

EXAMPLE 10.9 Embedding graphics in an XSL-FO document In this example, the embedded graphic is an SVG graphic that is output within the block in the PDF document: Insert instream-foreign-object within this block.

Defining Variables You can define variables in your XSL-FO document which can either contain text or system information. For example, you can define a user variable when you want to apply the same text fragment in several areas in a document. Or you can use a system variable to insert system information such as the current date in a document. For a list of the system variables that you can specify, see the “Supported XSL-FO Elements, Attributes, and Extensions” chapter in the Adobe Document Server XML Grammars Reference.

240 Dec 19, 2003 Adobe Document Server Developers Guide Defining Variables Creating PDF Files from XSL-FO Common Formatting Tasks 10

EXAMPLE 10.10 Defining variables in an XSL-FO document This example demonstrates user and system variables: My Product Name , , This is a block that references the variable prodname: . This variable is defined in the declarations element. The current date is . The fo:declarations element declares two variables: the user variable "prodname" and system variable "current-date". The system variable "current-date" contains ext-fo:variable-component elements. Each ext-fo:variable-component element and ext-fo:variable-component-type attribute pair defines a building block to output the current system date in a specific format.

Adobe Document Server Developers Guide Dec 19, 2003 241 Creating PDF Files from XSL-FO Specifying XMP Metadata 10 Common Formatting Tasks

Each fo:block element contains an ext-fo:variable-citation element. During formatting, the value of each ext-fo:variable-name here is substituted with the variable value defined for the ext-fo:define-variable element. For the user variable, the substituted text is “My Product Name”. For the system variable, the current system date is output in the format Monday Oct, 21, 02.

Specifying XMP Metadata ADS transfers any XMP metadata included in the XSL-FO document or FrameMaker template (if there is no metadata in the XSL-FO document) to the resulting PDF document. During this process, ADS updates the standard PDF property “Producer” and the last-modified dates. Any XMP metadata in the XSL-FO document must appear as an XML Packet containing the XMP packet wrapper, at one of the following XPath locations: /fo:root/fo:declarations/ext-fo:metadata /ext-fo:fragment-root/fo:declarations/ext-fo:metadata

EXAMPLE 10.11 XMP metadata in XSL-FO using fo:root This example defines the XMP metadata at the XPath location /fo:root/fo:declarations/ext-fo:metadata:

242 Dec 19, 2003 Adobe Document Server Developers Guide Specifying XMP Metadata Creating PDF Files from XSL-FO Common Formatting Tasks 10

EXAMPLE 10.12 XMP metadata in XSL-FO using ext-fo:fragment-root This example defines the XMP metadata at the XPath location /ext-fo:fragment-root/fo:declarations/ext-fo:metadata:

Adobe Document Server Developers Guide Dec 19, 2003 243 Creating PDF Files from XSL-FO Specifying XMP Metadata 10 Common Formatting Tasks

244 Dec 19, 2003 Adobe Document Server Developers Guide 11 Controlling Document Security

This chapter describes how to add and work with accessibility and security features provided for PDF files. It describes password–enabled encryption, which is provided by Acrobat, and explains how to encrypt PDF files with ADS and how to decrypt encrypted files before calling other ADS commands on them. It also describes the usage rights feature for Adobe Document Server 6.0 for Reader Extensions and how you can set usage rights with ADS. This chapter contains the following sections:

Encrypting PDF Documents starting on page 245 Decrypting PDF Documents starting on page 249 Usage Rights starting on page 251

Encrypting PDF Documents

You can add a measure of security to PDF documents by encrypting them. When a PDF document is encrypted, all string and stream content in the document is encrypted using the Adobe Acrobat Standard Security Handler. The PDF Reference contains details about this encryption algorithm. You cause a document to be encrypted by specifying one or two passwords for the document — an open password or a master password. The passwords set for an encrypted document determine the criteria that must be met for the document to be decrypted. You can also set permissions for the document, which can restrict what users who decrypt the document can do with it. You specify encryption criteria for a document while it is open, but the document’s contents are not actually encrypted until you save it. When you open an encrypted document and then close or save it, it is automatically encrypted again, unless you have removed password encryption while the document was open. It will be encrypted with the same passwords and permissions as were in place when you opened it, unless you have changed those settings while the document was open. You encrypt a PDF document in ADS with the encryptPDF command. When you encrypt PDF content with this command, you can supply three kinds of information: ● Passwords — You can specify an open password with the openPassword attribute, and a master password with the masterPassword attribute. You can specify one, both, or neither of these. However, Adobe recommends that you specify at least one of them. ● Encryption level — You can specify either 40–bit or 128–bit encryption with the level attribute. The default level is 40. The level you choose determines the length of the encryption key. It also determines the list of permissions you can set, and which versions of

Adobe Document Server Developers Guide Dec 19, 2003 245 Controlling Document Security Encryption Passwords 11 Encrypting PDF Documents

Acrobat can read the resulting file. Files encrypted at the 128–bit level can be opened only in Acrobat version 5.0 and later. ● Permissions — You can set permissions with the permissions attribute. The value of this attribute is a space–separated list of one or more constant string values denoting the operations you want to enable. The possible permission values you can specify are:

40–bit encryption 128–bit encryption

print printLow, printHigh

edit edit

note note

copy copy

access

fill

assemble

For details of these permissions, see the entry for the encryptPDF command in the Adobe Document Server Command Reference. Some encryption permissions affect the same functions as usage rights. In rights-enabled documents that are encrypted, the encryption permission setting takes precedence over the usage right in Adobe Reader. For more information on usage rights, see “Setting Usage Rights” on page 251.

Encryption Passwords There are two different passwords associated with encryption: ● The open password — Acrobat calls this the Document Open password; the PDF reference calls it the user password. This password controls who can decrypt and open the document. Only users who supply the correct open password can open and decrypt a file encrypted with an open password. ● The master password — Acrobat calls this the Permissions password; the PDF reference calls it the owner password. This password controls who can change the document permissions, including the passwords. Only users who supply the correct master password can set the document permissions and the passwords; others can only view the current permission settings. The permissions control what a user who opens the document can do to it. Permissions control such activities as printing the document, adding annotations, changing document layout by adding, deleting, or rearranging pages, filling in form fields, and accessing content to copy it or reinterpret it for the visually impaired. Setting the master password controls who can change these permission settings.

246 Dec 19, 2003 Adobe Document Server Developers Guide Encryption Passwords Controlling Document Security Encrypting PDF Documents 11

Because there are two possible passwords, there are four possible combinations for an encrypted PDF document. The criteria for opening and manipulating an encrypted file varies across these conditions. Open Password Only If a document is encrypted with only an open password, only users who know the password can open the file, but once open, users can do anything they like with the document because the permissions are not protected. Master Password Only If a document is encrypted with only a master password, anyone can open (and decrypt) the document, but their actions are limited by the permission settings in the document. Only those users who can supply the master password can do anything they like to the document. In ADS, this means decrypting the document with the master password. Both Open and Master Passwords A document encrypted with both open and master passwords can be opened with either password. In Acrobat, you can open an encrypted document with the user password, and then supply the master password to gain access to the permissions.

NOTE: If a PDF document has both an open and a master password, the passwords cannot be the same. Passwords are case-sensitive. In ADS, you must decrypt the document with one password or the other, and are then limited to those operations allowed by the permissions associated with that password. ● If you decrypt such a file with the open password, the document is decrypted so you can work on it. You are considered a regular user and can only perform the operations granted by the permissions in the document. For any ADS operation that changes the document such as deleting pages, you must have edit permission. For operations on comments, you must have note permission. ● If you decrypt such a file with the master password, the file is decrypted so you can work on it. You can do anything you want to the file, regardless of the current permissions settings. If an encrypted document has both master and open passwords, you must decrypt it with the master password in order to perform the following operations in ADS: ● Inserting a document into another document with the insertPages command. ● Assembling multiple documents into a single document. You can decrypt the first document with the open password, but you must decrypt all other documents to be assembled with the master password.

IMPORTANT: If an encrypted document has only an open password and no master password, you can perform the operations listed above. Both Passwords Null The encryptPDF command allows you to encrypt a document without setting either password. In this case, the passwords are assumed to be null strings. ADS automatically decrypts an encrypted document with null passwords. However, you cannot explicitly set a null password

Adobe Document Server Developers Guide Dec 19, 2003 247 Controlling Document Security Encryption Examples 11 Encrypting PDF Documents

in Acrobat, and Adobe recommends that you explicitly set passwords in encrypted files so as not to compromise document security.

TIP: It is not possible to recover a password from a document. Always store passwords in a secure location.

Encryption Examples This section gives a number of examples of different ways to encrypt PDF content with the encryptPDF command.

EXAMPLE 11.1 Encrypting a PDF document with an open password This example encrypts a PDF document at the 40–bit level with an open password only and saves it in a file named SampleOpen.pdf. Since no permission settings or master password are supplied, anyone who successfully opens this file can perform all operations on it.

EXAMPLE 11.2 Encrypting a PDF document with a master password and permissions This example encrypts a PDF document at the 128–bit level with a master password only and saves it in a file called sampleMaster.pdf. The resulting file can be opened only in Acrobat version 5.0 and later. Anyone can open and decrypt this file without supplying a password. However, they can only print the document at either high or low resolution, and fill in form fields. Users who open this file with the master password are not restricted by the current permission settings, and can do anything they like to the document, including changing the permission settings and the passwords.

248 Dec 19, 2003 Adobe Document Server Developers Guide Encryption Examples Controlling Document Security Decrypting PDF Documents 11

EXAMPLE 11.3 Encrypting a PDF file with permissions and both passwords This example encrypts a PDF document at the 40–bit level with both a master and open password, and with the permission to print the file and add and edit annotations enabled. The permission keywords must be separated by one or more spaces. The result is saved in a file called myEncryptedDoc.pdf. No one can open the resulting file without providing a password. A user who opens this document with the password “docWriters” is restricted to the permissions just set. A user who opens the document with the password “docMgr” can do any supported operation on it.

Decrypting PDF Documents

When you open an encrypted PDF document in Acrobat, the document is automatically decrypted when you supply a correct password (the user password, or the master password if one exists). Opening an encrypted document in ADS takes two steps: first you load the file with the loadContent command, and then you decrypt it with the decryptPDF command. You cannot call any other ADS commands on the loaded content until you have decrypted it. The decryptPDF command requires a single password. The password you supply must match one of the passwords set in the document. If it does not, the decryptPDF command does not produce an error, but the next operation you attempt on the decrypted content will fail. The password you provide determines what you can do to the decrypted contents. Since there are two passwords, there are four possible scenarios: no passwords, open password only, master password only, and both open and master passwords. The sections starting on page 247 explain the details of each scenario.

NOTE: In ADS, you cannot decrypt PDF content you just encrypted without first saving it, as the encryption doesn’t actually happen until the document is saved. In other words, there must be either a saveContent or saveOptimized command between the encryptPDF and decryptPDF commands; otherwise, an error occurs.

Adobe Document Server Developers Guide Dec 19, 2003 249 Controlling Document Security Encryption Examples 11 Decrypting PDF Documents

EXAMPLE 11.4 Decrypting a PDF document with a master password This example decrypts a PDF document that was encrypted with a master password of “shazam”. This allows you to perform any supported ADS operation on the decrypted content. After decryption, another document, Sample2.pdf, is prepended to the decrypted contents and the thumbnails are updated. The result is saved in an encrypted file called redo.pdf.

EXAMPLE 11.5 Decrypting a PDF document with an open password This example decrypts an encrypted PDF document that was encrypted with a user password of “openMe”. If the permissions set during the encryption process do not include edit, the deleting embedded thumbnails operation will fail. The result is saved to a file called SampleOpen.pdf.

250 Dec 19, 2003 Adobe Document Server Developers Guide Setting Usage Rights Controlling Document Security Usage Rights 11

Usage Rights

This section applies only if you have installed Adobe Document Server 6.0 for Reader Extensions (ADS-RE). Usage rights can enable specific editing capabilities in Adobe Reader 6.0. These rights are determined on a document–by–document basis. If you open a rights–enabled document in Reader, you may be able to: ● Add comments to the document; ● Fill in form fields; ● Digitally sign the document; ● Save the document after making these changes. PDF documents that are rights–enabled contain a usage rights dictionary. The presence of this type of dictionary causes the Adobe Reader to enable selected operations enabled by the rights in that dictionary. You can use ADS commands to set the usage rights in a PDF document, and to retrieve the current usage rights from a rights-enabled PDF document. You must have license permission to use the usage rights feature. The permission is granted based on the serial number you provide when you install ADS-RE. ADS provides two commands that allow you to work with usage rights in PDF documents: ● You can set usage rights in PDF content with the setUsageRights command. ● You can retrieve the current usage rights settings from PDF content with the getUsageRights command. This section explains these commands in more detail. For full detailed information on these commands and their attributes, see the Adobe Document Server Command Reference.

Setting Usage Rights You can create or modify usage rights in a PDF document with the setUsageRights command. If a PDF document does not contain a rights dictionary, the command creates one. If a PDF document already contains a rights dictionary, this command overwrites existing rights with the rights specified in the command. Rights for which you do not supply a setting retain their existing setting, or if not set, assume the default setting. There are four rights you can enable: ● Commenting — If you enable this right in a PDF document, anyone who opens the document in Acrobat Reader can add annotations to the document. ● Advanced Form Manipulations — If you enable this right in a PDF document, anyone who opens the document in Adobe Reader can import and export form data into existing form fields in the document, submit form data to a Web server, and spawn new pages from templates.

Adobe Document Server Developers Guide Dec 19, 2003 251 Controlling Document Security Setting Usage Rights 11 Usage Rights

● Digital Signatures — If you enable this right in a PDF document, anyone who opens the document in Adobe Reader can digitally sign the document. ● Save Document — If you enable this right in a PDF document, anyone who opens the document in Adobe Reader can make changes as enabled by the other rights, and can save the document with those changes. If any of the other rights are enabled, Adobe Reader automatically enables this one as well.

NOTE: Encryption permissions can affect whether an ADS command works on an encrypted file; usage rights have no such effect. Other than setting and reading them, ADS ignores usage rights.

EXAMPLE 11.6 Enabling all usage rights This example enables all usage rights and saves the result in a file called SampleUsageRights.pdf. Since the draft attribute is set to true, a draft watermark appears on every page of the document and the document counter is not incremented. Whenever this PDF document is opened in Adobe Reader 6.0, the Reader displays the message “Hello World” in the Documents Rights dialog box. The usage rights that are enabled for the document are displayed in the Document Rights dialog box. If this document is opened in a version of Reader prior to 6.0, a dialog box displays the string specified in the updateReaderMessage attribute.

252 Dec 19, 2003 Adobe Document Server Developers Guide Usage Rights in Encrypted Documents Controlling Document Security Usage Rights 11

EXAMPLE 11.7 Disabling all usage rights This example loads a PDF file, disables all usage rights for it, and saves the result in a file called disableUsageRights.pdf. None of the pages in this document are watermarked, so when the document is saved, the document counter is incremented. Users who open this file in Adobe Reader will not see any opening or update message, and will not be able to do anything to the document other than to view it.

Usage Rights in Encrypted Documents The operations enabled by usage rights and the operations enabled by encryption permissions overlap to some degree. When you encrypt a PDF document in which usage rights have been set, the encryption permissions may override the usage rights, since encryption happens after setting usage rights. ● If you load an unencrypted PDF document, you must set usage rights before encrypting it, as once you have called the encryptPDF command, you cannot do anything else with the content without first saving it. The encryption settings override the corresponding usage rights settings. ● If you load an encrypted PDF document, you must first decrypt it, and can then set usage rights. At this point, you could just save it, in which case the resulting document is encrypted with the existing permissions, and the encryption settings override the corresponding usage rights settings. ● If you load an encrypted PDF document, you must first decrypt it, and can then set usage rights. At this point, you may choose to re–encrypt it with new passwords and/or permissions. You cannot set usage rights after encrypting, because you must save the encrypted content before doing anything else to it (see the encryptPDF entry in the Adobe Document Server Command Reference for details). At the point of save, the encryption permissions override the corresponding usage rights settings.

Adobe Document Server Developers Guide Dec 19, 2003 253 Controlling Document Security Usage Rights in Encrypted Documents 11 Usage Rights

EXAMPLE 11.8 Setting usage rights and encryption permissions This example loads an unencrypted PDF document, enables all usage rights except for commenting, and then encrypts the content with a master password and edit and copy permissions. Each page of the resulting content has a watermark. The result is saved in a file called encryptPlusUsage.pdf. Users who open the resulting file in Adobe Reader can add comments to it, despite the fact that the usage rights forbid this operation; the encryption permission of edit overrides the fact the usage rights disabled commenting.

EXAMPLE 11.9 Setting usage rights and resetting encryption This example loads an encrypted PDF file and decrypts it with the master password. It then enables all usage rights, and resets the encryption permissions to just allow commenting. It saves the result in a file called decryptUsage.pdf.

254 Dec 19, 2003 Adobe Document Server Developers Guide Retrieving Usage Rights Controlling Document Security Usage Rights 11

Retrieving Usage Rights You can retrieve the existing usage rights from a PDF document with the getUsageRights command. This command returns the settings for all four of the usage rights — saving, commenting, form manipulation, and digital signatures — as well as any opening message and the draft status, as XML, in the form of a setUsageRights command.

EXAMPLE 11.10 Getting usage rights This example loads the PDF file created in Example 11.6, retrieves the usage rights, and saves the resulting XML output in a file called GetSampleUsageRights.xml.

The XML output produced by this example is shown below. Notice that is it formatted as an ADS setUsageRights command.

Adobe Document Server Developers Guide Dec 19, 2003 255 Controlling Document Security Retrieving Usage Rights 11 Usage Rights

256 Dec 19, 2003 Adobe Document Server Developers Guide 12 Manipulating PDF Features

This chapter describes how you can manipulate PDF document features that are peripheral to the text and images. These features include: ● Annotations associated with text or images in the document, with special emphasis on markup annotations (comments), and links. ● Bookmarks and thumbnails, which facilitate navigation within the document. ● File attachments, which encapsulate data from external files within a PDF document. All of the ADS commands you use for these manipulations are discussed and demonstrated in this section. For complete and detailed information on each command, see the Adobe Document Server Command Reference. This chapter contains the following sections:

Annotations starting on page 257 Bookmarks starting on page 269 Thumbnails starting on page 271 File Attachments starting on page 273

Annotations

An annotation associates an object such as a note with a location on a page in a PDF document. Annotations allow users to add information to existing PDF files, much like they would use a pen to mark up a physical copy of a document, although annotations provide more flexibility in the type of information that can be attached to a document, such as sounds, video clips, or other actions. Many of the standard annotation types display in either an open or closed state. When in a closed state, the annotation appears on a page in a distinctive form such as an icon or rubber stamp. When a user activates the annotation in Acrobat by double-clicking on it with the mouse, the annotation exhibits its associated object or plays a sound or video clip.

Annotation Types that ADS Supports There are a number of annotation types defined in PDF. The following table shows which of those types of annotations ADS recognizes and supports. The list is divided into two categories: markup annotations, also called comments, and other annotations.

Adobe Document Server Developers Guide Dec 19, 2003 257 Manipulating PDF Features Annotation Types that ADS Supports 12 Annotations

ADS provides four operations on annotations; you can add them to a PDF document by importing or merging them from another PDF source, you can delete them, and you can export them for other uses. Not all of these operations are supported for all the supported annotation types. The table below shows which operations are supported for which types, and lists the ADS command you use to accomplish each supported operation. N/S means “not supported”.

TABLE 12.1 Annotation types and operations supported by ADS

Type Description merge import export delete Markup annotations (also called Comments) Text Text annotation. Represents a mergeComments importComments exportComments deleteComments “sticky note” attached to a point on a page. When closed, it appears as an icon; when open, an associated Popup annotation displays the text of the annotation. Strikeout Strikeout annotation. When mergeComments importComments exportComments deleteComments opened, an associated Popup annotation displays text explaining the strikeout. Highlight Highlight annotation. When mergeComments importComments exportComments deleteComments opened, an associated Popup annotation displays text explaining the highlight. Underline Underline annotation. When mergeComments importComments exportComments deleteComments opened, an associated Popup annotation displays text explaining the underline. FreeText Freehand text annotation. N/S importComments exportComments N/S Displays text directly on the page. This type of annotation does not have an open or closed state or an associated Popup annotation, as the text is always visible. Squiggly Squiggly-underline N/S importComments exportComments N/S annotation, implemented by JavaScript. When opened, an associated Popup annotation displays text explaining the squiggly underline.

258 Dec 19, 2003 Adobe Document Server Developers Guide Annotation Types that ADS Supports Manipulating PDF Features Annotations 12

TABLE 12.1 Annotation types and operations supported by ADS (Continued)

Type Description merge import export delete Line Line annotation. Displays a N/S importComments exportComments N/S single straight line on a page. When opened, an associated Popup annotation displays text explaining the line. Square Square annotation. Displays a N/S importComments exportComments N/S rectangle on the page. When opened, an associated Popup annotation displays text explaining the square. Circle Circle annotation. Displays an N/S importComments exportComments N/S ellipse on the page. When opened, an associated Popup annotation displays text explaining the circle. Ink Ink annotation. A freehand N/S importComments exportComments N/S scribble composed of one or more disjointed paths. FileAttachment File attachment annotation. N/S importComments exportComments N/S Contains a reference to a file typically embedded in the PDF document. Sound Sound annotation. Typically N/S importComments exportComments N/S indicated by a speaker icon. When activated, a sound plays. Other annotations Popup Popup note annotation. mergeComments importComments exportComments deleteComments Displays text in a popup window for text entry, editing, and viewing. It usually does not appear alone, but is associated with a parent markup annotation such as a highlight or strikeout. Movie Movie annotation. Typically N/S N/S N/S N/S indicated by a filmstrip icon. When activated, a video plays.

Adobe Document Server Developers Guide Dec 19, 2003 259 Manipulating PDF Features Annotation Types that ADS Supports 12 Annotations

TABLE 12.1 Annotation types and operations supported by ADS (Continued)

Type Description merge import export delete Stamp Rubber stamp annotation. N/S importComments exportComments N/S Displays text or graphics intended to appear on a page as though they were stamped with a rubber stamp. TrapNet Trap network annotation for N/S importComments exportComments N/S printing workflows. Trapping adds marks to a page to avoid artifacts from colorant misregistration when printing the page. PrinterMark Printer’s mark annotation for N/S importComments exportComments N/S printing workflows. Represents a graphic symbol to assist in multi-plate print production. Link Link annotation. Represents N/S N/S exportLinks deleteLinks either a hypertext link to a destination elsewhere in the document, or an action to perform. For more information about manipulating links in ADS, see “Links” on page 266. Widget Widget annotation. N/S importFormDataa exportFormData deleteFormFields Represents form field appearance for user interaction. For more information about manipulating form fields in ADS, see Chapter 13, “Working with PDF Form Fields”.

a. See the note on page 261.

From this table, you can see that the import and export operations work on all annotation types except for links (import) and movies (both import and export). The merge and delete operations are more restrictive; they work only on a subset of the markup annotations, but they give you more control over which comments and comment types are affected by the operation. These operations are explained in more detail in the following sections: ● The Comments section describes how you can manipulate markup annotations. ● The Links section describes how you can manipulate link annotations.

260 Dec 19, 2003 Adobe Document Server Developers Guide Comments Manipulating PDF Features Annotations 12

Comments As shown in Table 12.1, some of the supported annotation types are considered markup annotations, because they are used to mark up a PDF file with comments of various types. They are also often called comments. Comments have associated text that appears with the markup, displayed in a related popup window (a Popup annotation). This section explains what you can do with comments in ADS: ● You can import and export most of the annotation types in either FDF or XFDF format with the importComments and exportComments commands. ● You can merge a subset of comment types (Text, Highlight, Underline, and Strikeout) from a source PDF into another PDF with the mergeComments command. You can also delete existing comments of these four types from a document with the deleteComments command. You can merge or delete comments from a document in ADS only if you have the proper permissions. For more information on document permissions, see the encryptPDF entry in the Adobe Document Server Command Reference. If you have the Adobe Document Server 6.0 for Reader Extensions product installed, you can edit a document in Adobe Reader only if you have the proper usage rights. For more information, see “Setting Usage Rights” on page 251. Exporting and Importing Annotations You can extract all annotations from one or more copies of a PDF document and consolidate them into a single copy of the same document. You use the exportComments command to extract the annotation information. You use the importComments command to copy the annotation information into a copy of the same document. These commands export and import all annotation types (not just the markup annotations) except for links and movies (see the next note). You can export and import annotations in either FDF or XFDF format. Use the FDF format when you have capabilities that require support in PDF syntax. For example, sound annotations are only supported in FDF format, since the format allows binary representation within it. Use the XFDF format for XML-based workflows where the ASCII representation is sufficient for your data.

NOTE: In Table 12.1, there are two commands listed in the import column: importComments and importFormData. The importComments command works on all annotation types listed except for Movie and Link; a different command, importFormData, is provided to import Widget annotations (form fields). This command is explained in Chapter 13. However, these two commands use the same mechanism for importing FDF or XFDF data into PDF content. This mechanism does not differentiate between Widget annotations (form fields) and other annotation types. Therefore, if you have an FDF or XFDF file that contains both form fields and other annotation types, both of these commands will import everything. In Acrobat, exporting form fields and exporting annotations are two separate operations, but there are other ways to generate FDF or XFDF data that may produce a mix of Widget and other annotation types.

Adobe Document Server Developers Guide Dec 19, 2003 261 Manipulating PDF Features Comments 12 Annotations

EXAMPLE 12.1 Exporting comments in the FDF format This example exports all annotations (except for widgets, links, and movies) from a PDF document into an FDF file called myExportedComments.fdf. Notice that you must specify the format attribute to get FDF format from the command.

EXAMPLE 12.2 Exporting comments in the XFDF format This example exports all annotations (except for widgets, links, and movies) from a PDF document into an XFDF file called myExportedComments.xfdf. Since the command produces XFDF format by default, you do not need to specify the format attribute here.

EXAMPLE 12.3 Importing comments in XFDF format This example imports annotations from an XFDF file into a PDF document and saves the resulting PDF in a file called reSample.pdf. Merging Comments The mergeComments command is intended to be used to copy comments from one or more copies of the same document into a single copy of that document. For example, you put out a document for review, and 10 people mark it up and send it back to you. Instead of processing the feedback one reviewer at a time, you can transfer each reviewer’s comments from his or her own copy into a single copy of the same document, and then work from that single document to make the corrections. You can accomplish a similar thing using the exportComments and importComments commands. However, these commands do not give you any control over which comments are included in the merge; they do a wholesale import and export of all comment types. The mergeComments command works only on four of the comment types -Text, Highlight,

262 Dec 19, 2003 Adobe Document Server Developers Guide Comments Manipulating PDF Features Annotations 12

Underline, and Strikeout - but it gives you more control over selecting comments within this subset, as it has attributes that allow you to specify particular comments to merge by comment type, page ranges, and author.

NOTE: You can merge comments from one document into a different document, but the results will not be useful. If you merge comments from multiple sources, and two or more sources contain some common comments, duplicate comments appear in the result file.

EXAMPLE 12.4 Merging comments from one source This example merges all comments from one source into another copy of that document. The document markUpSample.pdf contains comments from all but one reviewer. These comments are merged into the file reSampleMe.pdf, which contains comments from a single reviewer. The merged result is saved in a file called mySingleMergedComments.pdf. The file with multiple reviewer comments is loaded first and saved in a named content holder. The file with the single reviewer comments is then loaded, and the comments from the first load are merged into the second file, which is the current content. Since no attributes other than source are specified for the mergeComments command, all Text, Highlight, Underline, and Strikeout comments are merged, regardless of author, date created, or type.

EXAMPLE 12.5 Merging comments from multiple sources This example shows how to merge comments from multiple sources into a single copy of a PDF document, when each reviewer has commented on their own copy of the document. Each reviewer file is loaded and saved in a named content holder. The copy of the document into which all the comments is to be merged is loaded last, making it the current content. Then, one at a time, the comments from each named content holder are merged into the current content. The result is saved in a file called reviewedDoc.pdf.

Adobe Document Server Developers Guide Dec 19, 2003 263 Manipulating PDF Features Comments 12 Annotations

Deleting Comments Using the deleteComments command, you can delete four types of comments along with their associated popup annotations in PDF documents. You can delete Text, Highlight, Underline, and Strikeout comments. If you wish to delete other types of comments, you must do so from within Acrobat. When deleting comments, you can restrict the comments deleted by: ● Specifying only certain types of comments with the types attribute; ● Specifying comments added by a certain person with the author attribute; ● Specifying comments added before or after a certain date, or within a certain date range with the after and before attributes; ● Specifying a certain page or range of pages with the pages attribute. The following examples show how to do this.

EXAMPLE 12.6 Deleting all comments This example deletes all Text, Highlight, Underline, and Strikeout comments in the document, regardless of who added them, and regardless of when they were added, and saves the result in a file called unmarkedSample.pdf. All popup annotations associated with the comments are also deleted.

EXAMPLE 12.7 Deleting comments by author This example deletes all Text, Highlight, Underline, and Strikeout comments in a document that were created by a person named “blessing” in the current content and saves the result in a file called silentSample.pdf. All popup annotations associated with the comments are also deleted.

264 Dec 19, 2003 Adobe Document Server Developers Guide Comments Manipulating PDF Features Annotations 12

EXAMPLE 12.8 Deleting a specific type of comment This example deletes only comments of type Highlight and their associated popup annotations. All other comments are left in the document. The result is saved in a file called sampleSansHighlight.pdf.

EXAMPLE 12.9 Deleting comments before a particular date This example deletes all Text, Highlight, Underline, and Strikeout comments that were created before November 22, 2002. The result is saved in a file called sampleBeforeDate.pdf.

You can also specify dates with finer precision. For more information on date formats, refer to the Adobe Document Server Command Reference.

EXAMPLE 12.10 Deleting comments after a particular date This example deletes all Text, Highlight, Underline, and Strikeout comments that were created after January 1, 2002. The result is saved in a file called sampleAfterDate.pdf.

EXAMPLE 12.11 Deleting comments in a particular date range This example deletes all Text, Highlight, Underline, and Strikeout comments that were created between May 9th and May 15th. Notice that in order to specify this range, you specify the day before (May 8th) and after (May 16) the dates you actually want; the date specifications themselves are not inclusive. The result is saved in a file called BetweenDates.pdf.

Adobe Document Server Developers Guide Dec 19, 2003 265 Manipulating PDF Features Links 12 Annotations

EXAMPLE 12.12 Deleting comments by multiple authors This example deletes all Text, Highlight, Underline, and Strikeout comments added by two authors named “tony” and “blue”. In order to do this, you must use the deleteComments command twice, once for each author.

Links Links are a special type of annotation that represent one of two things (or sometimes both): ● A link to a destination elsewhere — Links of this type are like hypertext in HTML documents or online help systems. They allow a viewer to jump to other locations within the document or to other PDF documents when the link is activated. A destination link is a link represented by text in the Acrobat Destinations palette. Destination links are often used when linking across PDF documents, since a destination link is not affected by the addition or deletion of pages within the target document, unlike links to a page. ● An action to be performed — Links can initiate actions such as playing a sound or movie file, entering articles, showing comments, or submitting forms when they are activated. They can also express special kinds of destination actions, including URIs. ADS only exports the special destination action types. Links can be visible or invisible. You can use the Link tool in Acrobat to create links and set the destination. While you cannot create links in ADS, you can delete existing links from PDF content and export them in XML format. Because link annotations do not have any representation in FDF or XFDF, ADS provides special commands — exportLinks and deleteLinks — that operate on links separately from other annotation types. These commands are demonstrated in this section. For more detail about the commands and their attributes, refer to the Adobe Document Server Command Reference. Adobe has also defined an XML schema to describe link information. This schema is shown pictorially in the following figure. For more detailed information on this schema, and on the PDF key counterparts to the element attributes, refer to the Adobe Document Server XML Grammars Reference.

266 Dec 19, 2003 Adobe Document Server Developers Guide Links Manipulating PDF Features Annotations 12

FIGURE 12.1 The XML schema for links in PDF content

0 or more 0 or 1 linkOnPage baseURI rect date dashArray width color highlight name contents Mutually exclusive. A link can 1 only have one or the other of these 1 only elements, but not both. It must have one or the other. Mutually exclusive. pageNumber uri Only one of these pageName isMap three attributes can be pageAction specified. file fitParams fitType

Exporting Links You can extract links from a PDF document in XML format with the exportLinks command. You can use the resulting XML data to convert link information into an image map. The generated XML contains link annotation information in order by page, and within a page, in the order within the annotations array for that page. Only the supported keys and dictionaries are copied to the generated XML. Embedded file streams in destinations are not exported. The following table shows which action types are exported by ADS.

Link Type Exported Explanation GoTo Yes Changes the view to a specified destination within the same document. Only one such action is supported per link. This information is shown in the pageAction attribute of the destination element in the XML output. GoToR Yes Changes the view to a specified destination within a different document. Only one such action is supported per link. This information is shown in the pageAction attribute of the destination element in the XML output. URI Yes Changes the view to the location specified by a URI. Only one such action is supported per link. This information is shown in the uridest element in the XML output. Named actions Yes Initiates a predefined viewer operation, such as viewing the first, last, next, or previous page in a document. Only one such action is supported per link. This information is shown in the pageAction attribute of the destination element in the XML output.

Adobe Document Server Developers Guide Dec 19, 2003 267 Manipulating PDF Features Links 12 Annotations

Link Type Exported Explanation Article threads No Sound and Movies No Annotation Flags No Open file actions No AcroForm actions No Actions such as resetting or submitting forms, importing form data, or executing JavaScript scripts are not supported in ADS.

EXAMPLE 12.13 Exporting links This example demonstrates exporting links from a PDF document to an XML file. All links on all pages are exported. If you want to remove links from only some of the pages in a PDF document, you can specify a single page or a page range for the page attribute of the exportLinks command; the command removes links only from the pages you specify. The following code shows an excerpt of the exported link information output by Example 12.13. It shows the XML for a single link that has a destination child element. A link element’s rect attribute and its child element (either a destination or uridest element) are always present in exported link information. ... In the XML code above: ● The width attribute of the link element indicates the width of the border. In this example excerpt, the width is zero for the exported link. ● The rect attribute of the link element indicates the active rectangle area for the link. ● The linkOnPage attribute of the link element indicates on what page the link resides. ● The fitparams attribute of the destination element indicates the style of fit. ● The fitType attribute of the destination element indicates the view zoom adjustment. ● The pageNumber attribute of the destination element indicates the destination page of the link.

268 Dec 19, 2003 Adobe Document Server Developers Guide Links Manipulating PDF Features Bookmarks 12

The following XML code is another example of XML output from the exportLinks command. This example shows a link with a uridest child element. It also shows more of a link element’s attributes, such as color, dashArray, and highlight. Deleting Links You can delete link annotations from a PDF document in ADS with the deleteLinks command. Other types of annotations are deleted with a different command (see “Deleting Comments” on page 264).

EXAMPLE 12.14 Deleting links This example deletes all links on all pages of PDF content and saves it to a file called deleteLinks.pdf.

Bookmarks

A bookmark serves as a live link from a PDF document to another location within the same document, to another PDF or non–PDF document, or to a Web page. When present, bookmarks are displayed in a tree–structured hierarchy of outline items in the Acrobat viewer navigation pane, providing an online document outline that allows the viewer to navigate the document interactively. You can expand and collapse the hierarchy to show some or all of the bookmarks. When you click the text of a visible bookmark, the bookmark is activated, causing the Acrobat viewer to jump to the specified destination or trigger an action associated with the item. For most desktop–publishing programs, table of contents entries can be transformed into bookmarks in a PDF document. The only thing you can do to bookmarks with ADS is to export them.

Adobe Document Server Developers Guide Dec 19, 2003 269 Manipulating PDF Features Exporting Bookmarks 12 Bookmarks

Exporting Bookmarks You can extract bookmarks from a PDF document in XML format with the exportBookmarks command. The XML output conforms to the XML PDF bookmark schema as defined in the Adobe Document Server XML Grammars Reference. You can use the exported bookmark information in an XSL–FO or HTML workflow. You can also use the exportBookmarks command to confirm the presence of bookmark information when you insert a table of contents into an assembled PDF document. For more information on inserting a table of contents (TOC), see “Creating and Inserting a Table of Contents” on page 303.

NOTE: Bookmarks that perform actions such as playing a movie or sound, executing a menu item, or submitting a form are not exported by the exportBookmarks command. Only bookmarks that jump to another location with the same document or another document or Web page are exported by this command.

EXAMPLE 12.15 Exporting bookmarks This example loads a PDF document, exports its bookmarks, and saves the output in an XML file.

An excerpt of the XML file (SampleBookmarks.xml) that results from running this example is shown below:

270 Dec 19, 2003 Adobe Document Server Developers Guide Updating Thumbnails Manipulating PDF Features Thumbnails 12

...

Thumbnails

Thumbnails are miniature previews of pages in a PDF document that appear on the Pages tab in the navigation pane in Acrobat. A user can get an idea of what is on each page of the document by looking at the thumbnails, and can click a thumbnail image to jump to the corresponding page. Thumbnails are optional; not all PDF files contain them. When they are present, there is only one thumbnail per page. Thumbnails can be present for some pages and not for others. In Acrobat versions prior to 5.0, thumbnails display only if they are embedded in the PDF document. In Acrobat version 5.0 and later, thumbnails are always displayed, whether or not they are embedded in the document; if thumbnails are not embedded, Acrobat generates them dynamically. This takes some time for large documents, so the initial display can be slower. Thumbnails dynamically generated in Acrobat are not automatically embedded in the PDF document; you must explicitly embed them. By default, Acrobat Distiller does not automatically create and embed thumbnails in a PDF document; you must set an option to do so. For more information, see the Acrobat online help. You can do two things with thumbnails in ADS: create or update them, and delete them. ● Creating or updating thumbnails in ADS embeds the thumbnail images in the PDF content, resulting in a larger file size and possibly longer download times. However, Acrobat can display the document faster because the thumbnail images are already embedded in the file. ● Deleting thumbnails in PDF content results in a smaller file size and possibly faster download times. However, Acrobat will take longer to display the document because it must compute the thumbnail images from scratch each time. It may take Acrobat several seconds to redraw thumbnails in large documents. You may prefer to leave thumbnails embedded in these files.

Updating Thumbnails You might want to update thumbnails after inserting or deleting pages, combining several PDF documents into one, or otherwise changing the page count and organization of a document. You can update existing thumbnails in a PDF document, or create new ones if thumbnails do

Adobe Document Server Developers Guide Dec 19, 2003 271 Manipulating PDF Features Deleting Embedded Thumbnails 12 Thumbnails

not exist, with the updateThumbnails command. This command removes all existing thumbnails and regenerates and embeds new ones.

TIP: To maximize workflow efficiency and avoid rework, update thumbnails as one of the last steps when you create or edit a PDF document.

EXAMPLE 12.16 Updating thumbnails This example loads and decrypts a PDF document, inserts some pages, updates thumbnails for all pages, embeds them in the PDF document, and saves the result to a file called appendExtension.pdf. In order for the page insertion and thumbnail creation to succeed, the password provided when the document is decrypted must enable either the edit or assemble permission. You may not want to create or update thumbnails for every page in a document. For example, you may not want to have thumbnails for the opening pages that contain the title, the table of contents, and other lists. In this case, you can specify the pages attribute of the updateThumbnails command to specify either a single page or a range of pages, and thumbnails are created or updated only for those pages.

Deleting Embedded Thumbnails You can delete thumbnails embedded within a PDF document with the deleteThumbnails command. Deleting thumbnails reduces the file size of a PDF document; thumbnails consume approximately 3K of extra file space per thumbnail. When you delete thumbnails in ADS, the document pages associated with the thumbnails are not deleted.

TIP: Once you execute the deleteThumbnails command, you can verify that thumbnails are no longer embedded in the PDF document by opening the document in Acrobat (5.0 and up), and selecting Tools > PDF Consultant > Audit Space Usage. Thumbnails should display zero bytes and zero percent for file space consumption.

272 Dec 19, 2003 Adobe Document Server Developers Guide Deleting Embedded Thumbnails Manipulating PDF Features File Attachments 12

EXAMPLE 12.17 Deleting thumbnails This example removes all embedded thumbnails from a PDF document. If you do not want to delete all of the embedded thumbnails in a document, you can specify the pages attribute of the deleteThumbnails command to specify either a single page or a range of pages, and only the thumbnails for those pages are deleted.

File Attachments

A PDF document can have references to external files that are related to it. These references only identify the files; they do not contain the actual file data. In situations where you wish to archive or transmit a PDF document along with all of its related file data as a single entity, you can embed the related data in the PDF file itself, by using the PDF language construct called an embedded file stream. This embedded data need not be directly processed by Acrobat or any other PDF–consumer application. The Acrobat 6.0 interface calls embedded files streams file attachments, and provides operations on them from the Document > File Attachments menu. From this menu, you can create new file attachments, export data from existing file attachments, and delete existing file attachments.

NOTE: In Acrobat 5.0, file attachments were called embedded data objects.

NOTE: File attachments are not the same thing as annotations of type FileAttachment. ADS allows you to manipulate file attachments with the data object commands: ● Create new data objects — You use the importDataObject command to create new file attachments in PDF content. You supply the data source and a name for the newly created file attachments. ● Export data from data objects — You use the exportDataObject command to obtain a copy of embedded data in PDF content. You can save the resulting data in a content holder or an external file. ● Delete data objects — You use the deleteDataObject command to remove existing file attachments in PDF content. Deleting a file attachment removes the data bytes and the attachment’s name from the PDF content. In order to export or delete file attachments from PDF content in ADS, you must know the name of the file attachments on which you wish to operate. You can view the names of existing file attachments in Acrobat from the Document > File Attachments menu.

Adobe Document Server Developers Guide Dec 19, 2003 273 Manipulating PDF Features Importing File Attachments 12 File Attachments

The rest of this section explains in more detail how to create, export, and delete file attachments in ADS. For further details about the importDataObjects, exportDataObjects, and deleteDataObjects commands, refer to the Adobe Document Server Command Reference.

Importing File Attachments You create new file attachments in PDF content with the importDataObject command. You specify the source of the data to be embedded with the from attribute, and a name for the resulting file attachment with the object attribute. This command copies the bytes of the source file you specify into the current PDF content. You can also optionally specify a filename to be associated with the data you are importing with the fileName attribute. You can supply the data to be embedded in the file in one of two ways: ● By loading it first into an ADS content holder — You can import data in any format that you can load into ADS with the loadContent command; you can specify any type of content holder for the from attribute of the importDataObject command. See Chapter 3, “ADS Command Basics” for a list of all supported content types. You specify the name of the content holder that holds the file you wish to embed in the from attribute of the importDataObject command. ADS transforms the bytes of data in certain file formats upon load. For example, many of the raster image file formats (PSD, JPEG, TIFF, GIF, PNG) are transformed into a PDF–like internal representation called Raster. Raster content in ADS is not byte–identical with the original file that was loaded. ADS also reorders attributes in SVG and XML input upon load, so the embedded bytes are not identical to the source input. (The attribute reordering does not reformat the input.) ADS may also transform the bytes in a content holder when it saves it to an external file. For example, Raster content marked to be saved as TIFF is transformed to TIFF format upon save. When you create a data object from data in a content holder, ADS embeds the data in the form that it would save it with the saveContent command. If you wish to import data with no transformation, you should not specify a content holder as the data source; you should specify an external file, as described in the next item. Example 12.18 imports data from a content holder. ● By specifying an external file — If you want to embed a file type not supported by ADS, or you want to ensure that ADS does not transform the data you import in any way before embedding it, regardless of the file type, you should specify an external file for the from attribute of the importDataObject command. In this way, you can embed data of file types you cannot give to the loadContent command, such as bitmap (.bmp) or Targa (.tga) files.

NOTE: You must specify an external file in the from attribute with an absolute URI that uses the file: scheme. Example 12.19 imports data from an external file.

274 Dec 19, 2003 Adobe Document Server Developers Guide Importing File Attachments Manipulating PDF Features File Attachments 12

EXAMPLE 12.18 Importing data for a file attachment from a content holder This example creates a new file attachment in the current PDF content. It gets the data for the new file attachment from a named content holder that was created by loading a a JPEG image file. The JPEG data is transformed on load into Raster content marked to be saved as PSD, so the data is embedded in the PDF content in PSD format. As a result, the bytes embedded in the file attachment are not identical to the bytes in the original JPEG file.

The data file is loaded first and saved in a content holder named stuffObject. The PDF file is loaded second, becomes current content, and is operated on by the importDataObject command. The new file attachment is called myHorse and is associated with a filename called Heritage.psd. This filename is displayed along with the file attachment name in Acrobat. It can indicate the name of the file from which the file attachment contents came, but does not have to. If you save the file attachment content to a file on disk from the Acrobat UI, this name is used to name the resulting file. The PDF content containing the newly embedded file attachment is saved in a file called stuffNativeSample.pdf.

TIP: To make working with file attachments easier, make sure you append an extension to the fileName attribute of the importDataObject command. The filename attribute does not have a mechanism for automatically appending file extensions. When you add an extension to the fileName attribute value, you can avoid being prompted by the Windows operating system for an application in which to open the file. Note that when you manually append an extension, there is no guarantee that the file extension represents the file type. Content is embedded in the same format as the saveContent command would produce.

EXAMPLE 12.19 Importing data for a file attachment from an external file This example creates a new file attachment in the current PDF content. It gets the data for the new file attachment from an external JPEG file, so the JPEG data in the new file attachment is byte–identical to the data in the original JPEG file; ADS does not transform it in any way. Notice the absolute URI that identifies the external file. This URI cannot be relative.

Adobe Document Server Developers Guide Dec 19, 2003 275 Manipulating PDF Features Exporting File Attachments 12 File Attachments

The new file attachment is named myHorse and is associated with the filename Heritage.jpg. If you used Acrobat to look at the file stuffForeignSample.pdf that is produced by this example, you could see this file name in the information displayed for the myHorse file attachment.

Exporting File Attachments You can export the data from an file attachment with the exportDataObject command. You can export the data into either a content holder or a file. If the data is put into a content holder, the data may be transformed; if copied to a file, the data bytes are unchanged. You should export the data to a file if you want to extract the data exactly as it is embedded in the PDF content, or if the data being exported is not in a file format that you can load into ADS. If you attempt to export data in an unsupported format into a content holder, the exportDataObjects command will cause an error. The embedded data is not removed from the current content when you export a file attachment; the PDF content operated upon by the exportDataObject command is left unchanged.

NOTE: You can only export one file attachment per exportDataObject command.

EXAMPLE 12.20 Exporting a file attachment into a content holder This example exports a file attachment called myHorse into an unnamed content holder, which becomes the current content. Notice the absence of the to attribute for the exportDataObject command; this attribute is not necessary when saving to a content holder. If you wanted to name the content holder, you would do so with the out attribute. The current content is then saved to a file called myExportedHorse.psd. The extension .psd was chosen because the data in the file attachment was originally from a JPEG image file and was imported via content holder, so that ADS loaded it as Raster content marked to be saved as PSD. When ADS exported the data into the content holder, it wrote it out in PSD format. If you do not know the file format of the exported data, you should specify appendExtension=true in the saveContent command and let ADS append the correct extension to the filename.

276 Dec 19, 2003 Adobe Document Server Developers Guide Deleting File Attachments Manipulating PDF Features File Attachments 12

EXAMPLE 12.21 Exporting a file attachment into an external file This example exports a file attachment from PDF content directly into a file called exportExternalHorse.jpg. In this example, the to attribute specifies an absolute URI; relative URIs are not supported. In this case, you do not use a saveContent command. In contrast, the previous example 12.20 exported the same file attachment as a PSD file, since ADS internally converts supported raster images to PSD content.

NOTE: Because the URI for the to attribute is (and must be) absolute, any settings in effect for resultLocation and resultOverwrite are ignored by the exportDataObject command. Any pre-existing files are overwritten.

Deleting File Attachments You can delete a file attachment in PDF content with the deleteDataObject command. If the attachment you specify in the object attribute is not found in the PDF content, ADS produces a warning message.

EXAMPLE 12.22 Deleting a file attachment This example deletes the file attachment named myHorse from the current PDF content and saves the result in a file called strippedSample.pdf.

Adobe Document Server Developers Guide Dec 19, 2003 277 Manipulating PDF Features Deleting File Attachments 12 File Attachments

278 Dec 19, 2003 Adobe Document Server Developers Guide 13 Working with PDF Form Fields

This chapter explains how you can use Adobe Document Server commands to manipulate form fields in interactive forms. An interactive form is a collection of one or more form fields in a PDF document; it is also referred to as an AcroForm. A document containing an interactive form may or may not contain non–form content as well. Starting with PDF 1.5, interactive forms may contain fields that conform to the Adobe XML Forms Architecture (XFA). Files containing such fields are referred to as XFA-based PDF documents. In general, the commands described in this chapter apply only to non-XFA-based documents. The only exception is the flattenForm command (see “Flattening Form Fields” on page 287). The chapter contains the following sections:

Overview starting on page 279 Filling In Form Field Data starting on page 281 Covers providing text input, as well as importing and exporting field values. Controlling Form Field Appearance starting on page 283 Shows you how to change a field border and content appearance and other visual properties. Controlling Field Accessibility starting on page 286 Covers hiding, write-protecting, flattening, and deleting form fields.

Overview

The visual representation of form fields is provided by Widget annotations (see Table 12.1 on page 258). Because Widgets act differently than many other annotation types, ADS provides a separate set of commands that work on form fields. These commands operate on existing form fields in PDF content. You cannot create new form fields with ADS commands; you can use the Acrobat user interface or Acrobat JavaScript to create new form fields. ADS provides commands that: ● Export and import form data — You can export data from existing form fields in a PDF document, and import data into existing form fields. The imported data can come from an export operation. These operations allow you to populate different PDF forms with the same data set. ● Change form field appearance — You can change many visual characteristics about a field, such as its border color and style, font characteristics for text fields, and button appearance for button fields.

Adobe Document Server Developers Guide Dec 19, 2003 279 Working with PDF Form Fields 13 Overview

● Convert form fields to text — This process is called flattening. Once a field is flattened, you can no longer change it. ● Delete form fields — You can delete existing form fields in PDF content. You can manipulate the following form field types with these commands: ● Buttons — This type includes push buttons, check boxes, and radio buttons. A check box toggles between the on and off states. A radio button field is a set of related toggles of which one is selected at any given time. ● Choice — This type includes combo boxes and list boxes. ● Text — A text field is a box into which you can place text. Text fields can wrap to contain multiple lines of text.

NOTE: ADS cannot manipulate Digital Signature fields at this time. Each form field type has associated attributes that you can change. The attributes are referred to as properties in the Acrobat interface. You can change some of these properties in ADS:

TABLE 13.1 Form field properties you can change in ADS

Properties What they control Examples in this chapter

value The field value Example 13.1 on page 281

display Whether the form field is visible or not for Example 13.9 on page 286 onscreen viewing and printing

readOnly Whether the form field value can be Example 13.10 on page 287 changed

borderStyle The visible appearance of the form field Example 13.7 on page 285 lineWidth Example 13.6 on page 284 glyphStyle strokeColor fillColor

textColor The visible appearance of text in the form Example 13.6 on page 284 textFont field textSize alignment

buttonIcon Button field icons and captions Example 13.8 on page 285 buttonCaption

For details on these properties and their allowed values, see the entry for the setFormFields command in the Adobe Document Server Command Reference.

NOTE: If you require access to an attribute not accessible via ADS, you must use the Acrobat UI or the Acrobat JavaScript API to access the field property. Besides these form–specific operations, you can manipulate a PDF form with any of the general PDF manipulation commands described in Chapter 12, “Manipulating PDF Features” and Chapter 14, “Manipulating Pages and Documents.”

280 Dec 19, 2003 Adobe Document Server Developers Guide Setting Text Field Values Directly Working with PDF Form Fields Filling In Form Field Data 13

Filling In Form Field Data

One of the properties of a form field is its value. You can set a form field value in two ways with ADS commands: ● Setting the value directly — You can use the setFormFields command to directly provide text values for text fields. The section “Setting Text Field Values Directly” starting on page 281 explains how to do this. ● Importing the value — You can import form field values from another source with the importFormData command. One such source of input can be the output from the exportFormData command. The section “Importing and Exporting Form Data” starting on page 281 explains how to use these commands.

Setting Text Field Values Directly You specify the desired contents of a text form field by providing a value for the field’s optional value attribute. You use the setFormFields command to set this value. The value attribute is a string that can contain up to the maximum number of characters defined for the field. If you are setting values for text fields for a combo box, the combo box must be set to Editable in the Acrobat field properties dialog box. Otherwise, the setFormFields command fails to set the field value without issuing an error.

EXAMPLE 13.1 Providing values for text form fields directly This example loads an expense form and provides text values for the employee name and manager name fields. It saves the modified form to a file called fillFormFields.pdf. Notice that the setFormFields command can contain any number of field elements, one for each field you wish to set.

Importing and Exporting Form Data Another way to set the value of a form field is to import its value from a data file. This data can be in either FDF or XFDF format. FDF is the normal Acrobat form data format; XFDF is an XML version of FDF. You can export form data from a PDF document containing form fields to either of these formats. In ADS, you use the exportFormData command to export form field data from PDF content and the importFormData command to import form data into PDF content.

Adobe Document Server Developers Guide Dec 19, 2003 281 Working with PDF Form Fields Importing and Exporting Form Data 13 Filling In Form Field Data

NOTE: These commands do not import or export digital signature fields.

NOTE: The importFormData command will import other annotation types as well, if they are present in the FDF or XFDF input. See page 261 for details. Exporting Form Data You can export form data from PDF content with the exportFormData command. The resulting form data file is considerably smaller than the entire PDF document that contains the form data. The FDF or XFDF file is useful for archiving purposes and for sharing form data over limited bandwidth connections.

EXAMPLE 13.2 Exporting form data to FDF format This example loads a PDF form and exports its form data into a file called exportExpenses.fdf, in FDF format. The format attribute must be explicitly set to fdf in order to get the output in FDF format.

EXAMPLE 13.3 Exporting form data to XFDF format This example loads a PDF form and exports its form data into a file called exportXMLExpenses.xfdf, in XFDF format. Because XFDF is the default format output by the exportFormData command, you do not have to specify the format attribute. Importing Form Data Once you have form data in an FDF or XFDF file, you can import that data to another PDF form with the importFormData command. This command only sets property values for fields that already exist; it does not create new ones. If the input data specifies a form field that does not exist in the current content, the data for that field is ignored. You can import a form data file repeatedly to fill out multiple forms that have some field names in common. An organization should have a standard naming convention in place to facilitate form compatibility.

NOTE: Form field names are case-sensitive.

282 Dec 19, 2003 Adobe Document Server Developers Guide Importing and Exporting Form Data Working with PDF Form Fields Controlling Form Field Appearance 13

EXAMPLE 13.4 Importing form data This example loads the form data exported in Example 13.2, loads a PDF form, and imports the form data into the form. The newly filled–in form is saved in a file called fillBlankForm.pdf.

EXAMPLE 13.5 Exporting and importing together This example loads two PDF forms, exports the form data from the first one loaded, and imports it into the second one loaded, which is the current content. The result is saved in a file called exportImportDocument.pdf.

Controlling Form Field Appearance

Table 13.1 on page 280 lists the form field properties you can change to control the visible appearance of a form field and any text that appears in it. You set these properties with the setFormFields command. The new value you specify for a field’s property overrides the current value of that property in the current PDF content. If you specify a field name that does not exist in the current content, the command issues a warning. The following examples show how to change the appearance of a field, the style of a check box or radio button, and the graphic and caption displayed on a button.

Adobe Document Server Developers Guide Dec 19, 2003 283 Working with PDF Form Fields Importing and Exporting Form Data 13 Controlling Form Field Appearance

EXAMPLE 13.6 Changing the appearance of a form field This example sets the visible characteristics of the employee name field. It sets the borderStyle, lineWidth, strokeColor, and fillColor properties, which results in a field surrounded by a very thick red dashed border and filled with a yellow background. These properties correspond to the Border area of the Field Properties dialog box in the Acrobat user interface. It also sets the textColor, textFont, textSize, and alignment properties so that any text appearing in the form field appears in green GiddyupStd font centered in the field, in a font size as large as will fit in the field. These properties correspond to the Text area in the Appearance tab of the Field Properties dialog box in Acrobat. The textSize property set to 0 is equivalent to the Auto size option in Acrobat. Alignment is found on the Options tab in Acrobat. Notice that a PDF document can contain objects from multiple color spaces. For more information about color space arrays, see the online Acrobat JavaScript Guide, which is available from the Help menu of Acrobat.

284 Dec 19, 2003 Adobe Document Server Developers Guide Importing and Exporting Form Data Working with PDF Form Fields Controlling Form Field Appearance 13

EXAMPLE 13.7 Changing the style of a check box or radio button This example changes the style of two buttons in a form. It sets the field called “Recruiting” to a star style, and the field called “Unused Tickets” to a diamond style, by setting their glyphStyle properties. This property determines what appears inside a check box or radio button when a user turns it on. A button field may already display this glyph if its “Default is Checked” property is set. The size of the glyph is determined by the size of the font specified in the field’s textSize attribute.

NOTE: If you need to change the default selected property, you must change the “Default is Checked” property in Acrobat. This property is not available in the Acrobat JavaScript API.

EXAMPLE 13.8 Replacing a button’s icon and caption A button appears as an icon, a caption (a line of text), or both. A button field’s buttonIcon and buttonCaption properties determine its appearance. This example provides a graphic of the Adobe logo as the button’s icon and a caption of “Press Me” for a pushbutton field called “secretButton”. The button graphic must be a PDF file. The scale and location of the PDF graphic inherits the current settings of the button field.

TIP: In order to avoid any scaling issues such as distortion when importing a button graphic, make sure that your scaling properties are set to “Always” and “Proportional” in the Icon Placement dialog box in Acrobat. To access the scaling settings, click the Advanced Layout button on the Field Properties Options tab.

Adobe Document Server Developers Guide Dec 19, 2003 285 Working with PDF Form Fields Controlling the Visibility of a Form Field 13 Controlling Field Accessibility

Controlling Field Accessibility

You can control access to a field in a number of ways: ● By controlling its visibility — You can make a field visible or invisible. See “Controlling the Visibility of a Form Field” on page 286. ● By controlling whether it is writable — You can make a field read-only or writable. See “Controlling Write Access for a Form Field” on page 287. ● By flattening it — You can convert a field to page contents. See “Flattening Form Fields” on page 287. ● By removing it — You can delete form fields. See “Deleting Form Fields” on page 289.

Controlling the Visibility of a Form Field A form field can be either visible or invisible. You can control its visibility by setting its display property with the setFormFields command. This property can have four values, which control whether it is visible for online viewing and for printing. The four choices are:

Visible for Visible for Property value viewing printing

visible yes yes

noView no yes

noPrint yes no

hidden no no

While a form field’s display attribute is set to the hidden or noView values, you cannot change the form field’s properties.

EXAMPLE 13.9 Hiding a form field This example hides the field in an expense form that contains a person’s social security number, by setting the display property for the “SSN” field to “hidden”. It saves the result in a file called hideFormField.pdf. When viewed or printed, the SSN field will not be visible.

286 Dec 19, 2003 Adobe Document Server Developers Guide Controlling Write Access for a Form Field Working with PDF Form Fields Controlling Field Accessibility 13

Controlling Write Access for a Form Field A form field can be either writable or read–only; you can control this property by setting its readOnly property to true or false with the setFormFields command. When this property is true, users cannot edit the form field. Setting a form field to read–only is useful for fields that are calculated, such as totals fields, and for fields whose values are imported from a database.

EXAMPLE 13.10 Restricting write access for form fields This example loads an expense report form and sets six of its fields that contain totals to read– only. It saves the result in a file called formReadOnly.pdf. Users who open this file cannot edit these fields.

Flattening Form Fields You can convert form fields in a PDF document to page contents. This process is called flattening. Once you flatten a form field, users cannot manipulate the field in Acrobat. There is no operation to reverse this process. In ADS, there are two commands that allow you to flatten form fields in PDF content: ● The flattenForm command flattens all form fields in a document. It is the only command that can be used to flatten fields in XFA-based PDF documents; it also works with non- XFA-based documents. ● The flattenFormFields can be used only with non-XFA-based documents. With this command, you can flatten all form fields, or you can specify certain fields to flatten or to not flatten. You can also restrict the flattening to a specific page range. This command flattens only form fields (Widget annotations); it does not flatten any other types of annotations. If you specify a nonexistent form field or misspell the form field name, ADS issues a warning message.

NOTE: Digital signature form fields are never flattened by either of these commands.

NOTE: You cannot flatten form fields from the Acrobat UI.

Adobe Document Server Developers Guide Dec 19, 2003 287 Working with PDF Form Fields Flattening Form Fields 13 Controlling Field Accessibility

EXAMPLE 13.11 Flattening all form fields with the flattenFormFields command This example flattens all form fields on all pages in a final copy of an expense report. Notice that the flattenFormFields command does not have any attributes specified, resulting in the default behavior of flattening all form fields on all pages.

EXAMPLE 13.12 Flattening all form fields with the flattenForm command This example produces the same behavior as the previous example, using the flattenForm command. This example can be used with XFA-based PDF files. ****

EXAMPLE 13.13 Flattening certain form fields by inclusion This example shows how to flatten only certain form fields with the flattenFormFields command. The fields flattened here are the employee and manager name fields. All other form fields are preserved as form fields. Anyone viewing the resulting form in someFlatFormFields.pdf will not be able to change the employee or manager’s names.

288 Dec 19, 2003 Adobe Document Server Developers Guide Deleting Form Fields Working with PDF Form Fields Controlling Field Accessibility 13

EXAMPLE 13.14 Flattening certain form fields by exclusion This example shows how to flatten all form fields, except for an explicit list of fields, with the flattenFormFields command. All fields in the form are flattened except for the expense date and the line 1 amount in the airfare section. Anyone viewing the resulting form in preserveFormFields.pdf will not be able to interact with any fields except for these two.

Deleting Form Fields You can delete form fields in PDF content with the deleteFormFields command. You can delete all form fields, or specify specific fields to delete.If you specify a nonexistent form field or misspell the form field name, ADS issues a warning message.

EXAMPLE 13.15 Deleting specific form fields This example deletes the employee and manager name fields from an expense report form and saves the result in a file called fewerFormFields.pdf. All other form fields are not affected by this operation.

EXAMPLE 13.16 Deleting all form fields This example deletes all form fields from an expense report and saves the result in a file called noMoreFormFields.pdf. Notice that the absence of any field subelements in the deleteFormFields command causes all form fields to be removed.

Adobe Document Server Developers Guide Dec 19, 2003 289 Working with PDF Form Fields Deleting Form Fields 13 Controlling Field Accessibility

290 Dec 19, 2003 Adobe Document Server Developers Guide 14 Manipulating Pages and Documents

This chapter describes the operations you can perform in ADS that enable you to modify the layout of existing documents and combine them into a single document. You can perform these operations in a number of combinations; the organization of this chapter does not imply that this is the only way in which you can combine these operations. The operations fall roughly into the following categories: ● Deleting pages — You can delete specific pages from an existing document. ● Adding pages — You can add pages to an existing document by spawning pages from a template. You can also force an even page count by adding a blank page to the end of a document. ● Combining documents to make a new one — You can combine two or more documents into a single document and create a table of contents for the new document. ● Changing the layout — You can modify the layout of a document by rotating pages, by combining content from another document or from a template with existing page contents, and by renumbering page labels to reflect the new pagination after combining documents. This chapter contains the following sections:

Deleting Pages starting on page 292 Covers the deletePages command Adding Pages starting on page 294 Covers the spawnPage and forceEvenPages commands Combining Documents starting on page 296 Covers the insertPages, assemblePDF, and createTOC commands Changing Document Layout starting on page 306 Covers the rotatePages, overlayPages, overlayTemplates, spawnPage, and setPageLabels commands

This chapter explains how to use the commands listed above. For detailed information on each command, see the Adobe Document Server Command Reference. Starting with PDF 1.5, interactive forms may contain fields that conform to the Adobe XML Forms Architecture (XFA). Files containing such fields are referred to as XFA-based PDF documents. Some of the commands described in this chapter have restrictions when used with XFA-based documents, or cannot be used at all.

Adobe Document Server Developers Guide Dec 19, 2003 291 Manipulating Pages and Documents 14 Deleting Pages

Deleting Pages

You can delete contiguous pages from a PDF document with the deletePages command. After deleting the specified pages, this command updates bookmarks and logical structures for the remaining pages. It also renumbers the logical page numbers, but does not change the page labels. When you delete a page with this command, other objects associated with the deleted page are also deleted: ● Annotations ● Thumbnails ● Digital signatures, whether or not they are visible. You cannot delete all pages within a document; at least one page must remain. If you attempt to delete all pages, an error occurs. You cannot delete pages containing form fields from an XFA-based document; only pages not containing form fields can be deleted. The resulting document is XFA-based. The deletePages command has an attribute called pages that you can use to control the page or range of pages that the command deletes. The following examples show how to use this attribute.

EXAMPLE 14.1 Deleting the first page of a document This example deletes the first page from the current PDF content. Page numbers always start at one (1).

EXAMPLE 14.2 Deleting the last page of a document This example deletes the last page from the current PDF content. Notice the special value last to indicate the last page. This value relieves you of having to know how many pages the document contains.

292 Dec 19, 2003 Adobe Document Server Developers Guide Manipulating Pages and Documents Deleting Pages 14

EXAMPLE 14.3 Deleting a specified range of pages This example deletes pages three through ten (3-10) from the current PDF content.

EXAMPLE 14.4 Deleting discontiguous pages The pages attribute requires a range of contiguous pages. If you want to delete several pages that are not adjacent to each other, or a number of page ranges that are not contiguous, you must call the deletePages command multiple times, one for each page or page range you want to delete. However, since each deletePages command renumbers the remaining pages in the current content, you must specify your page numbers or page ranges from the end of the document to the beginning, or you will end up deleting the wrong pages. This example deletes pages 2, 4-6, and 8 from the current PDF content. \

EXAMPLE 14.5 Deleting all but one page This example deletes all but the first page of the current PDF content.

Adobe Document Server Developers Guide Dec 19, 2003 293 Manipulating Pages and Documents Forcing an Even Number of Pages 14 Adding Pages

Adding Pages

ADS provides two ways to add new pages one at a time to an existing PDF document: ● You can add a blank page to the end of a document with an odd number of pages with the forceEvenPages command. ● You can add a single page anywhere in a document using a template defined in the same document, with the spawnPage command. This section explains these two commands in more detail.

Forcing an Even Number of Pages You can use the forceEvenPages command to add an extra blank page to a document that has an odd number of pages. There are a number of reasons why you might want to do this. One situation is when you are combining a number of documents into a single new document in a double–sided layout and you want each section to start on a righthand page. Another is when you are producing PDF files for a print production workflow, which requires an even and odd page for each printing plate. The forceEvenPages command adds a blank page to the end of the document, using the same page size as the last page of the document. You can add content to this blank page with other commands explained in this chapter, such as adding a page label (setPageLabels) or adding background template content (overlayTemplates) or a watermark (overlayPages). If a document already contains an even number of pages, this command does nothing and completes without error.

EXAMPLE 14.6 Forcing an even number of pages The example below adds an extra blank page at the end of the document if the current content has an odd number of pages, and does nothing if the current content has a even number of pages. The resulting content is saved to a file called evenSample.pdf.

Spawning Pages from Templates In Acrobat, you can name a single page in a PDF document as a template. You can have multiple templates in the same document. Each template has a unique name. Template pages can be visible or invisible. Once you have created templates in a PDF document, you can use them to create new pages that look just like the template page. The process of creating a new page in a PDF document

294 Dec 19, 2003 Adobe Document Server Developers Guide Spawning Pages from Templates Manipulating Pages and Documents Adding Pages 14

using a template is called spawning. The spawned page is in the same document as the template that was used to create it. This template feature allows you to predefine the layout and content of portions of a document, and then create as many instances of that content as you need for a particular document. If you include form fields on a template page, you can use it to dynamically build a form, adding as many pages of a particular set of form fields as many times as necessary to accommodate the data supplied. For example, an invoice may need additional pages if invoice items in a table overflow a page. If you are generating a form by importing data from a database, you can spawn as many pages as needed to contain different quantities of data. You can spawn pages from Acrobat templates with the spawnPage command in ADS. You specify the template to use for the spawn operation with the template attribute. You control where the spawned page is placed in the existing document with the location attribute; it takes two values as a string, the second of which identifies a page in the current content, and the first of which indicates whether the new page should be inserted before or after the identified page. If a template contains form fields, you can control whether the field names in the template are copied as is or are renamed during spawning with the formFields attribute.

NOTE: You cannot use this command on XFA-based PDF documents.

NOTE: You can also use the spawnPage command to overlay the contents of a template page onto an existing page in the same document.

TIP: You must know the names of the templates in a PDF document in order to use this command. To define, view, or edit a template in Acrobat, choose Advanced > Forms > Page Templates. For more information, see the Acrobat online help.

EXAMPLE 14.7 Appending a spawned page This example spawns a new page from the template named "spawnMe" in the current PDF content and appends the new page to the end of the content. Since the default value for the location attribute is "after last", it is not necessary to specify the attribute when you want to append the spawned page at the end of the file. Form fields on the template page are not renamed when applied to the newly spawned page. The modified content is saved in optimized PDF format to a file called spawnAfter.pdf. If you have multiple templates in the same document that contain fields with the same name, you may want to rename the fields when you apply the template to a newly spawned page, in order to prevent field conflicts in the resulting document. You can do this by specifying a value of "rename" for the formFields attribute. The renaming convention used to rename form fields is described in the spawnPage entry in the Adobe Document Server Command Reference.

Adobe Document Server Developers Guide Dec 19, 2003 295 Manipulating Pages and Documents Inserting One Document into Another 14 Combining Documents

Combining Documents

You can combine two or more documents into a single document with two different ADS commands: ● You can combine two documents with the insertPages command. This command allows you to specify a location in a document into which to insert another entire document. For details, see the section “Inserting One Document into Another” on page 296. ● You can combine two or more documents with the assemblePDF command. This command appends documents to each other in the order you specify them. It gives you some control over page numbering and labeling and how bookmarks are combined in the new document. For details, see the section “Combining Multiple Documents into One” on page 298. Once you have combined multiple documents with either of these commands, you can generate a table of contents and include it in the resulting document with the createTOC command. This command gives you control over where in the document the table of contents is inserted, how many levels of entries appear in it, and how it should be formatted. For details, see the section “Creating and Inserting a Table of Contents” on page 303.

Inserting One Document into Another You can combine two PDF documents into one with the insertPages command. This command inserts all pages from one document into another at a specified location. You must load the document to be inserted into a named content holder, and provide this name for the source attribute. The document into which you are inserting is the current content. You can use the location attribute to specify where to insert the source document. This attribute takes two values as a string: the second specifies a particular page in the current content, and the first specifies whether the source document is inserted before or after that page. The existing page labels in the two files involved in this operation are not changed.

NOTE: The source document cannot be an XFA-based document. If the current content is XFA-based, the source document cannot contain form fields. The resulting document is XFA-based. In addition to inserting the pages from the source document into the current content, this command also copies other information from the source document: ● Annotations — All annotations from the source document are copied. ● Thumbnails — All thumbnails for pages from the source document are copied. ● Bookmarks — Existing bookmarks from the two documents are merged upon insertion. If both the source document and the current content contain bookmarks, the bookmark tree from the source document is inserted as the last child of the root bookmark in the current content. If you insert the source document in a location other than the end of the current content, the order in which the bookmarks are displayed in Acrobat will not match the

296 Dec 19, 2003 Adobe Document Server Developers Guide Inserting One Document into Another Manipulating Pages and Documents Combining Documents 14

actual order of the document contents. You may want to reorder the bookmarks in Acrobat to reflect the actual order of the contents. If the source document has bookmarks but the current content does not, the bookmark tree from the source document becomes the bookmark tree for the current content. ● Named destinations – Named destinations from the source document are copied. If the current content contains named destinations that conflict with those from the source document, the names from the source document are renamed, and actions and bookmarks that refer to those named destinations are modified. ● Logical structure — The logical document structure from the source document is copied into the current content. See the insertPages entry in the Adobe Document Server Command Reference for details. ● Form fields —Form fields from source documents are copied into the new document. If this results in more than one form field with the same name, those fields are treated as instances of the same field. If these duplicate fields have different values in the source document, the value of all the fields in the new document is taken from the first document that contained that field. This also applies to duplicate fields with different default values. ● JavaScript — JavaScript associated with form fields in the source document is copied into the current content, but document–level JavaScript is not copied.

NOTE: This command does not copy attribute objects or class map information from the source document into the current content. In order to insert an encrypted source document into another document, you must decrypt the source document with the master password before performing the insertion, or the insertPages command will not succeed.

EXAMPLE 14.8 Appending one document to another This example appends all pages from Chapter2.pdf to the current content, which was loaded from the file Chapter1.pdf. It saves the resulting combined chapters in a file called sampleInsertAppend.pdf. Since the default value of the location attribute is after last, it is not necessary to specify it in the insertPages command.

EXAMPLE 14.9 Prepending one document to another This example does the opposite of what Example 14.8 does; it combines the file contents from Chapter1.pdf and Chapter2.pdf, but puts the Chapter 2 content first. This time, the location attribute is set to "before 1". The result is saved in a file called sampleInsertPrepend.pdf.

Adobe Document Server Developers Guide Dec 19, 2003 297 Manipulating Pages and Documents Combining Multiple Documents into One 14 Combining Documents

EXAMPLE 14.10 Inserting pages before a specified page This example again inserts Chapter 2 into Chapter 1, but this time between pages 9 and 10 of Chapter 1. The location is specified using the before keyword.

EXAMPLE 14.11 Inserting pages after a specific page This example also inserts Chapter 2 into Chapter 1, but this time between pages 15 and 16 of Chapter 1. The location is specified using the after keyword.

Combining Multiple Documents into One You can create a PDF from one or more other PDF documents with the assemblePDF command. Unlike the insertPages command, the assemblePDF command can handle more than two documents at a time, but only allows you to append the documents to each other. It also give you control over what happens to the page labels and bookmarks when the files are combined into one. This command is an exception to the general rule that all ADS commands have both in and out attributes. The assemblePDF command only has the out attribute; it does not use the current content as a source of input. If the in attribute is inadvertently supplied, ADS ignores it and logs a warning message during processing. The input to this command is supplied in a series of document subelements, each one specifying named content that has already been loaded into ADS. These sources are appended to each other in the order in which you specify the document subelements. For each document to be combined, you specify the named content to append, whether or not the current page labels should be renumbered, and whether a new root bookmark is created, for that document.

298 Dec 19, 2003 Adobe Document Server Developers Guide Combining Multiple Documents into One Manipulating Pages and Documents Combining Documents 14

In addition to appending the document content you specify, this command retains other information from the documents: ● Annotations — All annotations from the source documents are retained in the combined document. ● Links — Existing links from each document are retained in the new document. Cross– document links between any of the documents being assembled are converted to internal links in the new document. Links are located using aliases if necessary. You can specify aliases for a source document with the alias subelement of the document element. ● Thumbnails —Thumbnails from the source documents are retained in the combined document, but if a source does not have thumbnails, none are generated for it. ● Bookmarks — Existing bookmarks from each document are retained in the new document. ● Named destinations – Named destinations from the source documents are copied into the new document. Any conflicts between named destinations across the set of files being assembled are resolved by changing the conflicting destination names. If renaming takes place, links and bookmarks that reference the renamed destinations are updated. ● Logical structure — The logical document structure from the source documents is not retained. The command creates a new document logical structure root and appends the top–level child of each source document’s root as a top–level child of the new document root. ● Attribute objects — Attribute objects in the source documents are copied into the new document, except for those that point to other PDF objects. ● Class maps — Class maps in the source documents are copied into the new document. Conflicts are resolved with a union of the referenced attribute objects. ● Form fields — Form fields from source documents are copied into the new document. If this results in more than one form field with the same name, those fields are treated as instances of the same field. If these duplicate fields have different values in the source document, the value of all the fields in the new document is taken from the first document that contained that field. This also applies to duplicate fields with different default values. ● JavaScript — JavaScript associated with form fields in the source document is retained for that field in the new document. Document–level JavaScript in the first document to be assembled is retained; document-level JavaScript in any of the other documents is not retained. ● Page labels — You have some control over what happens to page labels during assembly, using the labels attribute of the document element. If you want the existing page labels from the source document preserved as is, you set this attribute to preserve; this is the default. If you want to renumber the page labels, the only choice you have is to continue the numbering from the previous file; in this case, you set this attribute to continue. If you want to make any other changes to the page labels, either in style or in numbering, you can use the setPageLabels command on the newly assembled document. See “Renumbering Page Labels” on page 315.

Adobe Document Server Developers Guide Dec 19, 2003 299 Manipulating Pages and Documents Combining Multiple Documents into One 14 Combining Documents

NOTE: Only the first document you specify can be an XFA-based PDF document. None of the other documents can be XFA-based and they cannot contain form fields (AcroForms). The newly assembled document is XFA-based. If any of the source documents you are combining with the assemblePDF command are encrypted, you must decrypt them before assembly. Some restrictions apply when a file has both open and master passwords. If this is the case for the first file in the assembly list, you can decrypt it with the open password. If this is the case for any of the other files in the list, you must decrypt them with their master password.

EXAMPLE 14.12 Assembling multiple documents This example assembles six PDF documents into one optimized PDF file called assembleMe1.pdf.All of the source documents are first loaded into named content holders; the order in which you load these files does not matter. The files are then combined with the assemblePDF command. Here, the order in which the sources are listed does matter. Note that the first document listed for assembly preserves the page label numbering in the source, since there is no preceding document from which to continue the numbering. Since the default value for the labels attribute is preserve, you don’t have to explicitly set this attribute for the first source. The table of contents document, PressTOC.pdf, was previously generated in a desktop publishing application. For an example of generating and inserting a table of contents using an ADS command, see “Creating and Inserting a Table of Contents” on page 303.

300 Dec 19, 2003 Adobe Document Server Developers Guide Combining Multiple Documents into One Manipulating Pages and Documents Combining Documents 14

EXAMPLE 14.13 Creating new root bookmarks during assembly This example combines the same six files as the previous example, but this time it creates a new root bookmark for each document subelement. Notice that the optional bookmark attribute is specified for the sources in the assemblePDF command. Note that if the bookmark value string contains spaces, the new bookmark also contains spaces. Make sure you do not have any leading spaces in your strings. 1 2 3 5 7 9 11 13 15 16 18 20 22 24 26 28 29 30 31 The new root bookmarks for the commands are “TOC”, “Frontmatter”, and “Chapter”, from code lines 17, 19, 21, and 27 respectively. The destination page number of the new parent bookmark “TOC” is the same as the bookmark, “Table of Contents,” which is now a child bookmark of “TOC”. The Action Type for the new bookmark “TOC” is also the same as the child bookmark, which is Go To View in this example file. The destination for the new parent bookmark corresponds to the first page of the document subelement. The view for the bookmark is “fit page to window.” The bookmark is set to “open.”

Adobe Document Server Developers Guide Dec 19, 2003 301 Manipulating Pages and Documents Combining Multiple Documents into One 14 Combining Documents

EXAMPLE 14.14 Specifying an alias to resolve former references This example assembles the same six files as the other examples, but this time, it lists alternative names for the document in the alias subelement for each source document. Each document element can have multiple alias elements. The value for an alias element is a file name (see code lines 17, 19, 21, 22, etc.) or URI (see code line 19) that lists other names used in other documents to refer to the document. The alias element allows you to resolve any link references across the documents you are assembling. Any link to an alias resolves to an internal link in the new result document. For example, suppose you are assembling a document that contains multiple chapters. The various chapters are available on the Web as separate PDF files, and there are external links from one chapter to another. Now that these chapters are being assembled together in one single document, you want to remove the external links and replace them with internal links within the newly assembled file. You specify the external link to the assemblePDF command via the alias subelement. You need to have prior knowledge about the PDF files you are assembling to know the alias. One PDF file can have more than one alias if different chapters refer to the same file with different names, for example, if one chapter is named through a URI, and another is named through a filename on the local file system.

NOTE: Make sure that you do not have any leading or trailing spaces in the values for your alias subelements, since the spaces are not ignored. 1 2 3 5 7 9 11 13 15 16 17 TOC.pdf 18 19 http://www.writers.com/PrefaceTemplate.pdf 20 21 One.pdf 22 1.pdf 23 24 Two.pdf 25 2.pdf 26 27 Three.pdf 28 3.pdf

302 Dec 19, 2003 Adobe Document Server Developers Guide Creating and Inserting a Table of Contents Manipulating Pages and Documents Combining Documents 14

29 30 Indices.pdf 31 32 33

Creating and Inserting a Table of Contents You can generate a table of contents for the current PDF content and insert it into the content with the insertTOC command. This command is especially useful after you have assembled multiple PDF documents into one, and you want to include a table of contents for the combined result. You can also use this command to add a table of contents to any existing PDF content, regardless of its origin. The command uses bookmarks and page labels that exist in the PDF content to create the table of contents entries. You can specify which bookmarks are used with the levels attribute. If you don’t specify this attribute, all bookmarks are used. You can control where in the content the TOC is inserted with the location attribute. If you do not specify a location, the TOC is prepended to the current content. You must specify a Framemaker file (that has already been loaded into a named content holder) to be used to format the entries and page layout in the TOC with the template attribute. Verifying Bookmarks and Page Labels To ensure success when creating and inserting a table of contents, make sure that the PDF documents have the bookmark and page label information you need for your TOC: ● Bookmarks — You can visually inspect a PFD document in Acrobat or the Adobe Reader to see if a document has bookmarks appropriate to use for creating a TOC. You can also extract bookmarks from PFD content in ADS with the exportBookmarks command and inspect the output for the presence and suitability of bookmarks. For further information, see “Exporting Bookmarks” on page 270. If the document does not contain bookmarks, regenerate the PDF with an updated application, and make sure you enable the generate bookmarks option in the PDF setup options. Alternatively, you can add bookmarks manually within Acrobat.

NOTE: The insertTOC command does not create a bookmark for the TOC itself. If you want to include a bookmark for the generated TOC, you can add it manually in Acrobat. ● Page labels — You can open a PDF document in Acrobat and check for the presence of page labels in the Thumbnails view. Some older applications that create PDF files do not produce page label information. In this case, PDF viewers and processors assume arabic numbering beginning at 1. If the existing page labels in a PFD document are absent or not what you want, you can renumber the page labels with the setPageLabels command before generating a TOC. For more information, see “Renumbering Page Labels” on page 315.

Adobe Document Server Developers Guide Dec 19, 2003 303 Manipulating Pages and Documents Creating and Inserting a Table of Contents 14 Combining Documents

FrameMaker Templates for a Table of Contents The insertTOC command uses a FrameMaker file to format the TOC entries it creates. It uses paragraph styles from the template to format individual entries and page layout information from the Master pages to determine the TOC page layout. ADS includes a sample TOC template named SampleTOC.fm, located in your samples directory. The template is based on a standard US English portrait document template and provides paragraph styles for two levels of nesting. The first level has a bold font and is flush to the left page margin. The second level is a regular non-bold font and is indented from the left margin. The template defines a page sequence with left and right master pages. The numbering style for the page number is lowercase roman numeral. The default starting page number for the TOC itself is 3 (iii), since the assumption is that most documents have a title page for pages i and ii. If you design your own TOC template in FrameMaker, it must comply with the following restrictions: ● It must be saved in FrameMaker binary (.fm) or MIF (.mif) format. ● It must specify a starting page number that displays in the TOC document itself. This page number should match the number of the page at which the TOC is inserted in the insertTOC command. ● It must provide a paragraph style for each level of entry requested in the insertTOC command when the TOC is generated. The paragraph styles for a TOC entry are applied to the entire entry, from the start of the entry title to the end of the page label. The paragraph styles must be named TOC-###, where ### represents a three-digit level number that corresponds to the nesting level of the TOC entries. The style for the top level entries must be named TOC-001, the style for the second-level entries must be named TOC-002, and so on. Leading zero digits must be supplied to keep the level number 3 digits long. For further information on defining paragraph styles, refer to the FrameMaker documentation. ● It must specify the desired leader style if you want your TOC entry and the corresponding page labels separated by leader characters. The default behavior of the insertTOC command is to not use leaders.

304 Dec 19, 2003 Adobe Document Server Developers Guide Creating and Inserting a Table of Contents Manipulating Pages and Documents Combining Documents 14

EXAMPLE 14.15 Inserting a table of contents into an existing PDF document This example loads a MIF file and a PFD file and creates a TOC for the PDF content. It creates entries for all bookmarks and uses the MIF file to format the entries and determine the page layout. It prepends the resulting TOC to the PDF content and saves the result in an optimized PDF file called simpleInsert.pdf.

EXAMPLE 14.16 Inserting a table of contents in an assembled document This example creates a table of contents for a newly assembled PDF document, using a FrameMaker file called SampleTOC.fm as a template. Six files are combined with the assemblePDF command to form a new document for which a TOC is created. The TOC contains entries for the first and second level bookmarks only. Since the title and copyright page occupy the first two pages of the document, the TOC is inserted before page 3.

Adobe Document Server Developers Guide Dec 19, 2003 305 Manipulating Pages and Documents Rotating Pages 14 Changing Document Layout

Changing Document Layout

There are a number of ADS commands that allow you to modify aspects of the page layout in PFD content: ● You can change a page’s orientation with the rotatePages command. See “Rotating Pages” on page 306 for details. ● You can apply page contents from one page onto another with the overlayPages command. See “Applying Page Overlays” on page 308 for details. ● You can apply page contents from a template page onto a regular page with either the spawnPage or overlayTemplates command. See “Applying Template Overlays” on page 311 for details. ● You can change page labels for existing pages with the setPageLabels command. See “Renumbering Page Labels” on page 315 for details.

Rotating Pages You can rotate pages within a PDF document with the rotatePages command. Rotating pages is sometimes necessary after you combine documents that do not have the same orientation. You can rotate a single page, a range of pages, or all pages within an entire document. Text annotations do not rotate with a page, but remain in their original orientation. This command is useful for changing orientation from portrait (vertical) to landscape (horizontal) and vice versa. You can rotate pages only in positive or negative ninety degree increments. Positive rotation values rotate the pages clockwise; negative values rotate the pages counter-clockwise.

EXAMPLE 14.17 Rotating one page This example rotates one page (page four) of a document ninety degrees clockwise to convert from a portrait to a landscape orientation, and saves the result in a file called rotateOneSample.pdf.

306 Dec 19, 2003 Adobe Document Server Developers Guide Comparing the Overlay Commands Manipulating Pages and Documents Changing Document Layout 14

EXAMPLE 14.18 Rotating an entire document This example rotates all pages in the current content 90 degrees counter-clockwise and saves the result in a file called rotateAllSample.pdf. Because the default for the pages attribute is 1-last, it does not need to be specified here.

Comparing the Overlay Commands ADS provides two commands — overlayPages and overlayTemplates — that allow you to superimpose contents from one PDF document page onto another. The next two sections explain these two commands in detail. The following table compares their functionality so you can more easily decide when to use one or the other.

TABLE 14.1 Comparing the overlayPages and overlayTemplates commands

Feature overlayPages overlayTemplates Pages in target document All pages by default. Can be restricted. All pages by default. Can be restricted. (current content) that are affected Overlay source Any PDF file already loaded. Loaded PDF file containing one or more named template pages. Identified by name of content holder. Identified by name of content holder and template name. Can have multiple sources, which are Can have multiple sources and multiple used in cycles. templates in each source, which are used in cycles. Overlay over destination page Yes Yes Overlay under destination Yes No page Page or page range in overlay Page number or range. N/A. All templates are a single page. source

Can be used more than once. Can be used more than once. Can skip pages at regular intervals. Can designate a template to be used just once. Copy annotations from source No by default. Can be set to yes. No

Adobe Document Server Developers Guide Dec 19, 2003 307 Manipulating Pages and Documents Applying Page Overlays 14 Changing Document Layout

TABLE 14.1 Comparing the overlayPages and overlayTemplates commands

Feature overlayPages overlayTemplates Copy form fields from source No by default. Can be set to yes. Yes. Not filled on copy. Can be filled. Can specify field values. Not flattened on copy. Flattened after value is set on copy. Rotate, translate, and/or scale Not by default. Can be specified. No overlay page before applying JavaScript on form fields Preserved on copy. Executed before copy, but not used to calculate field value. Document-level JavaScript Discarded on copy. Discarded on copy. Thumbnails updated No No

Applying Page Overlays You can superimpose pages from a previously loaded document onto pages in the current content with the overlayPages command. You can superimpose the overlay pages either on top of or underneath the current content pages. Bookmarks and structures are not copied from overlay pages, but you can control whether annotations and form fields are copied. The document containing the overlay pages is called the source document.

NOTE: The source document cannot be an XFA-based document. If the current content is XFA-based, the source document cannot contain form fields. The resulting document is an XFA-based document. You can overlay a single page or a range of pages in the current content by specifying the pages attribute for the overlayPages command. The document containing the overlay pages is identified by the overlay subelement. Attributes of this element determine if the overlay pages are superimposed on top of or below the page contents of the current content pages (type), which page or pages in the source document are used as overlays (pages), if any pages in the overlay page range are to be skipped (skip), and whether annotations and form fields are copied from overlay pages (embed). The overlay element has its own subelement, transform, which you can use to adjust the size and placement of the overlay pages as they are applied to the current content. This element allows you to rotate, translate, and scale (in that order) the overlay pages. For further information, see the example “Applying a transform to an overlay page” on page 311. For best results, make sure that both the source document and the current contents have the same page size. If your overlay pages contain images, you cannot control the images’ opacity with the overlayPages command. If the images appear too dark after they are overlaid, adjust their opacity in the originating application such as Adobe Photoshop and regenerate the source PDF document. ADS does not update thumbnails after an overlay is done; you must update thumbnails using the updateThumbnails command. For further information, see “Annotations” on page 257.

308 Dec 19, 2003 Adobe Document Server Developers Guide Applying Page Overlays Manipulating Pages and Documents Changing Document Layout 14

EXAMPLE 14.19 Overlaying a single page This example overlays a single page document, Confidential.pdf, on top of each page of another document, Chapter1.pdf, and saves the result in an optimized PDF file called overlayPagesSingle.pdf after updating the thumbnails.

EXAMPLE 14.20 Overlaying multiple pages This example shows a more elaborate page overlay with multiple pages in both source and target documents, and page ranges specified. Pages 1-5 of the overlay document are superimposed onto the first 10 pages of the current content. The 5 pages of the overlay document are overlaid on the first 5 pages of the current content, and then the 5 overlay pages are used again on pages 6-10 of the current content. So, page 1 of the overlay document is overlaid onto pages 1 and 6 of the current content, page 2 of the overlay is overlaid onto pages 2 and 7 of the current content, and so on. When the overlay is complete, thumbnails are regenerated and the result is saved in an optimized PDF file called overlayMultiplePages.pdf.

EXAMPLE 14.21 Skipping pages in the overlay document This example applies every other page of the overlay document onto every page of the current content. It overlays page 1 of the overlay document onto page 1 of the current content, page 3 of the overlay document onto page 2 of the current content, and so on. If the last page of the overlay document is reached and there are still current content pages left, counting cycles back to the beginning of the overlay document. With a skip interval of 1, this means that for an overlay document with an even number of pages, only the odd-numbered pages would be used as overlays. For an overlay document with an odd number of pages, the first pass through the overlay document would apply the odd-numbered pages and the second pass through would

Adobe Document Server Developers Guide Dec 19, 2003 309 Manipulating Pages and Documents Applying Page Overlays 14 Changing Document Layout

apply the even-numbered pages, and so on, until all current content pages have had overlays applied to them.

EXAMPLE 14.22 Underlaying a page This example applies a single overlay page from sealTheDeal.pdf beneath the current content pages instead of over them. The type attribute for the overlay element is set to under to accomplish this. The overlay page is a graphic that shows behind the contents of the pages in the form named Expense.pdf. Once the overlay operation is complete, thumbnails are regenerated and the result is saved in an optimized PDF file called underlayPages.pdf.

EXAMPLE 14.23 Overlaying form fields and annotations This example uses the same two files as the previous example, but to different effect. The expense form is used as the overlay source, and the seal-the-deal graphic is the overlay target. The first page of the expense report is overlaid on the single page of the PDF graphic file. All form fields and annotations as well as the page contents from the expense report are copied on top of the graphic because the embed attribute of the overlay element is set to "annotations". Form fields are copied over as is, without flattening. If you need to flatten the fields, use the flattenFormFields command.

310 Dec 19, 2003 Adobe Document Server Developers Guide Applying Template Overlays Manipulating Pages and Documents Changing Document Layout 14

If you plan to apply a transform to a PDF form that you are overlaying onto another PDF document, be aware that the transformation is applied to the page contents only, and not to form fields and annotations. If you have graphical elements associated with a form field, as most forms do, a transformation (specified by the translate attribute of the transform element, which is a subelement of the overlay element) shifts these apart. For best results when overlaying PDF documents with form fields, either overlay a non-form PDF document onto the PDF form document; or make sure the objects are exactly where you want them in the original documents before you overlay them without a transform element.

EXAMPLE 14.24 Applying a transform to an overlay page This example shows how to use the transform attribute of the overlay subelement of the overlayPages command. The transform is applied to each overlay page before it is applied to the current content pages. The transform is applied to page contents only and not to form fields or annotations on the page. This example turns the seal-the-deal graphic upside down (the rotate attribute), shifts its position in the PDF default user coordinate space (the translate attribute), and shrinks it horizontally and vertically by 50% (the scale attribute) before applying it as an overlay to the pages in the expense report. Thumbnails are regenerated and the result is saved in an optimized PDF file called overlayPagesTransform.pdf. For best results in maintaining original proportions in a document that includes an image, scale the document by equal values.

Applying Template Overlays You can overlay Acrobat templates onto pages in a PDF document with the overlayTemplates command. The templates can contain form fields, graphics, text, or images, all of which are overlaid on top of the target page contents. This command enables you to use Acrobat templates to define repetitive page information, such as headers and footers. You can also use it to white out or mask content on a target document by either defining a form field with a white background, or creating a graphic with a matching fill color.

NOTE: This command cannot be used with XFA-based PDF files.

Adobe Document Server Developers Guide Dec 19, 2003 311 Manipulating Pages and Documents Applying Template Overlays 14 Changing Document Layout

Page contents from the template that are included in the overlay operation include: ● Graphics, text, and images. ● Form fields. If a template defines a default value for a field, and the field element value attribute is not set in the overlayTemplates command, the default form field value is used. If there is neither a default nor a value set, the form field is left blank. All fields are flattened on the target page. ● Form-level JavaScript. It is executed before fields are flattened. Page contents from the template that are not included in the overlay operation include: ● Links and other annotations. ● Document-level JavaScript. Thumbnails are not updated by this command; you must update thumbnails using the updateThumbnails command. For further information, see “Updating Thumbnails” on page 271. Creating Overlay Templates The overlayTemplates command uses PDF templates that contain custom-defined form fields for the overlay. To create a template for use with the overlayTemplates command: 1. Create a document with any static content that suits your overlay needs, using the word processing application of your choice, such as Adobe FrameMaker or Microsoft Word. You can include graphics and static text on the template, or the template can be blank. The template document should be the same page size and orientation as the document you plan to overlay. 2. Save the document as a PDF file, using Distiller or another PDF generator. 3. Create text form fields to accommodate the variable overlay information, using the Acrobat form tool. Click and drag the form tool in the desired location. To assist with precision when placing form fields, use the View> Navigation Tabs > Info tool in Acrobat set to the measurements you use in the document. You can opt for inches, millimeters, or points with the Info tool. For additional assistance with creating form fields, refer to the Acrobat online help. Make a note of the names used for the form fields, since you may use the field names within your commands. There is usually some trial and error associated with properly placing form fields. 4. Add the page (or pages) you have created as a named template by choosing Advanced > Forms > Page Templates. Make sure you are on the page you want to define as a document template, since there is a 1:1 correspondence between a page and a template within a PDF document. Type the template name in the Name box and click Add. Confirm the operation by clicking Yes and Done. Make a note of the template names for use in your commands. Populating Template Form Fields The text form fields you want to populate can contain either static text or variables for dynamic information within a PDF template, such as page numbers within a running header or footer.

312 Dec 19, 2003 Adobe Document Server Developers Guide Applying Template Overlays Manipulating Pages and Documents Changing Document Layout 14

Variables are marked by percent signs (%) and can either be standard or user-defined docInfo properties, or predefined attribute values. You can populate template text form fields with the desired overlay text in any of the following ways: ● By defining literal static strings for a form value within a set of commands, for example, . ● By using standard or user defined document information (docInfo) properties, for example, %docInfo.Title%. The docInfo static name is separated by a period from the docInfo property. The docInfo can be either standard or user-defined via the metadata commands in ADS. The properties allow for dynamic information within form fields. ● By using the predefined attributes built into the overlayTemplates command. These variables allow for dynamic information within form fields. Standard Document Information (docInfo) Properties Document metadata is information about the document itself that is not part of the content. The main purpose of this metadata is to assist in cataloging and searching document databases. A PDF document contains standard metadata, either as properties in a document information dictionary or in a metadata stream. The document information dictionary is located in the trailer of a PDF file. Acrobat viewers display the metadata for a document in the Document Properties dialog box. To view document metadata in Acrobat, choose File > Document Properties > Description. Some property values, such as title, author, subject, keywords, and some trapping information, are manually entered by a user. Other property values, such as creator, producer, and date, are set by Acrobat. A property value can be a static value or a variable. There is a limit of 255 bytes on any string representing a document metadata value. You can use the following standard docInfo properties as variables in your property values:

Document information Description %docInfo.Title% The document’s title. %docInfo.Author% Author of the document. %docInfo.Subject% The document’s subject. %docInfo.Keywords% Any keywords associated with the document. %docInfo.Creator% The name of the application, such as Adobe FrameMaker, that created the original document that was converted to PDF. %docInfo.Producer% The name of the application, such as Acrobat Distiller, that converted the original document to PDF. %docInfo.CreationDate% The date and time the document was created. %docInfo.ModDate% The date and time the document was last modified. %docInfo.Trapped% Any included trapping information; value can be True, False, or Unknown.

Adobe Document Server Developers Guide Dec 19, 2003 313 Manipulating Pages and Documents Applying Template Overlays 14 Changing Document Layout

For further information on the document information dictionary, refer to the PDF Reference version 1.4. For information on defining your own metadata for use as docInfo, refer to Chapter 4, “Working with File Metadata.” Predefined Field Values The following predefined form field attribute values are available for you to use with the overlayTemplates command: ● %pageLabel% ● %lastPageLabel% ● %pageNumber% ● %totalPages% The variables are delimited with percent (%) characters, and are fairly self-explanatory. The variables are replaced with the actual values in the destination document.

NOTE: If page labels do not exist or have not been set using the setPageLabels command, the page index is used instead. For further details on form field variables specially defined for this command, refer to the Adobe Document Server Command Reference.

EXAMPLE 14.25 Overlaying multiple templates This example overlays three templates defined in a single PDF file onto all pages of another PDF document. The first template is used only once (line 7), on the first page of the current content. The other two templates are used repeatedly on alternate pages of the current content. These templates provide a double-sided (right and left pages) layout with a special first page. After the overlay is complete, thumbnails are regenerated and the result is saved to a PDF file. You can define literal static strings for a form value. For example, code line 8 places a header with the literal string “Beta Draft” at the top of the first page. Since the firstPage template is only used once, the string only appears once on the first page of the document. There are also predefined variables available for you to use with the overlayTemplates command. Code lines 10, 19, and 24 demonstrate the use of the predefined values %pageNumber% of %totalPages%. Notice that you can mix the predefined names with character data (“of”) within a field value. Code lines 11 through 14 provide a draft creation and modification date for the document, using standard document information (docInfo) pulled from the metadata of the PDF document. A form field uses the style defined in the template, so for a particular date format, use the form field definition in Acrobat to set this as you desire.

TIP: To set a date format in Acrobat, choose the Format tab in the Field Properties dialog box. In the Form Category list, choose Date, and in the Date Options box, choose the date format you want. The draft date appears in every template: first, even, and odd, and therefore, the date appears on every page of the result document.

314 Dec 19, 2003 Adobe Document Server Developers Guide Renumbering Page Labels Manipulating Pages and Documents Changing Document Layout 14

1 2 3 4 5 6 7 16 21 26 27 28 29 30

NOTE: You can also apply a template to an existing page with the spawnPage comment, if you set its location attribute to over. When you do this, you can choose whether to rename form fields when they are copied from the template page. See the spawnPage command in the Adobe Document Server Command Reference.

Renumbering Page Labels A page in a PDF document can be identified in two ways: ● By its page index — A number that reflects the page’s relative position in the document. You can see this number displayed in the status bar at the bottom of the Acrobat window when viewing a file, for example, 6 of 14. ● By its page label — An optional string label that appears on the page itself when displayed or printed. It also appears below the thumbnail for that page and in the status bar. For example, a document may have 35 pages of front matter. The page label for the first page of the first chapter could be ‘1’ while the page index is 36. The page label is shown first in the status bar, followed by the page index and the total number of pages in the document, for example, 1 (35 of 345). When you type a number in

Adobe Document Server Developers Guide Dec 19, 2003 315 Manipulating Pages and Documents Renumbering Page Labels 14 Changing Document Layout

the status bar or the Go To Page dialog, it is interpreted as a page label if page labels exist in the document. Some of the operations discussed in this chapter change the number or order of pages in a PDF document. If you need to renumber the page labels after such an operation, you can do so with the setPageLabels command. You can renumber page labels for a selected page or a range of pages. Empty page labels can result if any page labels are not explicitly labeled in the setPageLabels command. Once page labels are set within a PDF document, all pages in the document have page labels based on how the PDF 1.5 specification defines page labels. Therefore, in a document that does not have page labels, any pages not explicitly labeled within the setPageLabels command are labeled with empty page labels. This command corresponds to Options > Number Pages from the Pages tab in the Acrobat navigation pane. It is particularly useful when used in conjunction with assembling a PDF document from multiple PDF documents, and generating and inserting a table of contents. Numbering Styles The numbering style for page labels is set with the style attribute for the setPageLabels command. This attribute can have the following values:

decimal Arabic integers (1, 2, 3). This is the default style if you do not specify the style attribute. upperRoman Uppercase Roman numerals (I, II, III) lowerRoman Lowercase Roman numerals (i, ii, iii) upperAlpha Uppercase alphabetic (A, B, C) lowerAlpha Lowercase alphabetic (a, b, c)

Prefixes Page labels can also include an optional text string specified with the prefix attribute. You must manually set the proper spacing you desire after the prefix. For example, if you use a string such as “Page” for a prefix, you must add a blank space after the string. You can customize the numbering system with prefixes. For example, you can set the prefix for the first chapter to prefix="1-" so that the numbering for chapter 1 appears as 1-1, 1-2, 1-3, and so on, and you can set the prefix for the second chapter to prefix="2-" so that the numbering for chapter 2 appears as 2-1, 2-2, 2-3, and so on.

EXAMPLE 14.26 Renumbering page labels This example renumbers page labels for all pages in the current content from their current styles to all uppercase Roman numerals. The renumbered contents are saved in a file called renumberMe1.pdf.

316 Dec 19, 2003 Adobe Document Server Developers Guide Renumbering Page Labels Manipulating Pages and Documents Changing Document Layout 14

EXAMPLE 14.27 Renumbering page labels after assembling a new document This example loads the document assembled in the example “A s s e m b l i n g m u l t i p l e d o c u m e n t s” on page 300. It calls setPageLabels twice: once to number the first four pages with lowercase Roman numerals, and again to label the remaining pages with Arabic numerals starting with 1. All page labels are preceded by the string “Page ”. The relabelled content is saved in a file called renumberMe2.pdf.

Adobe Document Server Developers Guide Dec 19, 2003 317 Manipulating Pages and Documents Renumbering Page Labels 14 Changing Document Layout

318 Dec 19, 2003 Adobe Document Server Developers Guide Converting and Saving PDF 15 Documents

This chapter describes the format conversions you can apply to PDF content. The chapter contains the following sections:

Overview starting on page 319 Converting Between Document Formats starting on page 320 Converting Between PDF and Image Formats starting on page 321 Saving Optimized PDF Content starting on page 322

Overview

ADS provides commands that allow you to perform explicit conversions that transform content among the supported image formats and document formats. There are commands to convert: ● PostScript content to PDF content, and PDF to PostScript ● PDF or PostScript content to Raster content ● Raster content to PostScript or PDF content ● SVG content to PDF content You can combine these conversions to achieve transformations for which there is no explicit command; for example, you can convert SVG to PDF, then convert the PDF to PostScript. Content is transformed to various file formats when you save it from ADS. You can combine content type conversions with each other and with other command sequences to achieve the transformation you want. For example, you can convert PDF to Raster, then use setFileFormat to mark the Raster content so that it is transformed to the TIFF format on save. For a summary of file and content format conversions and transformations, see Chapter 3, “ADS Command Basics.” When you save PDF content directly, you can choose to save in a standard PDF file format, or a Web-optimized PDF format.

Adobe Document Server Developers Guide Dec 19, 2003 319 Converting and Saving PDF Documents 15 Converting Between Document Formats

Converting Between Document Formats

ADS allows you to load and save documents in the PDF and PostScript formats. You can manipulate only PDF content, not PostScript content. However, you can convert loaded PostScript to PDF format and then manipulate the content, or you can manipulate PDF content then convert it to PostScript before saving it. ● Convert PostScript content to PDF format with the convertPSToPDF command. This command is the equivalent of sending the PostScript file to Acrobat Distiller. ● Convert PDF content to encapsulated PostScript (EPS) format with the convertPDFToEPS command. This command corresponds to the Acrobat File > Save As EPS command. The EPS format is Level 2 PostScript with full PostScript Document Structuring Conventions (DSC) comments. Any transparency in the PDF document is flattened. All fonts that can be embedded are embedded. You can convert one page at a time to EPS. If you are creating EPS files for separations, all image color spaces should be CMYK.

NOTE: ADS does not support XMP metadata in the PostScript or EPS file formats. For a mapping from DSC to XMP, see the Adobe Document Server Command Reference.

EXAMPLE 15.1 Converting PDF to EPS This example converts page 2 of the loaded PDF document to EPS and generates a preview image in a Windows device-dependent format, and saves the result as a new EPS file.

EXAMPLE 15.2 Converting PostScript to PDF This example converts the loaded PostScript document to PDF using the Distiller options set that optimizes for commercial printing, and saves the result as a new PostScript file.

For details of the convertPDFToEPS and convertPSToPDF commands and their attributes, see the Adobe Document Server Command Reference.

320 Dec 19, 2003 Adobe Document Server Developers Guide Converting and Saving PDF Documents Converting Between PDF and Image Formats 15

Converting Between PDF and Image Formats

You can convert a single page of PDF content to the Raster image format using the convertPDFToRaster command. The resulting Raster content has a single, unnamed layer and is marked to be saved as PSD. You can use image commands to manipulate the Raster content; see Chapter 5, “Basic Image Manipulations.” In particular, you can use the setFileFormat and set commands to change the save format. For details, see “Saving Optimized Files” on page 112. The convertPDFToRaster command takes a cropBox attribute that specifies a rectangle to which to crop the PDF image. The values are in Acrobat user units (1/72 inches). For example: Be careful to take into account the fact that the user unit is different from the default Raster pixel size of 1/96 inch. In the preceding example, you might expect a width of 30 pixels (126-96), and a height of 176 pixels (242-66). However, the size is calculated using the PDF document resolution first, then translated to the image resolution. This results in a Raster image that is 40 x 235 pixels at 96 DPI. You can convert Raster content to PDF format using the convertRasterToPDF command; see “Accessing Raster Content” on page 109. You can also convert SVG content to PDF using the convertSVGToPDF command; see Chapter 8, “Operations Specific to SVG Files.” For details of the conversion commands and their attributes, see the Adobe Document Server Command Reference.

EXAMPLE 15.3 Converting a PDF document to TIFF format This example converts the second page of the loaded PDF document to the Raster format, then marks the resulting Raster content to be saved as TIFF. It writes the result to a new TIFF file.

Adobe Document Server Developers Guide Dec 19, 2003 321 Converting and Saving PDF Documents 15 Saving Optimized PDF Content

Saving Optimized PDF Content

When you save PDF content, you can choose to save to a standard or Web-optimized format. ● If you plan to deliver a PDF document to be printed, use the saveContent command to save the PDF content. This writes a PDF version 1.4 file. ● If you plan to deliver a PDF document that will be accessed from a Web server, use the saveOptimized command to save in Web-optimized format. It takes longer to save an optimized PDF file. The saveOptimized command writes a Web-optimized PDF file using the Fast Web View options. Web-optimized, or linearized PDF is optimized for viewing read-only PDF documents on screen. Optimization consolidates and reorders internal objects within PDF documents to facilitate downloading a page at a time. Enhanced viewer applications recognize linearized PDF files and take advantage of the internal organization to display the content more quickly, sending only the requested page to the client, not the entire PDF document. Optimization can also reduce file size significantly.

NOTE: If you modify a linearized PDF document, the resulting PDF is no longer linearized.

EXAMPLE 15.4 Saving a Web-optimized PDF document

For further details about the saveContent and saveOptimized commands and their attributes, refer to the Adobe Document Server Command Reference.

322 Dec 19, 2003 Adobe Document Server Developers Guide A Example-to-Sample Mapping

This appendix contains a table that shows the mapping between the examples in this document and the samples in the samples directory. The corresponding samples may not exactly match the documentation, but will provide a working sample demonstrating a similar operation. All paths for sample files are relative to the ADS samples directory.

TABLE A.1 Examples in this document that map to working samples

Example # and page Example title Corresponding sample Example 4.4 Modifying a metadata ImageManipulation/commands/setMetadata.xml page 74 property Example 4.5 Creating and adding to a ImageManipulation/commands/appendMetadata.xml page 75 structured property ImageManipulation/commands/setMetadata1.xml Example 4.6 Streaming in replacement PDFManipulation/commands/importMetadata.xml page 76 metadata in the importMetadata command Example 4.7 Loading replacement PDFManipulation/commands/importMetadata1.xml page 76 metadata from a file Example 4.8 Copying metadata from ImageManipulation/commands/importMetadata2.xml page 77 one file to another Example 4.9 Saving an optimized image ImageManipulation/tasks/saveOptimization_metadata.xml page 78 with a new metadata property Example 5.1 Increasing canvas size by ImageManipulation/commands/canvasSize1.xml page 89 adding a border Example 5.2 Trimming an image ImageManipulation/commands/trim.xml page 89 ImageManipulation/commands/trim1.xml Example 5.3 Applying a clipping path ImageManipulation/commands/applyClipPath.xml page 90 Example 5.4 Making successive size ImageManipulation/commands/imageSize.xml page 91 modifications on the same image Example 5.5 Changing the resolution of ImageManipulation/tasks/changeResolution.xml page 91 an image Example 5.7 Resizing an image and ImageManipulation/tasks/ResizeSharpen.xml page 95 sharpening edges

Adobe Document Server Developers Guide Dec 19, 2003 323 Example-to-Sample Mapping A

TABLE A.1 Examples in this document that map to working samples

Example # and page Example title Corresponding sample Example 5.8 Setting layer and layer-set ImageManipulation/commands/set_Visibility.xml page 97 visibility Example 5.9 Setting layer opacity ImageManipulation/commands/set_Opacity.xml page 97 Example 5.10 Converting image data to a ImageManipulation/commands/convertProfile2.xml page 101 color profile Example 5.11 Rotating an image ImageManipulation/commands/rotate1.xml page 103 Example 5.12 Replacing pixels to add a ImageManipulation/commands/replacePixels1.xml page 105 product shot to an image Example 5.13 Duplicating one pixel layer ImageManipulation/tasks/duplicatePixelLayer.xml page 105 out of several layers Example 5.14 Applying a layer effect by ImageManipulation/tasks/addDropShadow.xml page 105 replacing pixels Example 5.15 Replacing a color overlay ImageManipulation/tasks/replaceColorOverlay.xml page 107 in an image layer Example 5.16 Automatically adjusting ImageManipulation/commands/autoContrast.xml page 108 contrast in an image Example 5.20 Changing the preferred ImageManipulation/commands/set_OptimizationSettings page 114 optimization format with set Example 5.21 Choosing an optimization ImageManipulation/commands/optimizeToSize1.xml page 114 format automatically Example 5.22 Adjusting the quality of an ImageManipulation/commands/set_OptimizationSettings.xml page 115 optimized file Example 6.1 Replacing all text in a layer ImageManipulation/commands/replaceText1.xml page 120 Example 6.2 Replacing specific text in a ImageManipulation/commands/replaceText1.xml page 120 layer Example 6.4 Replacing text in an SVG ImageManipulation/commands/set_SVG1.xml page 122 text flow Example 6.5 Replacing an entire text ImageManipulation/commands/set_SVG1.xml page 122 flow in SVG content Example 6.8 Changing the overlay color ImageManipulation/tasks/replaceColorOverlay.xml page 128 in a text layer

324 Dec 19, 2003 Adobe Document Server Developers Guide Example-to-Sample Mapping A

TABLE A.1 Examples in this document that map to working samples

Example # and page Example title Corresponding sample Example 6.10 Replacing text flow ImageManipulation/commands/set_SVG1 page 130 attributes in SVG content Example 7.1 Automatic variable ImageManipulation/commands/applyVariables1.xml page 134 replacement on load Example 7.3 Loading multiple data sets ImageManipulation/commands/applyVariables1.xml page 135 for a single template file Example 7.4 Streaming in replacement ImageManipulation/commands/applyVariables.xml page 135 data Example 7.5 Basic variable replacement ImageManipulation/commands/applyVariables.xml page 137 Example 7.7 Replacing an image ImageManipulation/commands/applyVariables.xml page 138 variable with an image file reference Example 7.9 Replacing a graph variable ImageManipulation/test_files/templates/column_data.xml page 139 ImageManipulation/tasks/DynamicGraph.xml Example 7.14 Replacing a text variable ImageManipulation/commands/applyVariables.xml page 142 Example 7.15 Replacing a pixel variable ImageManipulation/commands/applyVariables.xml page 142 using a file reference Example 7.17 Replacing the default text ImageManipulation/commands/applyVariables2.xml page 143 variable Example 9.2 The values element ImageManipulation/test_files/templates/column_data.xml page 172 Example 9.3 The propertyRow element ImageManipulation/test_files/templates/column_data.xml page 173 Example 9.11 A data element with an ImageManipulation/test_files/templates/column_data.xml page 177 implicit map Example 10.2 Using ext-fo:fragment- XSL-FO/templates/fragment-root/fragment-root_tpl.xml page 231 root Example 10.3 Command file without a XSL-FO/elements/block/block.xml page 232 FrameMaker template Example 10.4 Basic XSL-FO document XSL/fo/elements/simple-page-master/simple-page-master.xml page 232 with a single page master Example 10.5 XSL-FO document with XSL-FO/elements/region-after/region-after.xml page 233 different regions XSL-FO/elements/region-before/region-before.xml

Adobe Document Server Developers Guide Dec 19, 2003 325 Example-to-Sample Mapping A

TABLE A.1 Examples in this document that map to working samples

Example # and page Example title Corresponding sample Example 10.6 Running headers and XSL-FO/elements/marker/marker.xml page 236 footers without a FrameMaker template Example 10.7 Balancing text across XSL-FO/attributes/column-balancing/column-balancing.xml page 237 columns Example 10.8 Generating page # of ## XSL-FO/elements/page-number-last-citation/page-number- page 238 folios last-citation.xml Example 10.9 Embedding graphics in an XSL-FO/elements/instream-foreign-object/instream-foreign- page 240 XSL-FO document object.xml Example 10.10 Defining variables in an XSL-FO/elements/define-variable/define-variable.xml page 241 XSL-FO document Example 10.11 XMP metadata in XSL-FO XSL-FO/elements/metadata/metadata.xml page 242 using fo:root Example 11.1 Encrypting a PDF PDFManipulation/commands/encryptSample4.xml page 248 document with an open password Example 11.3 Encrypting a PDF file with PDFManipulation/commands/encryptSample3.xml page 249 permissions and both passwords Example 11.4 Decrypting a PDF PDFManipulation/commands/thumbsUp.xml page 250 document with a master password Example 11.6 Enabling all usage rights PDFManipulation/commands/setSampleUsageRights.xml/ page 252 Example 11.8 Setting usage rights and PDFManipulation/commands/encryptUsage.xml page 254 encryption permissions

Example 11.9 Setting usage rights and PDFManipulation/commands/encryptSample2.xml page 254 resetting encryption Example 12.2 Exporting comments in PDFManipulation/commands/exportAnnotsXFDF.xml page 262 the XFDF format Example 12.3 Importing comments in PDFManipulation/commands/importAnnots.xml page 262 XFDF format Example 12.4 Merging comments from PDFManipulation/commands/mergeAnnots.xml page 263 one source Example 12.6 Deleting all comments PDFManipulation/commands/deleteAllAnnots.xml page 264

326 Dec 19, 2003 Adobe Document Server Developers Guide Example-to-Sample Mapping A

TABLE A.1 Examples in this document that map to working samples

Example # and page Example title Corresponding sample Example 12.8 Deleting a specific type of PDFManipulation/commands/deleteAnnotsByType.xml page 265 comment Example 12.12 Deleting comments by PDFManipulation/commands/deleteAnnotsMultipleAuthors.xml page 266 multiple authors Example 12.15 Exporting bookmarks PDFManipulation/commands/exportBookmarks.xml page 270 Example 12.16 Updating thumbnails PDFManipulation/commands/thumbsUp.xml page 272 Example 12.17 Deleting thumbnails PDFManipulation/commands/allThumbs.xml page 273 Example 12.18 Importing data for a file PDFManipulation/commands/importNativeDataObject.xml page 275 attachment from a content holder Example 12.19 Importing data for a file PDFManipulation/commands/importForeignDataObject.xml page 275 attachment from an external file Example 12.20 Exporting a file PDFManipulation/commands/exportDataObjectContent.xml page 276 attachment into a content holder Example 12.21 Exporting a file PDFManipulation/commands/exportDataObjectExternal.xml page 277 attachment into an external file Example 12.22 Deleting a file attachment PDFManipulation/commands/deleteDataObject.xml page 277 Example 13.1 Providing values for text PDFManipulation/commands/setFormFieldValues.xml page 281 form fields directly Example 13.2 Exporting form data to PDFManipulation/commands/exportFDF.xml page 282 FDF format Example 13.3 Exporting form data to PDFManipulation/commands/exportXFDF.xml page 282 XFDF format Example 13.4 Importing form data PDFManipulation/commands/importFDF.xml page 283 Example 13.5 Exporting and importing PDFManipulation/commands/exportImportPipeFDF.xml page 283 together Example 13.6 Changing the appearance PDFManipulation/commands/setFormFieldSkin.xml page 284 of a form field

Adobe Document Server Developers Guide Dec 19, 2003 327 Example-to-Sample Mapping A

TABLE A.1 Examples in this document that map to working samples

Example # and page Example title Corresponding sample Example 13.7 Changing the style of a PDFManipulation/commands/setFormFieldGlyphs.xml page 285 check box or radio button Example 13.8 Replacing a button’s icon PDFManipulation/commands/setFormFieldButton.xml page 285 and caption Example 13.9 Hiding a form field PDFManipulation/commands/setFormFieldHide.xml page 286 Example 13.10 Restricting write access for PDFManipulation/commands/setFormFieldReadOnly.xml page 287 form fields Example 13.13 Flattening certain form PDFManipulation/commands/flattenSomeFormFields.xml page 288 fields by inclusion Example 13.14 Flattening certain form PDFManipulation/commands/doNotFlattenFormFields.xml page 289 fields by exclusion Example 13.15 Deleting specific form PDFManipulation/commands/deleteFormFields.xml page 289 fields Example 14.1 Deleting the first page of a PDFManipulation/commands/deleteFirstPage.xml page 292 document Example 14.2 Deleting the last page of a PDFManipulation/commands/deleteLastPage.xml page 292 document Example 14.3 Deleting a specified range PDFManipulation/commands/deletePageRange.xml page 293 of pages Example 14.5 Deleting all but one page PDFManipulation/commands/deleteAllButOnePage.xml page 293 Example 14.6 Forcing an even number of PDFManipulation/commands/forceEvenPages.xml page 294 pages Example 14.7 Appending a spawned PDFManipulation/commands/spawnPageAppend.xml page 295 page Example 14.8 Appending one document PDFManipulation/commands/insertPagesAppend.xml page 297 to another Example 14.9 Prepending one document PDFManipulation/commands/insertPagesPrepend.xml page 297 to another Example 14.12 Assembling multiple PDFManipulation/commands/assemblePDF.xml page 300 documents Example 14.13 Creating new root PDFManipulation/tasks/assemblePDFbookmark.xml page 301 bookmarks during assembly

328 Dec 19, 2003 Adobe Document Server Developers Guide Example-to-Sample Mapping A

TABLE A.1 Examples in this document that map to working samples

Example # and page Example title Corresponding sample Example 14.14 Specifying an alias to PDFManipulation/tasks/assemblePDFalias.xml page 302 resolve former references Example 14.15 Inserting a table of PDFManipulation/commands/insertTOC.xml page 305 contents into an existing PDF document Example 14.16 Inserting a table of PDFManipulation/commands/insertTOCassemblePDF.xml page 305 contents in an assembled document Example 14.17 Rotating one page PDFManipulation/commands/rotateOnePage.xml page 306 Example 14.18 Rotating an entire PDFManipulation/commands/rotateAllPages.xml page 307 document Example 14.19 Overlaying a single page PDFManipulation/commands/overlayPagesSingle.xml page 309 Example 14.20 Overlaying multiple pages PDFManipulation/commands/overlayPagesMultiple.xml page 309 Example 14.22 Underlaying a page PDFManipulation/commands/overlayPagesUnder.xml page 310 Example 14.23 Overlaying form fields and PDFManipulation/commands/overlayPagesAnnots.xml page 310 annotations Example 14.24 Applying a transform to an PDFManipulation/commands/overlayPagesTransform.xml page 311 overlay page Example 14.26 Renumbering page labels PDFManipulation/commands/renumberPageLabels1.xml page 316 Example 14.27 Renumbering page labels PDFManipulation/commands/renumberPageLabels2.xml page 317 after assembling a new document Example 15.1 Converting PDF to EPS PDFManipulation/commands/convertPDFtoEPS.xml page 320 Example 15.2 Converting PostScript to PDFManipulation/commands/convertPStoPDF.xml page 320 PDF

Adobe Document Server Developers Guide Dec 19, 2003 329 Example-to-Sample Mapping A

330 Dec 19, 2003 Adobe Document Server Developers Guide Index

ABCDEF GHI J KL MNOP QRS TUVWXYZ

A changeApplyDesign element 188 fitBox attribute 188 abbreviated graph data syntax 178 changeDelete element 188 accumulation attribute 167 changeGraphicStyle element 188 action types 267 changeHide element 188 AlterCast changeStacking element 188 saving files 59, 63 changeTextStyle element 188 annotations 261 changeTransform element 188 deleting 264 clipping paths 89 area graph 162 cluster 158 assemblePDF command 298 column graph 162 attribute command accumulation 167 assemblePDF 298 base 182 convertPDFToEPS 320 fitBox 188 convertPDFToRaster 321 hasSubstitution 188 convertPSToPDF 320 normalizedStackTotal 166 decryptPDF 249 postdecimal 188 deleteComments 264 predecimal 188 deleteDataObject 277 repeat 182 deleteFormFields 289 sliceValue 188 deleteLinks 269 stacking 161 deletePages 292 automatic file saving 59, 63 deleteThumbnails 272 axis encryptPDF 245 major 158 exportComments 261 minor 158 exportDataObject 276 axis element 180 exportFormData 282 exportLinks 267 B flattenForm 287 flattenFormFields 287 bar graph 162 forceEvenPages 294 base attribute 182 getUsageRights 255 bookmarks 269 importFormData 282 exporting 270 insertPages 296 insertTOC 303 C overlayPages 308 overlayTemplates 311 calculated element 182 RotatePages 306 cartesian saveContent 59 graph layout 161 saveOptimized 59, 63, 322 change element 188

Adobe Document Server Developers Guide 331 ABCDEF GHI J KL MNOP QRS TUVWXYZ

command (Continued) difference element 187 setPageLabels 316 docInfo setUsageRights 251 standard variables 313 spawnPages 295 document updateThumbnails 272 encrypting 245 comments getting usage rights 255 deleting 264 setting usage rights 251 exporting 261 documents importing 261 decrypting 249 merging 262 converting PDF to and from PostScript 320 E PDF to raster 321 element convertPDFToEPS command 320 axis 180 convertPDFToRaster command 321 calculated 182 convertPSToPDF command 320 change 188 creating changeApplyDesign 188 overlay templates 312 changeDelete 188 changeGraphicStyle 188 changeHide 188 D changeStacking 188 data changeTextStyle 188 abbreviated graph syntax 178 changeTransform 188 data element 172 data 172 data objects diference 187 deleting 277 format 179 exporting 276 graphDesc 180 importing 274 intersection 187 data sets 169 labelString 189 decrypting legend 180 documents 249 majorAxis 179 decryptPDF command 249 map 173 deleteComments command 264 minorAxis 179 deleteDataObject command 277 other 182 deleteFormFields command 289 property 173 deleteLinks command 269 property row 172 deletePages command 292 symbol 188 deleteThumbnails command 272 union 187 deleting values 172 annotations 264 valueSubstitution 188 comments 264 what 186 data objects 277 which 186 graph component 188 xform 186 links 269 xforms 180 thumbnails 272

332 Adobe Document Server Developers Guide ABCDEF GHI J KL MNOPQRS TUVWXYZ

embedded graph fonts in SVG 148 abbreviated data syntax 178 encrypting area 162 document 245 axis element 180 encryptPDF command 245 bar 162 EPS cartesian 161 converting to and from PDF 320 change stack positions 188 exportComments command 261 cluster 158 exportDataObject command 276 column 162 exportFormData command 282 data element 172 exporting design art 188 bookmarks 270 difference element 187 comments 261 format element 179 data objects 276 graphDesc element 180 links 267 intersection element 187 exportLinks command 267 legend 158 legend element 180 lenient mode 192 F line 162 Fast Web View 322 major axis 158 FDF 261 majorAxis element 179 files minor axis 158 saving 59 minorAxis element 179 saving in optimized format 59, 63 normalized 161 fitBox attribute 188 other element 182 flattenForm command 287 pie 162 flattenFormFields command 287 polar layout 161 fonts properties 171 embedded in SVG 148 property row element 172 forceEvenPages command 294 radar 162 forcing even pages 294 scatter 162 format element 179 series 158 formats 59, 63 showing or hiding a component of 188 formfields sliding a design 188 populating overlay template 312 stacked 161 stacked bar 162 stacked column 162 G strict mode 192 generating symbol element 188 TOC 303 union element 187 getting unstacked 161 usage rights 255 what element 186 getUsageRights command 255 which element 186 xforms element 180 graphDesc element 180

Adobe Document Server Developers Guide 333 ABCDEF GHI J KL MNOP QRS TUVWXYZ

H N hasSubstitution attribute 188 normalized graph 161 hiding normalizedStackTotal attribute 166 graph component 188 numbering pages 315 I importFormData command 282 O importing objects comments 261 deleting data 277 data objects 274 exporting data 276 inserting importing data 274 pages 292 optimized insertPages command 296 saving PDF 322 insertTOC command 303 optimized file formats 59, 63 intersection element 187 other element 182 overlay creating templates 312 L overlayPages command 308 labelString element 189 overlayTemplates command 311 legend 158 legend element 180 lenient graphing mode 192 P levels page labels log 42 renumbering 315 line graph 162 pages linearized PDF 322 forcing even 294 links inserting 292 deleting 269 renumbering 315 exporting 267 rotating 306 log levels 42 PDF converting to and from PostScript 320 converting to raster 321 M Fast Web View 322 major axis 158 linearized 322 majorAxis element 179 saving optimized 322 map element 173 pie graph 162 merging polar graph 161 comments 262 populating overlay template form fields 312 minor axis 158 postdecimal attribute 188 minorAxis element 179 PostScript converting to and from PDF 320 predecimal attribute 188 predefined form field values 314 proeprty element 173

334 Adobe Document Server Developers Guide ABCDEF GHI J KL MNOPQRS TUVWXYZ

properties standard docInfo variables 313 document information 313 strict graphing mode 192 graph 171 string property row element 172 substitutions 189 substitutions string 189 R SVG radar graph 162 embedded fonts 148 rasterizing symbol element 188 PDF 321 symbol element 188 repeat attribute 182 rights document usage 251 T getting document usage 255 table of contents setting document usage 251 generating 303 rotatePages command 306 template rotating overlay form fields 312 pages 306 templates creating overlay 312 TOC 304 S thumbnails saveContent command 59 deleting 272 saveOptimized command 59, 63, 322 TOC saving templates 304 optimized PDF 322 scatter graph 162 security U decrypting documents 249 Uniform Resource Identifier (URI) 148 encrypting documents 245 union element 187 series 158 unstacked graph 161 setPageLabels command 316 updateThumbnails command 272 setUsageRights command 251 usage rights 251 showing getting 255 graph component 188 setting document 251 sliceValue attribute 188 sliding graph design 188 spawnPages command 295 V stacked bar graph 162 values element 172 stacked column graph 162 valueSubstitution element stacked graph 161 postdecimal attribute 188 stacking attribute 161 predecimal attribute 188 stacking option valueSubstitution elements 188 normalized graph 161 variables stacked graph 161 standard docInfo 313 unstacked graph 161

Adobe Document Server Developers Guide 335 ABCDEF GHI J KL MNOP QRS TUVWXYZ

W X Web XFDF 261 Fast View PDF 322 xform element 186 what element 186 xforms element 180 which element 186

336 Adobe Document Server Developers Guide