Extensions

This chapter details Ibex-specific extensions to XSL-FO. Typically these extensions implement functionality which is not part of the XSL-FO standard such as password protecting a document .

The Ibex extensions have a namespace which is specified using the xmlns attribute as shown in Figure 21-1.

Document security

Ibex supports encryption of PDF documents and the setting of various document permissions. This is done using the ibex:security element as shown in Figure 21-1.

<root xmlns="http://www.w3.org/1999/XSL/Format" xmlns:ibex="http://www.xmlpdf.com/2003/ibex/Format">
<ibex:security deny-print='true' deny-extract='true' deny-modify='true' user-password='user' owner-password='owner'/>
...

Figure 21-1: FO using the ibex:security element

Two levels of encryption are available, 40 bit and 128 bit. When using 40 bit encryption available permissions which can be set including deny-print, deny-extract and deny-modify. When using 128 bit encyption additional permissions can be set including deny-assembly and deny-print-high-resolution. These options are details in the sections below.

The level of encryption is specified using the bits attribute of the ibex:security element.

This defaults to "40", so specify 128 bit encryption specify bits="128". If used the ibex:security element must occur before any page-sequence elements.

40 bit encryption security options

When the number of bits of encryption is set to 40 or not specified, the attributes of the ibex:security element are:

Attribute
 Value Meaning
user-password Specifies a password required to open the document in Acrobat. Once the document is opened with the correct user password, access is limited to permissions given using the attributes below.
owner-password Specifies a password required to get all rights to the document in Acrobat. Once the document is opened with the correct owner password the user has total control of the document.
deny-print true
false
 If this is set to true a user who opens the document with the user password will not be able to print the document.
deny-extract true
false
 If this is set to true a user who opens the document with the user password will not be able to use cut-and-paste functionality to copy part of the document.
deny-modify true
false
 If this is set to true a user who opens the document with the user password will not be able to modify the document.

 

Setting any of the attributes listed above will cause Ibex to encrypt the document. Specifying the user-password but not the owner-password will set the owner-password to the same value as the user-password. This means anyone who can open the document using the user password has complete control of the document. Specifying the owner-password but not the user-password is common usage. This means the user can open the document with limited rights without needing a password, but cannot then change or exceed those rights without knowing the owner password.

128 bit encryption security options

When the number of bits of encryption is set to 128, the attributes of the ibex:security element are:

Attribute
 Value Meaning
user-password Specifies a password required to open the document in Acrobat. Once the document is opened with the correct user password, access is limited to permissions given using the attributes below.
owner-password Specifies a password required to get all rights to the document in Acrobat. Once the document is opened with the correct owner password the user has total control of the document.
deny-print true
false
 If this is set to true a user who opens the document with the user password will not be able to print the document.
deny-print-high-resolution true
false
 If this is set to true a user who opens the document with the user password will not be able to print a high resolution copy of the document. They will only be able to print a low resolution (150dpi) version. If deny-print="true" this attribute has no effect and the document cannot be printed.
deny-extract true
false
 If this is set to true a user who opens the document with the user password will not be able to use cut-and-paste functionality to copy part of the document.
deny-modify true
false
 If this is set to true a user who opens the document with the user password will not be able to modify the document but can still "assemble" it. See deny-assembly below.
deny-assembly true
false
 If deny-modify="true" and deny-assembly="false" then the user cannot change the document, but can "assemble" it, which means insert, rotate or delete pages and create bookmarks or thumbnail images. Setting deny-modify="true" and deny-assembly="true" prevents assembly.

 

Setting any of the attributes listed above will cause Ibex to encrypt the document. Specifying the user-password but not the owner-password will set the owner-password to the same value as the user-password. This means anyone who can open the document using the user password has complete control of the document.

Specifying the owner-password but not the user-password is common usage. This means the user can open the document with limited rights without needing a password, but cannot then change or exceed those rights without knowing the owner password.

Standard document properties

Ibex allows you to set the various properties associated with a PDF document. These properties can be viewed in Acrobat by using the File | Document Properties | Summary menu option or just pressing control-d. Figure 21-2 shows FO for setting the document properties using the ibex:properties element.

<fo:root xmlns="http://www.w3.org/1999/XSL/Format" xmlns:ibex="http://www.xmlpdf.com/2003/ibex/Format">
		
	<ibex:properties
		title="Ibex User Manual"  
		subject="Ibex"
		author="visual programming limited"
		keywords="xml,pdf"	
		creator="xtransform" />
		...

Figure 21-2: FO using ibex:properties

If used the ibex:security element must occur before any page-sequence elements. The attributes of the ibex:properties element are:

Attribute
 Value Meaning
title Specifies a string which becomes the title property of the document.
subject Specifies a string which becomes the subject property of the document.
author Specifies a string which becomes the author property of the document.
keywords Specifies a string which becomes the keywords property of the document. Separate individual keywords with commas.
creator Specifies a string which becomes the creator property of the document. This should be the name of the application which created the document from which the PDF file was created.
page-mode none
bookmarks
thumbs
fullscreen
 Specifies how Acrobat will display the document when it is first opened. If set to 'bookmarks' then if the document has bookmarks they will be displayed. If set to 'thumbs' then the thumbnails tab in Acrobat will be displayed. If set to 'fullscreen' the document will be displayed without any toolbar, border etc.

 

Following the PDF standard, the document creator property should be the name of the product which converted the content to PDF format, so this is always Ibex. Other document properties such as creation and modification date are populated automatically by Ibex.

Custom Document Properties

Acrobat supports the display and editing of custom document properties. These properties are a set of name value pairs stored within the PDF file. In Acrobat 6.0 these properties can be viewed by using the File | Document Properties menu option and clicking on the "Custom" entry in the list box to display a screen like this: These custom properties are inserted into the PDF using the ibex:custom element as shown in Figure 21-3.

<fo:root xmlns="http://www.w3.org/1999/XSL/Format" xmlns:ibex="http://www.xmlpdf.com/2003/ibex/Format">
		
	<ibex:properties title="Ibex User Manual">
		<ibex:custom name="favourite color" value="blue"/>
	</ibex:properties>
		
	...

Figure 21-3: FO using the ibex:custom element

Each property must have a name and value attribute.

Image processing

Image resolution

Ibex adds the dpi attribute to the external-graphic element to permit managing the dots per inch resolution of images. See Image resolution on page image-resolution.

Anti-aliasing

Ibex adds the ibex:anti-alias attribute to the external-graphic element to permit disabling anti-aliasing in order to achieve clearer images. See Image anti-aliasing on page image-anti-aliasing.

Multi-page TIFF image processing

Ibex adds the ibex:page attribute to the external-graphic element to specify which page of a muti-page TIFF image should be included in the PDF file. See Multi-page TIFF images on page image-multi-page-tif.

Bookmarks

XSL-FO 1.0 had no support for creating bookmarks in the PDF file. XSL 1.1 now has this feature so the ibex:bookmark element is no longer supported. The XSL 1.1 implementation of bookmarks is described on page Bookmarks.

Document base URL

The PDF format supports setting a base URL for links created with a fo:basic-link element. This base URL is prepended to the destination specified with an external-destination attribute if (and only if) the specified destination does not start with a '/' character. Figure 21-4 shows FO which creates a document with "http://www.xmlpdf.com" as the base URL and a link to the page "index.html". When the user clicks on the link in the PDF file, it will go to "http://www.xmlpdf.com/index.html".

<ibex:document-base-url value="http://www.xmlpdf.com"/>
..
<fo:block>
		<fo:basic-link external-destination='url(index.html)'>
				index.html
		</fo:basic-link>
</fo:block>

Figure 21-4: FO setting the document base URL

The base URL is a document-wide property and can be set only once. This property should not be confused with the Settings.BaseURI value which specifies a base URI to be used when Ibex retrieves images, stylesheets and XML during creation of the PDF file.

Ibex version

The ibex:version element inserts the version number of Ibex used to create the PDF file. This is an inline element which inserts characters into the document. Figure 21-5 shows FO which uses this element.

<fo:block xmlns:ibex="http://www.xmlpdf.com/2003/ibex/Format">
		created with Ibex version <ibex:version/>
</fo:block>

Figure 21-5: FO using ibex:version

PDF/X

Ibex can create PDF files which comply with the PDF/X standard. This is described in detail on page pdf-x.

Viewer Preferences

Ibex can set flags on the PDF file which control how the viewer application, such as Acrobat Reader, will display the PDF file. These flags are set using the ibex:viewer-preferences element as shown in Figure 21-6.

<fo:root xmlns="http://www.w3.org/1999/XSL/Format" xmlns:ibex="http://www.xmlpdf.com/2003/ibex/Format">
		
		<ibex:viewer-preferences hide-toolbar="true"/>
		...

Figure 21-6: FO using the ibex:viewer-preferences element

The attributes for the ibex:viewer-preferences element are:

Attribute
 Value Meaning
hide-toolbar true
false
 Set to true to hide the viewer application's tool bars
hide-menubar true
false
 Set to true to hide the viewer application's menu bar
hide-window-ui true
false
 Set to true to hide the UI and just display the document content
fit-window true
false
 Set to true to resize the viewer window to fit the document page size
center-window true
false
 Set to true to center the viewer window on the screen
display-doc-title true
false
 Set to true to have the viewer display the document title in the viewer frame rather than the file name. The document title is set using the title attribute of the ibex:properties element as detailed on page document-properties .