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'/>
...
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" />
...
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>
...
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>
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>
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"/>
...
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 . |