Skip Headers

Oracle Business Intelligence Publisher User's Guide
Release 10.1.3.2.0
Part Number B40017-01
Go to Table of Contents
Contents
Go to previous page
Previous
Go to next page
Next

Setting Runtime Properties

Setting Properties in a Configuration File

You can customize the behavior of XML Publisher by setting properties in a configuration file. The configuration file is optional. No default configuration file is provided.

The file is primarily used for:

Important: It is strongly recommended that you set up this configuration file to create a temporary directory for processing large files. If you do not, you will encounter "Out of Memory" errors when processing large files. Create a temporary directory by setting the system-temp-dir property.

It is also recommended that you secure the configuration file if you use it to set the PDF security passwords.

File Name and Location

You must name this file xdo.cfg.

Place the configuration file under <JRE_TOP>/jre/lib, for example: jdk/jre/lib.

Namespace

The namespace for this configuration file is:

http://xmlns.oracle.com/oxp/config/

Configuration File Example

Following is a sample configuration file:

<config version="1.0.0" 
  xmlns="http://xmlns.oracle.com/oxp/config/">

   <!-- Properties -->
   <properties>
      <!-- System level properties -->
      <property name="system-temp-dir">/tmp</property>

      <!--  PDF compression -->
      <property name="pdf-compression">true</property>

     <!--  PDF Security -->
     <property name="pdf-security">true</property>
     <property name="pdf-open-password">user</property>
     <property name="pdf-permissions-password">owner</property>
     <property name="pdf-no-printing">true</property>
     <property name="pdf-no-changing-the-document">true</property>
    </properties>

   <!-- Font setting -->
   <fonts>
      <!-- Font setting (for FO to PDF etc...) --> 
      <font family="Arial" style="normal" weight="normal">
         <truetype path="/fonts/Arial.ttf" />
      </font>
      <font family="Default" style="normal" weight="normal">
         <truetype path="/fonts/ALBANWTJ.ttf" />
      </font>

      <!--Font substitute setting (for PDFForm filling etc...) -->
      <font-substitute name="MSGothic"> 
         <truetype path="/fonts/msgothic.ttc" ttcno="0" />
      </font-substitute>  
   </fonts>
</config>      

How to Read the Element Specifications

The following is an example of an element specification:

<Element Name Attribute1="value"
              Attribute2="value"
					 AttributeN="value"
   <Subelement Name1/>[occurrence-spec]
   <Subelement Name2>...</Subelement Name2>
   <Subelement NameN>...</Subelement NameN>
</Element Name>

The [occurrence-spec] describes the cardinality of the element, and corresponds to the following set of patterns:

Structure

The <config> element is the root element. It has the following structure:

<config version="cdata" xmlns="http://xmlns.oracle.com/oxp/config/">
   <fonts> ... </fonts> [0..n]
   <properties> ... </properties> [0..n]
</config>

Attributes

Variable Description
version The version number of the configuration file format. Specify 1.0.0.
xmlns The namespace for XML Publisher's configuration file. Must be http://xmlns.oracle.com/oxp/config/

Description

The root element of the configuration file. The configuration file consists of two parts:

The <fonts> and <properties> elements can appear multiple times. If conflicting definitions are set up, the last occurrence prevails.

Properties

This section describes the <properties> element and the <property> element.

The <properties> element

The properties element is structured as follows:

<properties locales="cdata">
   <property>...
   </property> [0..n]
</properties>

Description

The <properties> element defines a set of properties. You can specify the locales attribute to define locale-specific properties. Following is an example:

<!-- Properties for all locales -->
<properties>
 ...Property definitions here...
</properties>

<!--Korean specific properties-->
<properties locales="ko-KR">
 ...Korean-specific property definitions here...
</properties>

The <property> element

The <property> element has the following structure:

<property name="cdata">
  ...pcdata...
</property>

Attributes

Variable Description
name Specify the property name.

Description

Property is a name-value pair. Specify the property name (key) to the name attribute and the value to the element value.

<properties>
  <property name="system-temp-dir">d:\tmp</property>
  <property name="system-cache-page-size">50</property>
  <property name="pdf-replace-smart-quotes">false</property>
</properties>

List of Properties

The following tables list the available properties. They are organized into the following groups:

General Properties

General properties are shown in the following table:

Property Name Default Value Description
system-temp-dir N/A Enter the directory path for the temporary directory to be used by the FO Processor when processing large files. It is strongly recommended that you set a temporary directory to avoid "Out of Memory" errors.

PDF Output Properties

The following table shows properties supported for PDF output:

Property Name Default Value Description
pdf-compression True Specify "True" or "False" to control compression of the output PDF file.
pdf-hide-menubar False Specify "True" to hide the viewer application's menu bar when the document is active.
pdf-hide-toolbar False Specify "True" to hide the viewer application's toolbar when the document is active.
pdf-replace-smartquotes True Set to "False" if you do not want curly quotes replaced with straight quotes in your PDF output.

PDF Security

Use the following properties to control the security settings for your output PDF documents:

Property Name Default Value Description
pdf-security False If you specify "True," the output PDF file will be encrypted. You must also specify the following properties:
  • pdf-open-password

  • pdf-permissions-password

  • pdf-encryption-level

pdf-open-password N/A This password will be required for opening the document. It will enable users to open the document only. This property is enabled only when pdf-security is set to "True".
pdf-permissions-password N/A This password enables users to override the security setting. This property is effective only when pdf-security is set to "True".
pdf-encryption-level 0 - low Specify the encryption level for the output PDF file. The possible values are:
  • 0: Low (40-bit RC4, Acrobat 3.0 or later)

  • 1: High (128-bit RC4, Acrobat 5.0 or later)


This property is effective only when pdf-security is set to "True". When pdf-encryption-level is set to 0, you can also set the following properties:
  • pdf-no-printing

  • pdf-no-changing-the-document

  • pdf-no-cceda

  • pdf-no-accff


When pdf-encryption-level is set to 1, the following properties are available:
  • pdf-enable-accessibility

  • pdf-enable-copying

  • pdf-changes-allowed

  • pdf-printing-allowed

pdf-no-printing False Permission available when pdf-encryption-level is set to 0. When set to "True", printing is disabled for the PDF file.
pdf-no-changing-the-document False Permission available when pdf-encryption-level is set to 0. When set to "True", the PDF file cannot be edited.
pdf-no-cceda False Permission available when pdf-encryption-level is set to 0. When set to "True", the context copying, extraction, and accessibility features are disabled.
pdf-no-accff False Permission available when pdf-encryption-level is set to 0. When set to "True", the ability to add or change comments and form fields is disabled.
pdf-enable-accessibility True Permission available when pdf-encryption-level is set to 1. When set to "True", text access for screen reader devices is enabled.
pdf-enable-copying False Permission available when pdf-encryption-level is set to 1. When set to "True", copying of text, images, and other content is enabled.
pdf-changes-allowed 0 Permission available when pdf-encryption-level is set to 1. Valid Values are:
  • 0: none

  • 1: Allows inserting, deleting, and rotating pages

  • 2: Allows filling in form fields and signing

  • 3: Allows commenting, filling in form fields, and signing

  • 4: Allows all changes except extracting pages

pdf-printing-allowed 0 Permission available when pdf-encryption-level is set to 1. Valid values are:
  • 0: None

  • 1: Low resolution (150 dpi)

  • 2: High resolution

RTF Output

The following properties can be set to govern RTF output files:

Property Name Default Value Description
rtf-track-changes False Set to "True" to enable change tracking in the output RTF document.
rtf-protect-document-for-tracked-changes False Set to "True" to protect the document for tracked changes.

HTML Output

The following properties can be set to govern HTML output files:

Property Name Default Value Description
html-image-base-uri N/A Base URI which is inserted into the src attribute of the image tag before the image file name. This works only when the image is embedded in the template.
html-image-dir N/A Enter the directory for XML Publisher to store the image files that are embedded in the template.
html-css-base-uri N/A Base URI which is inserted into the HTML header to specify where the cascading stylesheets (CSS) for your output HTML documents will reside. You must set this property when make-accessible is true.
html-css-dir N/A The CSS directory where XML Publisher stores the css file. You must set this property when make-accessible is true.
html-show-header True Set to "False" to suppress the template header in HTML output.
html-show-footer True Set to "False" to suppress the template footer in HTML output.
html-replace-smartquotes True Set to "False" if you do not want curly quotes replaced with straight quotes in your HTML output.
html-output-charset UTF-8 Specify the output HTML character set.
make-accessible False Specify true if you want to make the HTML output accessible.

FO Processing Properties

The following properties can be set to govern FO processing:

Property Name Default Value Description
digit-substitution None Valid values are "None" and "National". When set to "None", Eastern European numbers will be used. When set to "National", Hindi format (Arabic-Indic digits) will be used. This setting is effective only when the locale is Arabic, otherwise it is ignored.
system-cache-page-size 50 This property is enabled only when you have specified a Temporary Directory (under General properties). During table of contents generation, the FO Processor caches the pages until the number of pages exceeds the value specified for this property. It then writes the pages to a file in the Temporary Directory.
fo-prevent-variable-header False If "True", prevents variable header support. Variable header support automatically extends the size of the header to accommodate the contents.
fo-merge-conflict-resolution False When merging multiple XSL-FO inputs, the FO Processor automatically adds random prefixes to resolve conflicting IDs. Setting this property to "True" disables this feature.
xslt-xdoparser True Controls XML Publisher's parser usage. If set to False, XSLT will not be parsed.
xslt-scalable False Controls the scalable feature of the XDO parser. The property xslt-xdoparser must be set to "True" for this property to be effective.
rtf-adj-table-border-overlap False Sets the behavior of the top/bottom borders of adjacent tables. If you want the top and bottom borders of adjacent tables to overlap (for example, if you want to repeat a table multiple times and make the whole repeating area appear to be a single table), set this property to "true."

RTF Template Properties

The following properties can be set to govern RTF templates:

Property Name Default Value Description
rtf-extract-attribute-sets Auto The RTF processor will automatically extract attribute sets within the generated XSL-FO. The extracted sets are placed in an extra FO block, which can be referenced. This improves processing performance and reduces file size.
Valid values are:
  • Enable - extract attribute sets for all templates and subtemplates

  • Auto - extract attribute sets for templates, but not subtemplates

  • Disable - do not extract attribute sets

rtf-rewrite-path True When converting an RTF template to XSL-FO, the RTF processor will automatically rewrite the XML tag names to represent the full XPath notations. Set this property to "False" to disable this feature.
rtf-checkbox-glyph Default value: Albany WT J;9746;9747/A The XML Publisher default PDF output font does not include a glyph to represent a checkbox. If your template contains a checkbox, use this property to define a Unicode font for the representation of checkboxes in your PDF output. You must define the Unicode font number for the "checked" state and the Unicode font number for the "unchecked" state using the following syntax: fontname;<unicode font number for true value's glyph >;<unicode font number for false value's glyph>
Example: Albany WT J;9746;9747/A
Note that the font that you specify must be made available to XML Publisher at runtime.

PDF Template Properties

The following properties can be set to configure form field behavior in PDF output files generated from PDF templates:

Property Name Default Value Description
remove-pdf-fields false Specify "true" to remove PDF fields from the output. When PDF fields are removed, data entered in the fields cannot be extracted. For more information, see Setting Fields as Updateable or Read Only.
all-field-readonly true By default, XML Publisher sets all fields in the output PDF of a PDF template to be read only. If you want to set all fields to be updateable, set this property to "false". For more information, see Setting Fields as Updateable or Read Only.
all-fields-readonly-asis false Set this property to "true" if you want to maintain the "Read Only" setting of each field as defined in the PDF template. This property overrides the settings of all-field-readonly. For more information, see Setting Fields as Updateable or Read Only.

PDF Document Merger Property

Property Name Default Value Description
pdf-tempfile-max-size unlimited This property sets the maximum size for the temporary file used during batch processing by the PDF Document Merger. Enter the maximum size in bytes. For more information, see PDF Document Merger.

XLIFF Extraction

The following properties can be set to govern XLIFF extraction:

Property Name Default Value Description
xliff-trans-expansion 150 (percentage) This property determines the maximum percent expansion of an extracted translation unit. For example, if set to 200, the XLIFF extractor will allow expansion by 200% - that is, a 10-character element will have a maximum width of 30 characters.
xliff-trans-min-length 15 (characters) Sets a minimum length in characters for the extracted translation unit. For example, the default expansion of a 4-character field is 10 characters (based on the default setting of Translation expansion percentage of 150). If the Minimum translation length is 15, this field will be reset to 15 characters.
xliff-trans-max-length 4000 (characters) Sets a limit to the calculated expansion of the translation unit (in characters). For example, the default maximum expansion of 100 characters is 250 characters. Setting Maximum translation length to 200 would limit this expansion to 200 characters.
xliff-trans-null False Instructs the XLIFF extractor to create a translation unit for a record that contains only spaces (is null). Set to "True" to generate the translation unit.
xliff-trans-symbol False Instructs the XLIFF extractor whether to extract symbol characters. If set to "False" only A-Z and a-z will be extracted.
xliff-trans-keyword True If set to "False", words with underscores will not be extracted.

Font Definitions

Font definitions include the following elements:

For the list of Truetype and Type1 fonts, see Predefined Fonts.

<fonts> element

The <fonts> element is structured as follows:

<fonts locales="cdata">
   <font> ... </font> [0..n]
   <font-substitute> ... </font-substitute> [0..n]
</fonts>

Attributes

Variable Description
locales Specify the locales for this font definition. This attribute is optional.

Description

The <fonts> element defines a set of fonts. Specify the locales attribute to define locale-specific fonts.

<!-- Font definitions for all locales -->
<fonts>
  ..Font definitions here...
</fonts>

<!-- Korean-specific font definitions -->
<fonts locales="ko-KR">
... Korean Font definitions here...
</fonts>

<font> element

Following is the structure of the <font> element:

<font family="cdata" style="normalitalic"
weight="normalbold">
   <truetype>...</truetype>
or <type1> ... <type1>
</font>

Attributes

Variable Description
family Specify any family name for the font. If you specify "Default" for this attribute, you can define a default fallback font. The family attribute is case-insensitive.
style Specify "normal" or "italic" for the font style.
weight Specify "normal" or "bold" for the font weight.

Description

Defines an XML Publisher font. This element is primarily used to define fonts for FO-to-PDF processing (RTF to PDF). The PDF Form Processor (used for PDF templates) does not refer to this element.

<!-- Define "Arial" font -->
<font family="Arial" style="normal" weight="normal">
  <truetype path="/fonts/Arial.ttf"/>
</font>

<font-substitute> element

Following is the structure of the font-substitute element:

<font-substitute name="cdata">
   <truetype>...</truetype>
or <type1>...</type1>
</font-substitute>

Attributes

Variable Description
name Specify the name of the font to be substituted.

Description

Defines a font substitution. This element is used to define fonts for the PDF Form Processor.

<font-substitute name="MSGothic">
   <truetype path="/fonts/msgothic.ttc" ttccno=0"/>
</font-substitute>

<type1> element>

The form of the <type1> element is as follows:

<type1 name="cdata"/>

Attributes

Variable Description
name Specify one of the Adobe standard Latin1 fonts, such as "Courier".

Description

<type1> element defines an Adobe Type1 font.

<!--Define "Helvetica" font as "Serif" -->
<font family="serif" style="normal" weight="normal">
  <type1 name="Helvetica"/>
</font>

Locales

A locale is a combination of an ISO language and an ISO country. ISO languages are defined in ISO 639 and ISO countries are defined in ISO 3166.

The structure of the locale statement is

ISO Language-ISO country

Locales are not case-sensitive and the ISO country can be omitted.

Example locales:

Font Fallback Logic

XML Publisher uses a font mapping fallback logic so that the result font mappings used for a template are a composite of the font mappings from the template up to the site level. If a mapping is found for a font on more than one level, the most specific level's value overrides the others.

The resulting font mapping to use in any particular instance is the sum of all the applicable font mappings. The applicable mappings in order of preference, are:

Language + Territory match, territory null > Language + Territory null (global value)

For example:

Suppose for a particular template, there are different font mapping sets assigned at the site and template levels, with the mappings shown in the following table:

Level Font Family Style Weight Language Territory Target Font
Site Times New Roman normal normal (none) (none) Times
Site Arial normal normal Japanese Japan Times
Template Arial normal normal Japanese (none) Courier
Template Trebuchet MS normal normal (none) (none) Helvetica

At runtime if the locale of the template file is Japanese/Japan, the following font mappings will be used:

Font Family Style Weight Target Font
Times New Roman normal normal Times
Arial normal normal Times
Trebuchet MS normal normal Helvetica

Note that even though there is a mapping for Arial at the template level, the site level value is used because it has a better match for the locale.

Predefined Fonts

XML Publisher has several predefined fonts. These fonts do not require any font setting in the Administration interface.

The Type1 fonts are listed in the following table:

Type 1 Fonts
Number Font Family Style Weight Font Name
1 serif normal normal Time-Roman
1 serif normal bold Times-Bold
1 serif italic normal Times-Italic
1 serif italic bold Times-BoldItalic
2 sans-serif normal normal Helvetica
2 sans-serif normal bold Helvetica-Bold
2 sans-serif italic normal Helvetica-Oblique
2 sans-serif italic bold Helvetica-BoldOblique
3 monospace normal normal Courier
3 monospace normal bold Courier-Bold
3 monospace italic normal Courier-Oblique
3 monospace italic bold Courier-BoldOblique
4 Courier normal normal Courier
4 Courier normal bold Courier-Bold
4 Courier italic normal Courier-Oblique
4 Courier italic bold Courier-BoldOblique
5 Helvetica normal normal Helvetica
5 Helvetica normal bold Helvetica-Bold
5 Helvetica italic normal Helvetica-Oblique
5 Helvetica italic bold Helvetica-BoldOblique
6 Times normal normal Times
6 Times normal bold Times-Bold
6 Times italic normal Times-Italic
6 Times italic bold Times-BoldItalic
7 Symbol normal normal Symbol
8 ZapfDingbats normal normal ZapfDingbats

The TrueType fonts are listed in the following table. All TrueType fonts will be subsetted and embedded into PDF.

Number Font Family Name Style Weight Actual Font Actual Font Type
1 Albany WT normal normal ALBANYWT.ttf TrueType (Latin1 only)
2 Albany WT J normal normal ALBANWTJ.ttf TrueType (Japanese flavor)
3 Albany WT K normal normal ALBANWTK.ttf TrueType (Korean flavor)
4 Albany WT SC normal normal ALBANWTS.ttf TrueType (Simplified Chinese flavor)
5 Albany WT TC normal normal ALBANWTT.ttf TrueType (Traditional Chinese flavor)
6 Andale Duospace WT normal normal ADUO.ttf TrueType (Latin1 only, Fixed width)
6 Andale Duospace WT bold bold ADUOB.ttf TrueType (Latin1 only, Fixed width)
7 Andale Duospace WT J normal normal ADUOJ.ttf TrueType (Japanese flavor, Fixed width)
7 Andale Duospace WT J bold bold ADUOJB.ttf TrueType (Japanese flavor, Fixed width)
8 Andale Duospace WT K normal normal ADUOK.ttf TrueType (Korean flavor, Fixed width)
8 Andale Duospace WT K bold bold ADUOKB.ttf TrueType (Korean flavor, Fixed width)
9 Andale Duospace WT SC normal normal ADUOSC.ttf TrueType (Simplified Chinese flavor, Fixed width)
9 Andale Duospace WT SC bold bold ADUOSCB.ttf TrueType (Simplified Chinese flavor, Fixed width)
10 Andale Duospace WT TC normal normal ADUOTC.ttf TrueType (Traditional Chinese flavor, Fixed width)
10 Andale Duospace WT TC bold bold ADUOTCB.ttf TrueType (Traditional Chinese flavor, Fixed width)