Place any content: Use information about the PDF document

When placing content, in order to make use of information about the PDF document or the variables used and their values, a file named “calsDocInfo.js” is provided in the “callas_tmp” sub-folder at the time the function is called. This file is updated every time a “Place content” Fixup is run and contains several useful pieces of information:

  • File name
  • File path
  • Variables used for the “Place content” Fixup (or the Profile containing this Fixup), including the values provided for these variables
  • Document information metadata fields: Title, Author, Subject, Keywords
  • Page geometry borders for each page (MediaBox, CropBox, BleedBox, TrimBox, ArtBox) as well as the “Page label”

This information is represented as values in the “cals_doc_info” variables and can be read using JavaScript.

Selecting an HTML file folder for content to be placed

  1. Configuring the “HTML file folder”
  2. Selected “HTML file folder”
  3. Selecting this menu item will take you to the folder containing all existing “HTML file folders”

“Open folder with configuration files” option (#3. from above) opens the corresponding “HTMLTemplates” folder

Menüpunkt "Ordner mit Konfigurationsdateien öffnen" öffnet den entsprechenden Ordner "HTMLTemplates"

Selecting “Open folder with configuration files” will take you to the corresponding “HTMLTemplates” folder. Here you can find all folders which contain at least an “index.html” file and which usually also contain other files such as CSS or JavaScript files as well as other required resources such as images or fonts.

Example structure for an HTML file folder containing “calsDocInfo.js” and “manifest.xml”

Beispiel für Aufbau eines HTML-Dateiordner mit "calsDocInfo.js" und "manifest.xml"

Important:

  • If it does not exist yet, the “callas_tmp” folder will be created by pdfToolbox when the corresponding configured “Place content” Fixup is run for the first time
  • The “callas_tmp” folder will contain the corresponding document information for the last processed PDF in the file “calsDocInfo.js”
  • If you need to request additional information for the next processing run, the “manifest.xml” file must be placed in the same folder which contains “index.html”
  • This manifest.xml file must contain the relevant requests

Example content for a “manifest.xml” file requesting all possible information

Beispiel für den Inhalt einer "manifest.xml"-Datei mit maximaler Informationsanforderung

Content for a “calsDocInfo.js” file containing special color, coverage and hit positioning information for “Apply to” check

Inhalt der "calsDocInfo.js"-Datei mit Angaben zu Sonderfarben, Flächendeckung und Postionen der Treffer der "Anwenden auf"-Prüfung

calsDocInfo.js

In an HTML file, in order to access information in the cals_doc_info data object, it is necessary to include the JavaScript file calsDocInfo.js from the "callas_tmp" sub-folder, using <script type="text/javascript" src="callas_tmp/calsDocInfo.js"></script>:

<!DOCTYPE html>
<html>
<head>
	<!-- Define our text encoding as unicode to avoid problems with accents etc... -->
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
	<!-- Style sheets -->
	<link rel="stylesheet" href="your/styles.css"  type="text/css"/>
	<!-- Javascripts -->
	<script type="text/javascript" src="callas_tmp/calsDocInfo.js"></script> <!-- ⬅⬅⬅ -->
	<script type="text/javascript" src="your/javascripts.js"></script>
</head>
<body>
    <!-- your HTML content -->
</body>
Click to copy

Thereafter you can access any data inside the cals_doc_info data object using common JavaScript conventions, as illustrated by the following example:

function getTrimBox( inPageNumber ) {
	var thePage = cals_doc_info.pages[inPageNumber];
	if thePage.trimbox != null) {
			return thePage.trimbox;
	} else {
			return thePage.mediabox;
	}
}
Click to copy

Example information contained within a “calsDocInfo.js” file:

var cals_doc_info = { 
	'document':{ 
		'name':'Example.pdf',
		'path':'\/Users\/odruemmer\/Desktop',
		'info':{ 
			'author':'Max Meyer'
			'title':'On cals_doc_info and other useful things',
			'subject':null,
			'keywords':'pdfChip; useful; document information; variable; special colors; coverage; hit positions'
		},
		'numberofpages':2,
		'completeinkinformation':false,
		'variables':[ 
			{ 
				'name':'minimum',
				'value':'0'
			},
			{ 
				'name':'maximum',
				'value':'100'
			}
		]
	},
	'pages':[ 
		{ 
			'mediabox':[ 0, 0, 4251.97, 2834.65 ],
			'trimbox':[ 0, 0, 4251.97, 2834.65 ],
			'bleedbox':[ 0, 0, 4251.97, 2834.65 ],
			'cropbox':[ 0, 0, 4251.97, 2834.65 ],
			'artbox':[ 0, 0, 4251.97, 2834.65 ],
			'pagenumber':0,
			'pagelabel':'front side'
		},
		{ 
			'mediabox':[ 0, 0, 4251.97, 2834.65 ],
			'trimbox':[ 0, 0, 4251.97, 2834.65 ],
			'bleedbox':[ 0, 0, 4251.97, 2834.65 ],
			'cropbox':[ 0, 0, 4251.97, 2834.65 ],
			'artbox':[ 0, 0, 4251.97, 2834.65 ],
			'pagenumber':1,
			'pagelabel':'back side'
		}
	]
};

 

You can also keep the temporary calsDocInfo.js via:

<x:settings>
	<!--- if 'true' temporary files are moved next to the resulting PDF file (useful for developing templates) -->
	<x:keeptemp>true</x:keeptemp>
</x:settings>
Click to copy

Manifest.xml: Request additional information

Additional information about the PDF document can be requested with the help of a so-called manifest file (“manifest.xml”). This manifest file can additionally request the following types of information:

  • Name and replacement appearance for special colors contained within the PDF: <x:inkinfo/>
  • Coverage per color channel per page: <x:inkcov aperture="1mm" bbox="trimbox"/>; Note: This information requires each page to be rendered using a configurable resolution (specified using the blend value aperture), which can result in the Fixup taking longer to run.
  • The bounding box per “hit” for an “apply to” check set up within the “Place content” Fixup: <x:hitinfo/>

These details for requesting information must be contained in an <x:resources> note within the <manifest> root node:

?xml version=1.0 encoding=UTF-8 ?
manifest xmlns:x=http://www.callassoftware.com/cchip/template/manifest/
x:resources
 ... one or more entries requesting information ... /
/x:resources
/manifest

If all available information is requested, the manifest file will look like this:

?xml version=1.0 encoding=UTF-8 ?
manifest xmlns:x=http://www.callassoftware.com/cchip/template/manifest/
x:resources

!--- include ink info (ink names and alternate appearance only): --
x:inkinfo/

!--- include ink coverage info: ink names, usagecm, usage percent
   Ink coverage is determined by rendering the bbox of each 
   page with the specified aperture; units for aperture can be pt or mm 
   bbox can be mediabox, cropbox, bleedbox, trimbox 
   (Default: bbox: trimbox, aperture: 15mm) --
x:inkcov aperture=1mm bbox=trimbox/
 
!--- include bbox info for items found by Apply to check --
x:hitinfo/

/x:resources
/manifest

An example of a “calsDocInfo.js” file containing the maximum amount of information follows. The following items are of particular interest:

  • “completeinkinformation” is set to true; this means that both the existing special colors are listed (including their alternative appearance in CMYK values) as well as all color channels including each one's coverage (in percent based on the area specified (e.g. trimbox) and in absolute terms as an area in square centimeters)
  • Each document page has an entry named “inks” which includes the aforementioned information about special colors and coverage for all color channels.
  • Tonal values are given for the two special colors, “sky blue” and “tomato red” for their alternative appearance in CMYK.
  • The bounding boxes are listed under “hits” (“bbox”) for each hit in the “Place content” Fixup containing the “Apply to”  check - in this example, we are testing for special color objects.
var cals_doc_info = { 
  'document':{ 
   'name':'zwei Sonderfarben.pdf',
   'path':'\/Users\/odruemmer\/Desktop',
   'info':{ 
     'author':'OD',
     'title':'two special colors',
     'subject':'Test file for special colors',
     'keywords':null
   },
   'numberofpages':1,
   'completeinkinformation':true,   'variables':[ 
   ]
  },
  'pages':[ 
   { 
     'mediabox':[  0, 0, 792, 612 ],
     'trimbox':[  0, 0, 792, 612 ],
     'bleedbox':[  0, 0, 792, 612 ],
     'cropbox':[  0, 0, 792, 612 ],
     'artbox':[ 0, 0, 792, 612 ],
     'pagenumber':0,
     'pagelabel':null,
     'inks':[ 
      { 
        'name':Cyan,
        'usagecm':0,
        'usagepercent':0
      },
      { 
        'name':Magenta,
        'usagecm':0,
        'usagepercent':0
      },
      { 
        'name':Yellow,
        'usagecm':0,
        'usagepercent':0
      },
      { 
        'name':Black,
        'usagecm':1.09066,
        'usagepercent':0.180804
      },
      { 
        'name':"sky blue",
        'alternatename':'cmyk',
        'alternatecomps':[ 
         1, 0, 0, 0
        ],
        'alternateicc':null,
        'usagecm':37.6872,
        'usagepercent':6.24762
      },
      { 
        'name':"tomato red",
        'alternatename':'cmyk',
        'alternatecomps':[ 
         0.15, 1, 1, 0
        ],
        'alternateicc':null,
        'usagecm':37.6685,
        'usagepercent':6.24453
      }
     ],
     'hits':[ 
      { 
        'bbox':[ 82.2098, 129.289, 253.823, 229.147 ]
      },
      { 
        'bbox':[  473.391, 209.367, 253.823, 229.147 ]
      }
     ]
   }
  ]
};

For processing to succeed, it is important for the file to be named manifest.xml and for it to be located in the processing folder (alongside the index.html file.)