Optional content (Layers) in pdfChip

Specifying optional content (commonly named as "Layers") in CSS is done in two steps:

  1. define optional content rules, for optional content groups (OCGs), optional content group nodes (OCG nodes) and/or optional content membership dictionaries (OCMDs) by using pdfChip specific syntax
  2. set style attributes for HTML elements or through CSS classes and IDs via names defined in the optional content rules

A simple example is shown here:

<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="UTF-8">
		<title> Optional content example </title>
		<style>
			@-cchip-pdf-ocg-node{
					-cchip-pdf-ocg-display-name: "Show/hide paragraphs";
					-cchip-pdf-ocg-name: "paragraphs";
			}
			p {
				-cchip-pdf-ocg: 'paragraphs';
			}
		</style>
	</head>
	<body>
		<h1>This is a heading. </h1>
		<p>This is some text in a paragraph. It is only shown if visibility for the layer "Show/hide paragraphs" is turned on.
	</body>
</html>
Click to copy

In the attached ZIP archive two examples are included, one very simple example, and a second example demonstrating handling of OCGs in imported PDF pages. At least pdfChip 1.4 (December 2017) is required to process the optional content related features.

Optional_content_with_pdfChip_(2_examples).zip

Optional content rules

Optional content groups: @-cchip-pdf-ocg

An optional content group rule establishes an optional content group (often referred to as layer). 

@-cchip-pdf-ocg {
	/* attributes: */	
	...
}
Click to copy

The attributes shown in the table below are available to define properties of an optional content group:

Attribute Matching optional content property
in PDF 1.7 (ISO 32000-1)		 Description
-cchip-pdf-ocg-display-name
 Name entry in an Optional Content Group Dictionary (ISO 32000-1, Table 98) (optional) a string providing the display name for the OCG
-cchip-pdf-ocg-name
 no equivalent in PDF syntax; only used for associating styles with OCG rules (required) a string providing the name for the OCG to be used in CSS style attributes
-cchip-pdf-ocg-visibility
 inserts reference to the OCG in the ON array of the default Optional Content Configuration DIctionary (OCCD) (ISO 32000-1, Table 101) (optional; default: on) a value setting the visibility of the OCG; possible values are on and off; the default value is on
-cchip-pdf-ocg-parent-name
 no equivalent in PDF syntax; only used in optional content rules for associating an OCG with a parent OCG
 (optional) a string providing the name of the OCG or OCG node that is the parent of this OCG; this requires that a separate OCG or OCG node is defined that serves as a parent for this OCG; this feature makes it possible to define nested lists of OCGs that can be displayed as a hierarchy in a user interface.
-cchip-pdf-ocg-rbgroup
 RBGroups entry in default Optional Content Configuration Dictionary (ISO 3200-1, Table 101) (optional) a positive integer (i.e. 1 or greater) identifying the radio button group to which this OCG belongs. All OCGs that have the same -cchip-pdf-ocg-rbgroup number will belong to the same radio button group. A value of -1 indicates that the OCG does not belong to any radio button group; the default value is -1
-cchip-pdf-ocg-gts-procstepsgroup
 GTS_ProcStepsGroup entry in a GTS_Metadata dictionary (ISO 19593-1, Table 2)

 (optional) a string providing the metadata entry for the OCG's processing steps group as defined in ISO 19593-1, "Graphic technology — Use of PDF to associate processing steps and content data – Part 1: Processing steps for packaging and labels"; see below for a list of pre-defined values
-cchip-pdf-ocg-gts-procstepstype
 GTS_ProcStepsType entry in a GTS_Metadata dictionary (ISO 19593-1, Table 2)
 (optional) a string providing the metadata entry for the OCG's processing steps step as defined in ISO 19593-1, "Graphic technology — Use of PDF to associate processing steps and content data – Part 1: Processing steps for packaging and labels"; see below for a list of pre-defined values

An OCG will only be created in the resulting PDF, if there is actually content using it. The presence of an @-cchip-pdf-ocg alone is not sufficient.

Example for a @-cchip-pdf-ocg rule:

@-cchip-pdf-ocg{
	-cchip-pdf-ocg-display-name: "Show / hide this optional content"
	-cchip-pdf-ocg-name: "example-ocg"; 
	-cchip-pdf-ocg-visibility: on; 
}
Click to copy

Optional content group nodes: @-cchip-pdf-ocg-node

An optional content group node rule establishes an optional content group node. Such a node is not in itself associated with any optional content, but serves as a node in the hierarchical display of optional content groups in a user interface.

@-cchip-pdf-ocg-node {
	/* attributes: */	
	...
}
Click to copy

The attributes shown in the table below are available to define properties of an optional content group node:

Attribute Matching optional content property
in PDF 1.7 (ISO 32000-1)		 Description
-cchip-pdf-ocg-display-name
 optional first entry (of type text string) in an Order array (or sub-array) in the default Optional Content Configuration Dictionary (ISO 32000-1, Table 101) (optional) a string providing the display name for the OCG node
-cchip-pdf-ocg-name
 no equivalent in PDF syntax; only used for associating styles with OCG node rules (required) a string providing the name for the OCG node to be used in CSS style attributes
-cchip-pdf-ocg-parent-name
 no equivalent in PDF syntax; only used in OCG node rules for associating an OCG node with a parent OCG
 (optional) a string providing the name of the OCG that is the parent of this OCG node; this requires that an OCG is defined that serves as a parent for this OCG node; this feature makes it possible to define nested lists of OCGs that can be displayed as a hierarchy in a user interface.

Example for a @-cchip-pdf-ocg-node rule:

@-cchip-pdf-ocg-node{
	-cchip-pdf-ocg-display-name: "Example of a node (without OCG)";
	-cchip-pdf-ocg-name: "example-ocg-node-name";
}
Click to copy

Optional content membership dictionaries: @-cchip-pdf-ocmd

Optional Content Membership Dictionaries (OCMDs) make it possible to go beyond associating some content with a specific OCG. Using OCMDs it is possible to associate content (and its visibility) with the visibility of OCGs. A simple use would be to make some content visible if at least one of three OCGs is visible, and to turn it off if all three OCGs are off.

@-cchip-pdf-ocmd {
	/* attributes: */	
	...
}
Click to copy

The attributes shown in the table below are available to define properties of an optional content group node:

Attribute Matching optional content property
in PDF 1.7 (ISO 32000-1)		 Description
-cchip-pdf-ocmd-policy

 P entry  in an Optional Content Membership Dictionary (ISO 32000-1, Table 99) (optional) a value defining the visibility policy for content belonging to this OCMD; possible values are anyon, anyoff, allon, allof, the default is anyon.
-cchip-pdf-ocmd-name
 no equivalent in PDF syntax; only used for associating styles with OCMD rules (required) a string providing the name for the OCMD to be used in CSS style attributes
-cchip-pdf-ocg-list
 OCGs entry  in an Optional Content Membership Dictionary (ISO 32000-1, Table 99)
 		(optional) a list of strings providing the names of the OCG that are associated with this OCMD
 
@-cchip-pdf-ocmd {
	-cchip-pdf-ocmd-policy: allon; /* allon, alloff, anyon(default), anyoff */
	-cchip-pdf-ocmd-name: "example-ocg-group";
	-cchip-pdf-ocg-list: "example-ocg-1" "example-ocg-2";/* space-separated list of strings */
}
Click to copy

Hierachies of OCGs

Hierarchies of OCGs are defined bottom up by having the child in a hierarchy reference its parent node by means of the -cchip-pdf-ocg-parent-name in an @-cchip-pdf-ocg or @-cchip-ocg-node rule. The following examples demonstrates a simply hierarchy with one top most OCG and two childs, with the second child having a child of its own. 

/*parent node*/
@-cchip-pdf-ocg{
	-cchip-pdf-ocg-display-name: "Parent OCG entry";
	-cchip-pdf-ocg-name: "example-ocg-parent"; 
}
/*first child node*/
@-cchip-pdf-ocg{
	-cchip-pdf-ocg-display-name: "Child #1";
	-cchip-pdf-ocg-name: "example-ocg-child-1"; 
	-cchip-pdf-ocg-parent-name: "example-ocg-parent";
}
/*second child node*/
@-cchip-pdf-ocg{
	-cchip-pdf-ocg-display-name: "Child #2";
	-cchip-pdf-ocg-name: "example-ocg-child-2"; 
	-cchip-pdf-ocg-parent-name: "example-ocg-parent";
}
/*child of child node #2*/
@-cchip-pdf-ocg{
	-cchip-pdf-ocg-display-name: "Child of child #2";
	-cchip-pdf-ocg-name: "example-ocg-child-of-child-2"; 
	-cchip-pdf-ocg-parent-name: "example-ocg-child-2";
}
Click to copy

Importing PDF pages that already contain optional content

When importing PDF pages that already contain optional content, one of the following will happen:

  • for any OCG in the imported PDF page for which there is also an OCG rule with the same display name in the PDF created by pdfChip, the properties defined in the OCG rule will override the properties defined in the imported PDF page; for example, if the visibility for an OCG in the imported PDF page is set to true, whereas it is set to false in the OCG rule, the visibility for this OCG will be false for the PDF created by pdfChip.
  • if for an OCG in an imported PDF page there is not yet already an OCG rule with the same display name in the PDF created by pdfChip, the definition of the OCG in the imported PDF page will be copied into the PDF created by pdfChip. As a result, the properties for the OCG as they exist in the imported PDF page will then also exist in the same manner in the PDF created by pdfChip, excluding properties that define a relationship with other OCGs. For example, the visibility of the OCG will be the same in the PDF created by pdfChip but if it belonged to a radio button group, or has a parent OCG node, neither of these two will be created in the PDF created by pdfChip. Furthermore, when two PDF pages are imported that each contain an OCG with the same display name, but with differing properties, the properties of the PDF page imported first will prevail.