XML Document Preferences

Document preferences instruct PTC Arbortext Layout Developer how strict to be when processing XML and how to handle some optional functionality which may affect performance. Preference settings also make it easier to create and use XML dynamically without unnecessary overheads.

When creating an PTC Arbortext Layout Developer template from scratch, the default settings for handling XML in a document do not support the most common usage. You may need to configure your own settings.

There are two methods for setting XML document preferences:

• Access the preferences.xml property set of the fTemplate object with JavaScript

• Make changes manually in the document preferences menu in PTC Arbortext Layout Developer— Desktop product

The following preferences are available. Refer to Best Practices for a list of recommended settings:

• Preference: Save parser errors with document

FOM: fTemplate.preferences.xml.saveXMLErrors boolean property

Ensures any parser errors generated in the xerror namespace when trying to parse an XML content stream are kept with the document

This preference only needs to be activated if you want to provide specific information about a problem in parsing, for example to PTC Support.

• Preference: Ignore missing <?xml...?> declaration

FOM: fTemplate.preferences.xml.ignoreMissingXMLDecl boolean property

Instructs PTC Arbortext Layout Developer to build a DOM using the fStream.isXML property, even if the text stream it encounters does not include the XML declaration

FOM: fTemplate.preferences.xml.ignoreUndefinedEntities boolean property

Allows PTC Arbortext Layout Developer to ignore the presence of undeclared entities in content so the DOM tree can be built

When PTC Arbortext Layout Developer receives XML content it does not always have a DTD available. It also uses &...; delimited markers in content to apply styling. A lack of entity reference declaration can cause a problem with some parsers.

• Preference: Replace undefined entity references

FOM: fTemplate.preferences.xml.replaceUndefinedEntities boolean property

Instructs PTC Arbortext Layout Developer to leave an entity reference in output, rather than replacing it with its text equivalent

When parsing and/or processing XML using XSLT, if an entity reference is not defined, an attempt to replace it with its text equivalent would insert nothing.

• Preference: Validate against internal DTD

FOM: fTemplate.preferences.xml.validateXML boolean property

Instructs PTC Arbortext Layout Developer to validate XML content when a DTD is referenced from the XML instance

PTC Arbortext Layout Developer’s libXML library can validate against DTDs (not schemas), but by default it is not necessary. It is assumed that validation occurred during content creation. However, it can be helpful to validate when allowing content editing in a saved document.

• Preference: Expand XInclude elements

FOM: fTemplate.preferences.xml.processXInclude boolean property

• Preference: Load external files

FOM: fTemplate.preferences.xml.loadExternalFiles boolean property.

Instructs PTC Arbortext Layout Developer to use external files referenced from an XML instance, for example in entities, when parsing

• Preference: Create links to external files

FOM: fTemplate.preferences.xml.createLinksToFiles boolean property

Instructs PTC Arbortext Layout Developer to create a PTC Arbortext Layout Developer tag that links to an external content file, if Load external files specifies that they should be used

• Preference: Strip whitespace nodes

FOM: fTemplate.preferences.xml.stripWhitespaceNodes boolean property

Strips nodes that only contain whitespace from the resulting tree during parsing

• Preference: Add default attributes from DTD

FOM: fTemplate.preferences.xml.addDefaultAttributes boolean property

Ensures that attribute processing is aware of all attributes that should appear on an element

When parsing and validating against a DTD, PTC Arbortext Layout Developer can add default attributes to the resulting DOM tree if they are specified in the DTD.

Some other document preferences govern XPath behavior particular to PTC Arbortext Layout Developer:

• Allow PTC ALD variables — before JavaScript, PTC Arbortext Layout Developer accessed XPath using show strings. Accessing variables in XPath in show strings was complex before this setting was provided.

• Allow PTC ALD node tests — activates/deactivatesPTC Arbortext Layout Developer’s node test extensions to XPath

• Add ALD functions to global namespace and Add ALD functions to x3b2 namespace — PTC Arbortext Layout Developer provides a number of extension functions to standard XPath 1.0. These preferences are used to make the extensions available without using a namespace prefix before the function name.

In Arbortext Styler, the x3b2 namespace prefix is required for PTC Arbortext Layout Developer XPath extension functions.

Refer to XPath in PTC Arbortext Layout Developer for information on PTC Arbortext Layout Developer’s XPath support.

The following XML document preference settings are recommended when setting up a native PTC Arbortext Layout Developer template:

• Save parser errors with document / fTemplate.preferences.xml.saveXMLErrors — false

• Ignore missing XML <?xml...?> declaration / fTemplate.preferences.xml.ignoreMissingXMLDecl — true

• Ignore undefined entity references / fTemplate.preferences.xml.ignoreUndefinedEntities — true

• Replace undefined entity references / fTemplate.preferences.xml.replaceUndefinedEntities — false

• Validate against DTD / fTemplate.preferences.xml.validateXML — false

• Expand XInclude elements / fTemplate.preferences.xml.processXInclude — false

• Load external files / fTemplate.preferences.xml.loadExternalFiles — false

• Create links to external files / fTemplate.preferences.xml.createLinksToFiles — false

• Strip whitespace nodes / fTemplate.preferences.xml.stripWhitespaceNodes — false

• Add default attributes from DTD / fTemplate.preferences.xml.addDefaultAttributes — false

• Allow PTC ALD variables — true

• Allow PTC ALD node tests — true

• Add PTC ALD functions to global namespace and Add PTC ALD functions to x3b2 namespace — true