PDF In-Depth

Focus on PDF Layers (OCG)

February 18, 2004


With the introduction of PDF version 1.5 came the concept of Layers. Layers or as they are more formally known Optional Content Groups (OCG) provide an excellent method for dealing with related content.

The concept of Layers isn't new, Illustration and CAD packages have been using Layers to separate content for many years, however the ability to have this functionality inside Acrobat/PDF provides developers and PDF authors alike with the kind of functionality we've become accustomed to, and made use of extensively.

Authoring Applications

An essential point to remember is that Acrobat is not able to set or create layers from existing content. This is largely due in part to the fact that Acrobat isn't an illustration package or indeed an authoring application. This means we need to rely on authoring applications to generate PDF files that can write PDF version 1.5 and also write OCGs/Layers.

At present the following applications support this functionality:

  • Illustrator CS (v11)
  • InDesign CS (v3)
  • AutoCAD (w/Acrobat PDFMaker)
  • Visio (w/Acrobat PDFMaker)
  • AcroTips.com StacksOn for MSWord*
  • ARTS PDF Stratify (Acrobat Plugin)*

The new Adobe Creative Suite translates directly the layers you have in your documents into layers in you PDF's, AutoCAD and Visio rely on Acrobat's PDFMaker (VBA) macro to to create the corresponding layers from the source documents.

StacksOn* is the first MSWord tool for creating Layers from Word source documents and ARTS PDF Stratify* is the only tool on the market for creating or rather defining layers from existing PDF content (it's a plugin for Acrobat).

* AcroTips is currently in the late stages of development of StacksOn -- the first tool for creating layers in Word that produce a layered PDF version. ARTS PDF (a division of BinaryThing) has also announced it will be releasing a new version of ARTS PDF Stratify which will let Acrobat users define layers from within Acrobat.

Next Steps

So this gives us an idea on how to create Layered PDFs, in our example I've created a PDF with a floor plan with several layers.

The potential of Layered PDF (OCGs) is huge, one of the best examples I've seen so far has been a company brochure with two layers. The page is initially blank with just the background images for the products, however when the PDF is opened a little bit of Javascript checks the language of the user and switches either the German Layer or English layer on -- these two layers contain the appropriate translated text for the product -- all in one PDF!

What we'll concentrate on in this article is how to manipulate OCGs with Javascript to truly make best use of this new technology.

Throughout this article I'll use the terms Layers and OCGs interchangeably.

Finding the Layers

When you open a PDF file that has Layers you'll notice a piece of cake (no really, a piece of cake) in the status bar at the bottom left of the screen. This icon indicates that the PDF you have open has special features and by clicking on the icon a dialog will display informing you what these special features are.

In our case the PDF has Layers (or Optional Content Groups), so the dialog let's us know that such a thing exists and how to show the layers panel.

So if we havent already got the Layers Panel open we can go into the 'view' menu and select 'Navigation Tabs' and then choose 'layers'.

You should be presented with the list of currently available Layers for this PDF. Just remember that Layers are page bound not Document bound, meaning each layer in the list belongs to a page somewhere in the document, using the properties menu you can actually elect to show only Layers for the current page or for the entire document.

Properties for Layers

The authoring application that created the PDF can set attributes for each Optional Content Group that can tell the viewing software (in our case Acrobat/Reader) how to deal with the OCG and also any other features that may or may not be Interface driven.

OCG Properties

The following properties can be defined when creating PDF's, the actual properties that are set are determined by the authoring application, some properties are user defineable and others are part of the PDF standard. (This list isn't complete)

Property/Feature Description
CreatorInfo: Creator The application that created the OCG/PDF
CreatorInfo: Subtype For example, Artwork or Technical or Illustration
Language: Lang Language and Locale for this Layer. This is useful for applications extracting or exporting data from PDF files.
Language: Preferred This can contain either an ON or OFF value indicating if this Language should be the preferred Language.
View:ViewState A value of either ON or OFF which indicates if this Layer should be visible when the document is opened
Export:ExportState ON or OFF again indicating if the layer should be included for export by Acrobat or other applications
Print:Subtype This property can indicate what type of content is being controlled by the OCG for the purposes of printing, eg Trapping, Water

From the Properties dialog for a PDF Layer created from Adobe Illustrator CS (v11.0) it indicates the following four properties.

Groups of Optional Content

It's possible to have loads of single Layers (or content marked as Optional Content) or to actually gather these layers into related groups. However currently we only have programmatic access to individual layers, not the entire group(s).

It's also possible to have nested groups, meaning groups inside groups inside groups. The level of complexity is purely driven by your needs or the needs of the application using the PDF.

Scripting OCGs

The real power of OCGs comes from the ability to programmatically control the visibility and other properties of each individual Layer, regardless of the page is belongs to.

However one thing you might notice that's missing is the ability to control any Top Level Groups that exist as 'wrappers' to individual Layers. Although it's missing the functionality provided in other areas more than makes up for this deficiency.

If we take a look in the AcroJS (Acrobat Javascript Scripting Reference) manual we can see we have the following objects to play with.

Effectively it breaks down to having control over Layers in the following ways:

  • Change the current State: Visible/Invisible
  • Extract the Name of the Layer
  • Set the Action for the Layer (what happens when it's Visibility is changed)
  • We are also able to get ALL of the OCGs for the current document or a specific page, this method is listed under the 'Doc' object.

Writing the Code

In our example I want to add four link boxes, one to each of the icons in the PDF. Each Icon toggles the appropriate layers visibility:

  • Toggle the display of the Names
  • Toggle the display of the Wet Areas
  • Toggle the display of the Carpeted Areas
  • Toggle the display of the Tiled Areas

I'll also add a link box over the logo to toggle it's visibility, and also one covering the actual floor plan -- so you can toggle that layer also (although in our case the icons are on that layer as well so you'll need to remember where the link boxes are ;)

Probably the first thing you'll notice when you add a link box and go to set it's action is that there's an action of type 'set Layer Visibility'. For this example we aren't going to make use of this action type. Basically this action makes note of the current layer visibility settings. When you click the link it changes the visibility of all of the layers to however they were when you set the action.

Code for the Icon Links Boxes

Create a link box and choose 'Custom Link' , under the Action settings select 'run a Javascript'. Click 'Add' and enter the following Javascript.

var docOCGs = this.getOCGs();
for (var x=0; x < docOCGs.length; x++) 
	if(docOCGs[x].name == "names")
		docOCGs[x].state = !docOCGs[x].state;

You'll need to repeat this step for each of the link boxes (in our case there's 6 link boxes. The important thing to change being the 'names' to whatever the name of the layer is.

As a convenience I also added two form buttons that run similar code, except they turn all of the layers on or all of the layers off:

// Visible
var docOCGs = this.getOCGs();
for (var x=0; x < docOCGs.length; x++) 
	docOCGs[x].state = true;

// InVisible
var docOCGs = this.getOCGs();
for (var x=0; x < docOCGs.length; x++) 
	docOCGs[x].state = false;


Hopefully from the example code and the example PDF you should see how useful Layers can be.

Remembering of course that the javascript we entered for the links could easily have been set as the action for a text field, bookmark, form button, checkbox etc.




Copyright Dave Wraight & Planet PDF. No unauthorised reproduction, distribution or publication permitted.

PDF In-Depth Free Product Trials Ubiquitous PDF

Debenu Quick PDF Library

Get products to market faster with this amazing PDF developer SDK. Over 900 functions and an equally...

Download free demo

Back to the past, 15 years ago! Open Publish 2002

Looking back to 2002, it's amazing how much of the prediction became a reality. Take a read and see what you think!

September 14, 2017
Platinum Sponsor

Search Planet PDF
more searching options...
Planet PDF Newsletter
Most Popular Articles
Featured Product

Debenu PDF Aerialist

The ultimate plug-in for Adobe Acrobat. Advanced splitting, merging, stamping, bookmarking, and link control. Take Acrobat to the next level.


Adding a PDF Stamp Comment

OK, so you want to stamp your document. Maybe you need to give reviewers some advice about the document's status or sensitivity. This tip from author Ted Padova demonstrates how to add stamps with the Stamp Tool along with related comments.