Oracle Business Intelligence Publisher User's Guide Release 10.1.3.2.0 Part Number B40017-01 | ![]() Contents | ![]() Previous | ![]() Next |
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:
Setting a temporary directory
Setting properties for PDF, RTF, and HTML output files
Setting PDF security properties
Setting font locations and substitutions
Setting translation properties
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.
You must name this file xdo.cfg.
Place the configuration file under <JRE_TOP>/jre/lib, for example: jdk/jre/lib.
The namespace for this configuration file is:
http://xmlns.oracle.com/oxp/config/
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>
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:
[0..1] - indicates the element is optional, and may occur only once.
[0..n] - indicates the element is optional, and may occur multiple times.
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>
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/ |
The root element of the configuration file. The configuration file consists of two parts:
Properties (<properties> elements)
Font definitions (<fonts> elements)
The <fonts> and <properties> elements can appear multiple times. If conflicting definitions are set up, the last occurrence prevails.
This section describes the <properties> element and the <property> element.
The properties element is structured as follows:
<properties locales="cdata">
<property>...
</property> [0..n]
</properties>
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 has the following structure:
<property name="cdata">
...pcdata...
</property>
Variable | Description |
---|---|
name | Specify the property name. |
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>
The following tables list the available properties. They are organized into the following groups:
General Properties
PDF Output Properties
PDF Security
RTF Output
HTML Output
FO Processing Properties
PDF Template Properties
RTF Template Properties
PDF Document Merger Property
XLIFF Extraction Properties
General properties are shown in the following table:
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. |
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 | 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:
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:
When pdf-encryption-level is set to 1, the following properties are available:
|
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:
|
pdf-printing-allowed | 0 | Permission available when pdf-encryption-level is set to 1. Valid values are:
|
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. |
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. |
The following properties can be set to govern FO processing:
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:
|
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. |
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. |
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. |
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 include the following elements:
<fonts>
<font>
<font-substitute>
<truetype>
<type1>
For the list of Truetype and Type1 fonts, see Predefined Fonts.
The <fonts> element is structured as follows:
<fonts locales="cdata">
<font> ... </font> [0..n]
<font-substitute> ... </font-substitute> [0..n]
</fonts>
Variable | Description |
---|---|
locales | Specify the locales for this font definition. This attribute is optional. |
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>
Following is the structure of the <font> element:
<font family="cdata" style="normalitalic"
weight="normalbold">
<truetype>...</truetype>
or <type1> ... <type1>
</font>
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. |
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>
Following is the structure of the font-substitute element:
<font-substitute name="cdata">
<truetype>...</truetype>
or <type1>...</type1>
</font-substitute>
Variable | Description |
---|---|
name | Specify the name of the font to be substituted. |
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>
The form of the <type1> element is as follows:
<type1 name="cdata"/>
Variable | Description |
---|---|
name | Specify one of the Adobe standard Latin1 fonts, such as "Courier". |
<type1> element defines an Adobe Type1 font.
<!--Define "Helvetica" font as "Serif" -->
<font family="serif" style="normal" weight="normal">
<type1 name="Helvetica"/>
</font>
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:
en
en-US
EN-US
ja
ko
zh-CN
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.
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:
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) |