Editor UserManual PDF
Editor UserManual PDF
Editor UserManual PDF
Notice
Copyright
Oxygen XML Editor User Manual
Syncro Soft SRL.
Copyright 2002-2015 Syncro Soft SRL. All Rights Reserved.
All rights reserved. No parts of this work may be reproduced in any form or
by any means - graphic, electronic, or mechanical, including photocopying,
recording, taping, or information storage and retrieval systems - without the
written permission of the publisher. Products that are referred to in this document
may be either trademarks and/or registered trademarks of the respective owners.
The publisher and the author make no claim to these trademarks.
Trademarks. Many of the designations used by manufacturers and sellers to
distinguish their products are claimed as trademarks. Where those designations
appear in this document, and Syncro Soft SRL was aware of a trademark claim,
the designations have been rendered in caps or initial caps.
Notice. While every precaution has been taken in the preparation of this
document, the publisher and the author assume no responsibility for errors or
omissions, or for damages resulting from the use of information contained in
this document or from the use of programs and source code that may accompany
it. In no event shall the publisher and the author be liable for any loss of profit
or any other commercial damage caused or alleged to have been caused directly
or indirectly by this document.
Link disclaimer. Syncro Soft SRL is not responsible for the contents or
reliability of any linked Web sites referenced elsewhere within this
documentation, and Syncro Soft SRL does not necessarily endorse the products,
services, or information described or offered within them. We cannot guarantee
that these links will work all the time and we have no control over the availability
of the linked pages.
Warranty. Syncro Soft SRL provides a limited warranty on this product. Refer
to your sales agreement to establish the terms of the limited warranty. In addition,
Oxygen XML Editor End User License Agreement, as well as information
regarding support for this product, while under warranty, is available through
the Oxygen XML Editor website.
Third-party components. Certain software programs or portions thereof
included in the Product may contain software distributed under third party
agreements ("Third Party Components"), which may contain terms that expand
or limit rights to use certain portions of the Product ("Third Party Terms").
Information identifying Third Party Components and the Third Party Terms that
apply to them is available on the Oxygen XML Editor website.
Downloading documents. For the most current versions of documentation, see
the Oxygen XML Editor website.
Contact Syncro Soft SRL. Syncro Soft SRL provides telephone numbers and
e-mail addresses for you to report problems or to ask questions about your
product, see the Oxygen XML Editor website.
Contents
Chapter 1: Introduction..........................................................................................19
Chapter 2: Getting Started.....................................................................................21
What is Oxygen XML Editor..............................................................................................................................22
Getting Familiar with the Layout........................................................................................................................22
Resources to Help You Get Started Using Oxygen XML Editor .......................................................................23
Your First Document or Project...........................................................................................................................24
Your First XML Document.....................................................................................................................24
Your First DITA Topic.............................................................................................................................28
Creating a New Project............................................................................................................................33
Getting Help........................................................................................................................................................34
Help Menu...............................................................................................................................................34
Chapter 3: Installation............................................................................................37
Installation Options.............................................................................................................................................38
Windows Installation...........................................................................................................................................38
Mac OS X Installation.........................................................................................................................................40
Linux Installation................................................................................................................................................41
Windows Terminal Server Installation................................................................................................................43
Linux Server Installation.....................................................................................................................................45
Java Web Start (JWS) Installation.......................................................................................................................46
Site-wide deployment..........................................................................................................................................48
Licensing.............................................................................................................................................................48
Setting up a License Server.................................................................................................................................52
Setting up a Floating License Server Running as a Standalone Process Using a Platform-independent
Distribution........................................................................................................................................57
Transferring or Releasing a License....................................................................................................................58
Upgrading............................................................................................................................................................58
Installing and Updating Add-ons.........................................................................................................................59
Uninstalling.........................................................................................................................................................60
Installer Command Line Reference.....................................................................................................................61
Chapter 4: Perspectives..........................................................................................63
Editor Perspective................................................................................................................................................64
Supported Document Types....................................................................................................................65
XSLT Debugger Perspective...............................................................................................................................65
XQuery Debugger Perspective ...........................................................................................................................66
Chapter
1
Introduction
Welcome to the User Manual of Oxygen XML Editor 17.1.
Oxygen XML Editor is a cross-platform application designed to accommodate
all of your XML editing, authoring, developing, and publishing needs. It is the
best XML editor available for document development using structured mark-up
languages such as XML, XSD, Relax NG, XSL, DTD. It is a comprehensive
solution for authors who want to edit XML documents visually, with or without
extensive knowledge about XML and XML-related technologies. The
WYSIWYG-like editor is driven by CSS stylesheets associated with the XML
documents and offers many innovative, user-friendly authoring features that
make XML authoring easy and powerful.
It offers developers and authors a powerful Integrated Development Environment
and the intuitive Graphical User Interface of Oxygen XML Editor is easy to
use and provides robust functionality for content editing, project management,
and validation of structured mark-up sources. Coupled with XSLT and FOP
transformation technologies, Oxygen XML Editor offers support for generating
output to multiple target formats, including: PDF, PS, TXT, HTML, JavaHelp,
WebHelp, and XML.
This user guide is focused on describing features, functionality, the application
interface, and to help you quickly get started. It also includes a vast amount of
advanced technical information and instructional topics that are designed to
teach you how to use Oxygen XML Editor to accomplish your tasks. It is
assumed that you are familiar with the use of your operating system and the
concepts related to XML technologies and structured mark-up.
Chapter
2
Getting Started
Topics:
This chapter is designed to help you get started using Oxygen XML Editor as
quickly as possible and to provide you with a variety of resources to help you
get the most out of the application. Typically, the first step of getting started
with Oxygen XML Editor would be to install the software. For detailed
information about that process, see the Installation on page 37 chapter.
After installation, when you launch Oxygen XML Editor for the first time, you
are greeted with a Welcome dialog box. It presents upcoming events, useful
video demonstrations, helpful resources, the tip of the day, and also gives you
easy access to recently used files and projects and to create new ones.
See the Configuring Oxygen XML Editor on page 1147 section for details on the various ways that you can configure
the application and its features.
Video Tutorials
The Oxygen XML Editor website includes numerous video demonstrations and webinars that present many of the
features that are available in Oxygen XML Editor and show you how to complete specific tasks or how to use the various
features.
Go to the Oxygen XML Editor Videos Page to see the list of video tutorials and webinars.
Text Editing Mode on page 70 Section - Provides information about the Text editor.
Author Editing Mode on page 93 Section - Provides information about the visual WYSIWYG-like Author editing
mode.
Editing Documents on page 133 Section - Includes information about editing a large variety of different types of
documents.
DITA Authoring on page 469 Section - Provides information about using DITA to edit and structure your content.
WebHelp System Output on page 828 Section - Provides information about the WebHelp system that can be used
for publishing content.
Importing Data on page 953 Section - Provides information about importing data from text files, MS Excel files,
database data, and HTML files.
Sample Documents
Your installation of Oxygen XML Editor includes a large variety of sample documents and projects that you can use as
templates to get started and to experiment with the various features and technologies. They are located in the samples
folder that is located in the installation directory of Oxygen XML Editor. You will find files and folders for a variety of
different types of documents, including the following:
sample.xpr file - A sample project file that will allow you to experiment with how projects can be structured and
used. When you open this project file, you will be able to see all the sample files and folders in the Project view.
Other Resources
The following list includes links to various other resources that will help you get started using the features of Oxygen
XML Editor:
See the Oxygen XML Editor Blog Site for a large variety of current and archived blogs in regards to numerous features,
requests, and instructional topics.
Take advantage of the Oxygen XML Editor Forum to see various announcements and learn more about specific issues
that other users have experienced.
If you are using DITA, see the incredibly helpful DITA Style Guide Best Practices for Authors.
To learn about the WebHelp features in Oxygen XML Editor, see the Publishing DITA and DocBook to WebHelp
section of the website.
For more information about various additional tools that are integrated into Oxygen XML Editor, see the Tools
section.
See the External Resource Page for links to various other helpful resources, such as discussion lists, external tutorials,
and more.
See the oXygen SDK section for details about the SDK that allows you to extend and develop Oxygen XML Editor
frameworks and plugins, and to integrate Eclipse plugins.
For a list of new features that were implemented in the latest version of Oxygen XML Editor, see the What's New
Section of the Website
You can select the Tip of the Day action in the Help menu to display a dialog box that includes a variety of tips for
using Oxygen XML Editor.
At any given location in the document, there are only certain XML elements allowed. Oxygen XML Editor helps
you determine which elements are allowed. In Author mode, when you press Enter, Oxygen XML Editor assumes
that you want to enter a new element and shows you a list of elements that can be created in this location. Keep
typing until the element you want is highlighted and press Enter to insert the element. If you want to view the overall
structure of a document and see what is allowed (and where), you can use the Model view (Window > Show View >
Model).
When you create certain elements, you may find that your text gets a jagged red underline and you get a warning
that your content is invalid. This is usually because the element you have just created requires certain other elements
inside of it. Your document will be invalid until you create those elements. Oxygen XML Editor does its best to help
you with this. If there is only one possible element that can go inside the element you just created, Oxygen XML
Editor creates it for you. However, if there is more than one possibility you have to create the appropriate elements
yourself. In many cases, Oxygen XML Editor presents XML Quick Fixes that help you resolve errors by offering
proposals to quickly fix problems such as missing required attributes or invalid elements.
Showing Tags
To see exactly where you are in the structure of the document, you can show the tags graphically in the Author
view. There are several levels of tag visibility that you can choose using the
Display tags mode drop-down
menu on the toolbar (the button may look a little different as it changes to reflect the level of tags currently displayed).
Outline View
The Outline view shows you the structure of your document in outline format. You can use it to select elements,
or to move elements around in the document.
You can configure the Outline view to determine what is shown, such as element names, attributes, and comments.
Certain choices may work better for particular document types. You can also filter the Outline view to show only
elements with a certain name.
New - Opens the New file wizard for creating a new topic.
Reference - Opens the Insert Reference dialog box that allows you to create a reference to an existing topic.
Reference to the currently edited file - Opens the Insert Reference dialog box that helps you to easily create a
reference to the file that is currently opened in the editor.
You can also change the order and nesting of topics in the DITA Maps Manager view by doing either of the following:
Select the topic to move while holding down the Alt key and use the arrow keys to move it around.
Use the mouse to drag and drop the topic to the desired location.
The way your parent and child topics are organized in any particular output depends on both the configuration of those
topics in the map and the rules of the output transformation that is applied to them. Do not assume that your topics must
have the same organization for all output types. The map defines the organization of the topics, not the topics themselves.
It is possible to create a variety of different maps, each with different organization and configuration options to produce
a variety of different outputs.
Child Maps
If you have a large set of information, such as a long book or extensive help system, a single map can become long and
difficult to manage. To make it easier to manage, you can break up the content into smaller sub-maps. A sub-map might
represent a chapter of a book, a section of a user manual, or a page on a website.
To build a publication out of these smaller maps, you must add them to a map that represents the overall publication.
To add a child map to the current map, right-click the parent DITA map and choose Append child > Map reference.
Validating the map that describes your entire publication validates all the files that make up the publication and all of
the relationships between them. To validate a map, click the
DITA Maps Manager view.
Logical Folder
Creates a logical folder in the tree structure (the icon is a magenta folder on Mac OS X - ).
New > Logical Folders from Web
Replicates the structure of a remote folder accessible over FTP/SFTP/WebDAV, as a structure of logical folders.
The newly created logical folders contain the file structure of the folder it points to.
Add Folder
Adds a link to a physical folder, whose name and content mirror a real folder that exists in the local file system (the
icon of this action is different on Mac OS X
).
Add Files
Adds links to files on the local file system.
Add Edited File
Adds a link to the currently edited file in the project.
Using Linked Folders (Shortcuts)
Another easy way to organize your XML working files is to place them in a directory and then to create a corresponding
linked folder in you project. If you add new files to that folder, you can simply use the
Refresh (F5) action from
the toolbar or contextual menu and the Project view will display the existing files and subdirectories. If your files are
scattered amongst several folders, but represent the same class of files, you might find it useful to combine them in a
logical folder.
You can create linked folders (shortcuts) by dragging and dropping folders from the Windows Explorer (Mac OS X
Finder) to the project tree, or by selecting
Add Folder in the contextual menu from the project root. Linked folders
File action
Note: Files may have multiple instances within the folder system, but cannot appear twice within the same
folder.
For much more information on managing projects and their content, see the The Project View on page 71 section.
For more details about how you can share projects with other users, see the Sharing a Project - Team Collaboration on
page 164 section.
Getting Help
If you run into specific problems while using Oxygen XML Editor you can take advantage of a variety of support related
resources. Those resources include the following:
The application also includes various specific help-related resources in the Help menu.
Help Menu
The Oxygen XML Editor Help menu provides various resources to assist you with your tasks.
These resources include the following actions or options:
The Help (F1) Action
Use this action (or the F1 key) to open a dialog box that presents a section in the User Manual that is appropriate
for the context of the current cursor position. If the Use online help option is enabled, this action will open the User
Manual in an online mode.
Dynamic Help
Use the Show Dynamic Help view action to open a dynamic view that automatically loads the relevant help section
of the User Manual for the focused editor, view, or dialog box.
Add-ons
If you want to extend the functionality of Oxygen XML Editor with add-ons, the Help menu includes several options
for installing, updating, or managing add-ons.
Licensing
If you encounter problems with your Oxygen XML Editor license, you can use the Register option to open a dialog
box that provides options for obtaining or using a license key.
Reporting a Problem
You can use the Report problem option to open a dialog box that allows you to write the description of a problem
that was encountered while using the application. You are able to change the URL where the reported problem is
sent by using the com.oxygenxml.report.problems.url system property. The report is sent in XML format through
the report parameter of the POST HTTP method.You can also use the Support Center option to open the Oxygen
XML Editor Support Section of the Website.
The About Dialog Box
Clicking About opens a dialog box that contains information about Oxygen XML Editor and the installed version.
This dialog box includes the following tabs:
Chapter
3
Installation
Topics:
As a desktop application (running standalone or as an Eclipse plugin) on a Unix or Linux server or on Windows
Terminal Server.
From within a browser though the Java Web Start technology.
Choosing an installer
You have a choice of installers;
The native installer for your platform. On Windows and Linux, the native installer can run also in unattended mode.
The installation packages were checked before publication with an antivirus program to make sure they are not infected
with viruses, trojan horses, or other malicious software.
Choosing a license option
You must obtain and register a license key to run Oxygen XML Editor.
You can choose from two kinds of license:
System Requirements
System requirements for a Windows install:
Operating systems
Windows Vista, Windows 7, Windows 8, Windows 10, Windows Server 2008, Windows Server 2012
Memory
Minimum - 2 GB of RAM
Recommended - 4 GB of RAM
Storage
Java
Oxygen XML Editor requires Java. If you use the native Windows installer, Oxygen XML Editor will be installed
with its own copy of Java. If you use the all platforms installer, your system must have a compatible Java virtual
machine installed.
Oxygen XML Editor supports only official and stable Java Virtual Machines with the version number 1.6.0 or later
(the recommended version is 1.7) from Oracle available at
http://www.oracle.com/technetwork/java/javase/downloads/index.html. Oxygen XML Editor may work with JVM
implementations from other vendors, but there is no guarantee that those implementations will work with future
Oxygen XML Editor updates and releases.
Oxygen XML Editor uses the following rules to determine which installed version of Java to use:
1. If you install using the native Windows installer, which installs a version of Java as part of the Oxygen XML
Editor installation, the version in the jre subdirectory of the installation directory is used.
2. Otherwise, if the Windows environment variable JAVA_HOME is set, Oxygen XML Editor uses the Java version
pointed to by this variable.
3. Otherwise the version of Java pointed to by your PATH environment variable is used.
If you run Oxygen XML Editor using the batch file, oxygen.bat, you can edit the batch file to specify a particular
version to use.
6. To license your copy of Oxygen XML Editor go to Help > Register and enter your license information.
Unattended Installation
You can run the installation in unattended mode by running the installer from the command line with the -q parameter.
By default, running the installer in unattended mode installs Oxygen XML Editor with the default options and does not
overwrite existing files. You can change many options for the unattended installer using the installer command line
parameters.
System Requirements
System requirements for a Mac OS X install:
Operating system
OS X version 10.6 64-bit or later
CPU
Memory
Minimum - 2 GB of RAM
Recommended - 4 GB of RAM
Storage
Java
Oxygen XML Editor requires Java to run. OS X includes Java by default or it will install it on the first attempt to
run a Java application.
Oxygen XML Editor supports only official and stable Java Virtual Machines with the version number 1.6.0 or later
(the recommended version is 1.6.0 from Apple). Oxygen XML Editor may work with JVM implementations from
other vendors, but there is no guarantee that other implementations will work with future Oxygen XML Editor
updates and releases.
Oxygen XML Editor uses the following rules to determine which installed version of Java to use:
1. If you start Oxygen XML Editor with the application launcher (.app) file then:
a. if you use the zip distribution for OS X Oxygen XML Editor uses the Apple Java SE 6 available on your
Mac computer
OS X Installation
To install Oxygen XML Editor on OS X:
1. Download the OS X installation package (oxygen.zip).
The Safari web browser should recognize and expand the compressed file. If it is not automatically expanded, you
can expand it manually by double-clicking it.
2. Validate the integrity of the downloaded file by checking it against the MD5 sum published on the download page.
3. In Finder, move the expanded folder to your Applications folder.
Oxygen XML Editor is now installed.
4. Start Oxygen XML Editor, using one of the following methods:
5. To license your copy of Oxygen XML Editor, go to Help > Register to enter your license key.
System Requirements
System requirements for a Linux install:
Operating system
Any Unix/Linux distribution with an available Java SE Runtime Environment version 1.6.0 or later from Oracle
CPU
Memory
Minimum - 2 GB of RAM
Recommended - 4 GB of RAM
Storage
Java
Oxygen XML Editor requires Java. Oxygen XML Editor supports only official and stable Java Virtual Machines
with the version number 1.6.0 or later (the recommended version is 1.6.0) from Oracle available at
http://www.oracle.com/technetwork/java/javase/downloads/index.html. Oxygen XML Editor may work with JVM
implementations from other vendors, but there is no guarantee that other implementations will work with future
Oxygen XML Editor updates and releases. Oxygen XML Editor does not work with the GNU libgcj Java Virtual
Machine.
Oxygen XML Editor uses the following rules to determine which installed version of Java to use:
1. If you used the Linux installer, which installs a version of Java as part of the Oxygen XML Editor installation,
the version in the jre subdirectory of the installation directory is used.
2. Otherwise, if the Linux environment variable JAVA_HOME is set, Oxygen XML Editor uses the Java version
pointed to by this variable.
3. Otherwise the version of Java pointed to by your PATH environment variable is used.
You can also change the version of the Java Virtual Machine that runs Oxygen XML Editor by editing the script
file, oxygen.sh. Go to the Java command at the end of the script file and specify the full path to the Java executable
of the desired JVM version, for example:
/usr/bin/jre1.6.0_45/bin/java -Xmx256m ...
Linux Installation
Linux installation procedure.
To install Oxygen XML Editor on Linux, follow these steps:
1. Download the Linux installer.
2. Optionally, you can validate the integrity of the downloaded file by checking it against the MD5 sum published on
the download page.
3. Run the installer that you downloaded.
For example, open a shell, cd to the installation directory, and at the prompt type sh ./oxygen-32bit.sh or
sh ./oxygen-64bit.sh, depending on which installer you downloaded.
5. To license your copy of Oxygen XML Editor go to Help > Register and enter your license key.
Unattended Installation
You can run the installation in unattended mode by running the installer from the command line with the -q parameter.
By default, running the installer in unattended mode installs Oxygen XML Editor with the default options and does not
overwrite existing files. You can change many options for the unattended installer using the installer command line
parameters.
System Requirements
System requirements for a Windows Server install:
Operating systems
Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2
CPU
Memory
Storage
6. To license your copy of Oxygen XML Editor go to Help > Register and enter your license information.
System Requirements
System requirements for a Linux install:
Operating system
Any Unix/Linux distribution with an available Java SE Runtime Environment version 1.6.0 or later from Oracle
CPU
Memory
Minimum - 2 GB of RAM
Recommended - 4 GB of RAM
Storage
Java
Oxygen XML Editor requires Java. Oxygen XML Editor supports only official and stable Java Virtual Machines
with the version number 1.6.0 or later (the recommended version is 1.6.0) from Oracle available at
http://www.oracle.com/technetwork/java/javase/downloads/index.html. Oxygen XML Editor may work with JVM
implementations from other vendors, but there is no guarantee that other implementations will work with future
Oxygen XML Editor updates and releases. Oxygen XML Editor does not work with the GNU libgcj Java Virtual
Machine.
Oxygen XML Editor uses the following rules to determine which installed version of Java to use:
1. If you used the Linux installer, which installs a version of Java as part of the Oxygen XML Editor installation,
the version in the jre subdirectory of the installation directory is used.
2. Otherwise, if the Linux environment variable JAVA_HOME is set, Oxygen XML Editor uses the Java version
pointed to by this variable.
3. Otherwise the version of Java pointed to by your PATH environment variable is used.
You can also change the version of the Java Virtual Machine that runs Oxygen XML Editor by editing the script
file, oxygen.sh. Go to the Java command at the end of the script file and specify the full path to the Java executable
of the desired JVM version, for example:
/usr/bin/jre1.6.0_45/bin/java -Xmx256m ...
Linux Installation
Linux installation procedure.
To install Oxygen XML Editor on Linux, follow these steps:
5. To license your copy of Oxygen XML Editor go to Help > Register and enter your license key.
Installing Oxygen XML Editor using the Java Web Start (JWS) Installer
Oxygen XML Editor provides the tools to create your own JWS distribution that can be installed on a custom web server.
The advantages of a JWS distribution include:
Oxygen XML Editor is run locally, not inside a web browser, overcoming many of the browser compatibility problems
common to applets.
JWS ensures that the most current version of the application will be deployed, as well as the correct version of JRE.
Applications launched with Java Web Start are cached locally. Thus, an already downloaded application is launched
on par with a traditionally installed application.
The following schematics depicts the Oxygen XML Editor Java Web Start deployment procedure:
Site-wide Deployment
If you are deploying Oxygen XML Editor for a group, there are a number of things you can do to customize Oxygen
XML Editor for your users and to make the deployment more efficient.
Creating custom default options
You can create a custom set of default options for Oxygen XML Editor. These will become the default options for
each of your users, replacing Oxygen XML Editor's normal default settings. Users can still set options to suit
themselves in their own copies of Oxygen XML Editor, but if they choose to reset their options to defaults, the
custom defaults that you set will be used.
Creating default project files
Oxygen XML Editor project files are used to configure a project. You can create and deploy default project files
for your projects so that your users will have a preconfigured project file to begin work with.
Shared project files
Rather than each user having their own project file, you can create and deploy shared project files so that all users
share the same project configuration and settings and automatically inherit all project changes.
Using the unattended installer
You can speed up the installation process by using the unattended installer for Windows or Linux installs.
Using floating licenses
If you have a number of people using Oxygen XML Editor on a part-time basis or in different time zones, you can
use a floating license so that multiple people can share a license.
Obtaining a License
You can obtain a license for Oxygen XML Editor in one of the following ways:
You can purchase one or more licenses from the Oxygen XML Editor website at http://www.oxygenxml.com/buy.html.
A license key will be sent to you by email.
If your company or organization has purchased licenses please contact your license administrator to obtain a license
key.
If you purchased a subscription and you received a registration code, you can use it to obtain a license key from
http://www.oxygenxml.com/registerCode.html. A license key will be sent to you by email.
If you want to evaluate the product you can obtain a trial license key for 30 days from the Oxygen XML Editor
website at http://www.oxygenxml.com/register.html.
If all the machines sharing a pool of floating licenses are on the same network segment, you will register your licence
the same way you register a named-user licence.
Note: [For System Administrators] Different running instances of Oxygen XML Editor communicate with
each other, using UDP broadcast on the 59153 port, to the 239.255.255.255 group.
Warning: This mechanism was deprecated starting with version 17.0 and it is scheduled for removal in a
future version. It is recommended to switch to the license server/servlet licensing mechanism.
If the machines sharing the pool of floating licenses are on different network segments, someone in your company
will need to set up a license server. Consult that person to determine if they have set up a license server as a standalone
process or as a Java servlet as the registration process is different for each.
If a floating license is available, it is registered in Oxygen XML Editor. To display the license details, open the About
dialog box from the Help menu. If a floating license is not available, you will get a message listing the users currently
using floating licenses.
Request a Floating License from a License Server Running as a Java Servlet
1. Contact your server administrator to get network address and login details for the license server.
2. Start Oxygen XML Editor.
3. Go to Help > Register.
The license registration dialog box is displayed.
4. Choose Use a license server as licensing method.
5. Select HTTP/HTTPS Server as server type.
6. In the URL field enter the address of the license server.
The URL address has the following format:
http://hostName:port/oXygenLicenseServlet/license-servlet
7. Complete the User and Password fields.
8. Click the OK button.
If a floating license is available, it is registered in Oxygen XML Editor. To display the license details, open the About
dialog box from the Help menu. If a floating license is not available, you will get a message listing the users currently
using floating licenses.
Release a Floating License
The floating license you are using will be released and returned to the pool if any of the following occur:
You exit the application running on your machine, and no other copies of Oxygen XML Editor running on your
machine are using your floating license.
You register a Named User license with your copy of Oxygen XML Editor, and no other copies of Oxygen XML
Editor running on your machine are using your floating license.
A Java servlet.
A standalone process.
Note: Oxygen XML Editor version 17 or higher requires a license server version 17 or higher. License servers
version 17 or higher can be used with any version of a floating license key.
License load - A graphical indicator that shows how many licenses are available. When the indicator turns red, there
are no more licenses available.
Floating license server status - General information about the license server status, including the following
information:
License key information - License key data, including the following information:
licensed product
registration name
company name
license category
number of floating users
Maintenance Pack validity
Current license usage - Lists all currently acknowledged users, including the following information:
user name
date and time when the license was granted
name and IP address of the computer where Oxygen XML Editor runs
MAC address of the computer where Oxygen XML Editor runs
Note: The report is also available in XML format at
http://hostName:port/oXygenLicenseServlet/license-servlet/report-xml.
Steps for Installing the Floating License Server in Windows as a Standalone Process
1. Download the license server installation kit for Windows from the Oxygen XML Editor website.
2. Run the downloaded installer and follow the on-screen instructions.
By default, the installer installs the license server as a Windows service. Optionally, you have the ability to start the
Windows service automatically at Windows startup or create shortcuts on the Start menu for starting and stopping
the Windows service manually. If you want to manually install, start, stop, or uninstall the server as a Windows
service, run the following scripts from a command line as an Administrator:
Steps for Installing the Floating License Server as a Standalone Process with a Zip Archive
1.
2.
3.
4.
Ensure that a Java runtime version 6 or later is installed on the server machine.
Download the license server installation kit for your platform from the Oxygen XML Editor website.
Unzip the installation kit into a new folder.
Start the server using the startup script from a command line console.
The startup script is called licenseServer.sh for OS X and Unix/Linux or licenseServer.bat for
Windows. The following parameters are accepted:
licenseDir - The path of the directory where the license files will be placed. The default value is license.
port - The TCP port number used to communicate with Oxygen XML Editor instances. The default value is
12346.
The following is an example of the command line for starting the license server on Unix/Linux and OS X:
sh licenseServer.sh myLicenseDir 54321
5. Floating licenses require activation prior to use. Follow the on-screen instruction to complete the license activation
process.
Upgrading Your Floating License Server
The goal of the following procedure is to help you minimize the downtime generated when you upgrade the Oxygen
XML Editor floating license server to its newest version.
Follow this procedure:
1. Stop the current license server process.
2. Locate and open the floating server startup script. It should look like:
sh licenseServer.sh pathToLicenseDir 54321
3. Make a note of the path to the license directory (in our example is pathToLicenseDir) and the port number (in
our example is 54321).
4. Go to the license directory and copy the license key file (license.txt) for later use.
All the files from its install directory will be removed, including any modification in document type (framework)
files, XSLT stylesheets, XML catalogs, and templates.
All global user preferences are preserved in the new version.
All project preferences will be preserved in their project files.
Any custom frameworks that were stored outside the installation directory (as configured in Document type
associations > Locations) will be preserved and will be found by the new installation.
All the files from the old install directory will be preserved, including any modification in document type (framework)
files, XSLT stylesheets, XML catalogs, and templates. However, these modifications will not be automatically
imported into the new installation.
All global user preferences are preserved in the new version.
All project preferences will be preserved in their project files.
Any custom frameworks that were stored outside the installation directory (as configured in Document type
associations > Locations) will be preserved and will be found by the new installation.
On Windows use the appropriate uninstaller shortcut provided with your OS.
On OS X and Unix manually delete the installation folder and all its contents.
Unattended Uninstall
The unattended uninstall procedure is available only on Windows and Linux.
Run the uninstaller executable from command line with the -q parameter.
The uninstaller executable is called uninstall.exe on Windows and uninstall on Linux and is located in
the application's install folder.
The following table describes some of the settings that can be used in the response.varfile:
Table 1: response.varfile Options Parameters
Parameter name
Description
Values
true / false. Default setting is true.
reportProblem Allows you to report a problem encountered while true / false. Default setting is true.
using Oxygen XML Editor.
downloadResources Allows Oxygen XML Editor to download resources true / false. Default setting is true.
(links to video demonstrations, webinars and
upcoming events) from http://www.oxygenxml.com
to populate the application welcome screen.
The Oxygen XML Editor installation uses the install4j installer. A description of the response.varfile format
can be found on the install4j site.
Command line parameters
The Oxygen XML Editor installer supports the following command line parameters:
Meaning
-q
Run the installer in unattended mode. The installer will not prompt the user for input during the
install. Default settings will be used for all options unless a response.varfile is specified
using the -varfile option or individual settings are specified using
- on Windows:
oxygen.exe -q
- on Linux:
oxygen.sh -q
-overwrite
In unattended mode, the installer does not overwrite files with the same name if a previous version
of the Oxygen XML Editor is installed in the same folder. The -overwrite parameter added after
the -q parameter forces the overwriting of these files.
- on Windows:
oxygen.exe -q -overwrite
- on Linux:
oxygen.sh -q -overwrite
-console
To display a console for the unattended installation, add a -console parameter to the command line.
- on Windows:
start /wait oxygen.exe -q -console
Note: The use of start /wait on Windows is required to make the installer run
in the foreground. It you run it without start /wait, it will run in the background.
- on Linux:
oxygen.sh -q -console
-varfile
- on Linux:
oxygen.sh -q -varfile response.varfile
-V
- on Linux:
oxygen.sh -q -VusageDataCollector=false
The Oxygen XML Editor installation uses the install4j installer. A full list of the command line parameters supported
by the install4j installer can be found on the install4j site.
Chapter
4
Perspectives
Topics:
Editor Perspective
XSLT Debugger Perspective
XQuery Debugger Perspective
Database Perspective
The Oxygen XML Editor interface uses standard interface conventions and
components to provide a familiar and intuitive editing environment across all
operating systems. There are several perspectives that you can use to work with
documents in Oxygen XML Editor. You can change the perspective by selecting
the respective icons in the top-right corner of Oxygen XML Editor or by selecting
the perspective from the Window > Open Perspective menu.
Editor Perspective
The Editor perspective is the most commonly used perspective and it is the default perspective when you start Oxygen
XML Editor for the first time. It is the perspective that you will use to edit the content of your XML documents.
To switch the focus to this perspective, select the Editor button in the top-right corner of Oxygen XML Editor
(or select Editor from the Window > Open perspective menu)
The layout of this perspective is composed of the following components:
Menus
Provides menu driven access to all the features and functions available in Oxygen XML Editor. Most of the menus
are common for all types of documents. However, Oxygen XML Editor also includes some context-sensitive and
framework-specific menus that are only available for a specific context or type of document.
Toolbars
Provides easy access to common and frequently used functions. Each icon is a button that acts as a shortcut to a
related function. Most of the toolbars are common for all types of documents. However, Author mode also includes
framework-specific toolbars, depending on the type of document that is being edited (for example, if you are editing
a DITA document, a DITA Author Custom Actions toolbar is available that includes operations that are specific to
DITA documents). The toolbars can be configured to suit your specific needs.
Editor Pane
The main editing pane where you spend most of your time reading, editing, applying markup, and validating your
documents.
Views
Oxygen XML Editor includes a large variety of views to assist you with editing, viewing, searching, validating,
transforming, and organizing your documents. The most commonly used views are displayed by default and you
can choose to display others by selecting them from the Window > Show View menu. The layout of the views can
also be configured according to your preferences.
When two or more views are displayed, the application provides divider bars. Divider bars can be dragged to a new
position increasing the space occupied by one panel while decreasing it for the other.
As the majority of the work process centers around the Editor area, other views can be hidden using the controls
located on the top-right corner of the view (
).
Some of the most helpful views in the Editor perspective include the following:
Project view - Enables the definition of projects and logical management of the documents they contain.
DITA Maps Manager view - For DITA frameworks, this view helps you organize, manage, and edit DITA
topics and maps.
Open/Find Resource view - Designed to offer advanced search capabilities in various scopes.
Outline view - It provides an XML tag overview and offers a variety of functions, such as modifications follow-up,
document structure change, document tag selection, and elements filtering.
Results view - Displays the messages generated as a result of user actions such as validations, transformation
scenarios, spell checking in multiple files, search operations, and others. Each message is a link to the location
related to the event that triggered the message.
Attributes view - Presents all possible attributes of the current element and allows you to edit attribute values.
You can also use this view to insert attributes in Text mode. Author mode also includes an in-place attribute
editor.
Model view - Presents the current edited element structure model and additional documentation as defined in
the schema.
Elements view - Presents a list of all defined elements that you can insert at the current cursor position according
to the document's schema. In Author mode this view includes tabs that present additional information relative
to the cursor location.
Entities view - Displays a list with all entities declared in the current document as well as built-in ones.
- XML documents
- XSLT stylesheets
- XML Schema
- XSL:FO documents
- XQuery documents
- WSDL documents
- Schematron documents
- JavaScript documents
- Python documents
- CSS documents
- LESS documents
- XProc scripts
- SQL documents
- JSON documents
or select XSLT Debugger from the Window > Open perspective menu.
The workspace in this perspective is organized as an editing area assisted by special helper views. The editing area
contains editor panels that you can split horizontally or vertically in a stack of XML editor panels and a stack of XSLT
editor panels. The XML files and XSL files can be edited in Text mode only.
The layout of this perspective is composed of the following components:
Database Perspective
The Database perspective allows you to manage a database, offering support for browsing multiple connections at the
same time, relational and native XML databases, SQL execution, XQuery execution and data export to XML. To switch
the focus to this perspective, select the Database Debugger button in the top-right corner of Oxygen XML Editor
or select Database from the Window > Open perspective menu.
This perspective offers support for the following databases:
Displaying an XML Schema node in the tree of the database structure (for databases with an XML-specific structure)
with actions for opening, editing, and validating the schemas in an Oxygen XML Editor editor panel.
Handling the values from XML Type columns as XML instance documents that can be opened and edited in an
Oxygen XML Editor editor panel.
Validating an XML instance document added to an XML Type (column of a table, etc.)
For a detailed feature matrix that compares the Academic, Professional, and Enterprise editions of Oxygen XML Editor
go to the Oxygen XML Editor website.
Tip: Connections configured on relational data sources can be used to import data to XML or to generate XML
schemas.
The layout of this perspective is composed of the following components:
Menus
Provides menu driven access to all the features and functions available in the XQuery Debugger.
Toolbars
Contains all actions needed in order to configure and control the debugging process. The toolbars can be configured
to suit your specific needs.
Editor Pane
The main editing pane where you spend most of your time reading, editing, applying markup, and validating your
documents.
Data Source Explorer View
Provides browsing support for the configured connections.
Table Explorer View
Provides table content editing support for inserting new rows, deleting table rows, editing cell values, exporting to
an XML file, and more.
Chapter
5
Editing Modes
Topics:
The main editing area in Oxygen XML Editor includes several editing modes
to suit the type of editing that you want to perform. You can easily switch
between modes by clicking on the desired mode at the bottom of the main editing
pane. Oxygen XML Editor offers the following editing modes:
Back
Create Bookmark (F9) action from the Edit > Bookmarks menu.
A bookmark can be removed by right-clicking its icon on the vertical strip and select Remove or Remove all (Ctrl+F7)
(you can also find the Remove all (Ctrl+F7) action in the Edit > Bookmarks menu).
You can navigate the bookmarks by using one of the actions available on the Edit > Bookmarks > Go to menu or by
using the shortcut keys.
The files are usually organized in an XML project as a collection of folders. There are three types of resources displayed
in the Project view:
Logical folders - marked with a blue icon on Windows and Unix/Linux ( ) and a magenta icon on Mac OS X ( ).
They help you group files within the project. This folder type has no correspondent on the physical disk, since they
are used as containers for related items. Creating and deleting them does not affect the file system on disk. They are
created on the project root or inside other logical folders by using the contextual action New > Logical Folder. The
contextual menu action
Remove from Project can be used to remove them from the project.
Physical folders and files - marked with the operating system-specific icon for folders (usually a yellow icon on
Windows and a blue icon on Mac OS X). These folders and files are mirrors of real folders or files that exist in the
local file system. They are created or added to the project by using contextual menu actions (such as New > File,
New > Folder, Add Folder, etc.) Also, the contextual menu action
Remove from Disk (Shift+Delete) can be
used to remove them from the project and local file system.
Shortcut folders and files - the icons for file shortcuts include a shortcut symbol and names of folder shortcuts are
displayed in bold text. All files and folders that appear as direct descendants of a logical folder are considered
shortcuts. They are created and added with the contextual actions Add Files and Add Folder from the project root.
Both contextual menu actions
Remove from Project and
Remove from Disk (Shift+Delete) are available
for shortcuts.
Remove from Project just removes the shortcut from the project, while
Remove from Disk
(Shift+Delete) removes the shortcut and the physical resource from the local file system.
Figure 10: The Project View with Examples of all Three Types of Resources
Creating New Projects
The following action is available in the Project menu, the New menu in the contextual menu, or from the drop-down
menu in the top-left of the Project view:
New Project
Creates a new, empty project.
).
Add Files
Adds links to files on the local file system.
Add Edited File
Adds a link to the currently edited file in the project.
Managing Project Content
Creating/Adding Files and Folders
You can create linked folders (shortcuts) by dragging and dropping folders from the Windows Explorer / Mac OS X
Finder to the project tree, or by selecting Add Folder in the contextual menu from the project root. To create a file inside
a linked folder, select the New >
Note: The linked files presented in the Project view are marked with a special icon. Linked folders are displayed
in bold text.
You can create physical folders by selecting New > Folder from the contextual menu.
When adding files to a project, the default target is the project root. To change a target, select a new folder. Files may
have multiple instances within the folder system, but cannot appear twice within the same folder.
Removing Files and Folders
To remove one or more linked files or folders, select them in the project tree and press the Delete key, or select the
contextual menu action
Remove from Project. To remove a linked file or folder from both project and local file
system, select the contextual menu action
Remove from Disk (Shift+Delete). The
Remove from Disk
(Shift+Delete) action is also used to remove physical files or folders.
Caution: In most cases this action is irreversible, deleting the file permanently. Under particular circumstances
(if you are running a Windows installation of Oxygen XML Editor and the Recycle Bin is active) the file is
moved to Recycle Bin.
Cut,
Copy, and
XML Refactoring
Opens the XML Refactoring tool wizard that presents refactoring operations to assist you with managing the structure
of your XML documents.
Other Contextual Menu Actions
Other actions that are available in the contextual menu from the project tree include:
Open
Opens the selected file in the editor.
Open with submenu
This submenu allows you to open the selected file with the internal editor, a system application, or other internal
tools: DITA Maps Manager, Archive Browser, MathML Editor, Generate/Convert Schema, WSDL/SOAP Analyzer,
Large File Viewer, Hex Viewer, SVG Viewer.
Open All Files (when a folder or multiple resources are selected)
Opens all the selected files with the corresponding editors.
Show in Explorer (or Show in Finder on OS X)
In Windows, the content of the selected folder or file is presented in a specific explorer window. On MAC OS X,
the parent folder is opened and the selected folder is highlighted in a specific finder window.
Copy Location
Copies an application-specific URL for the selected resource to the clipboard.
Refresh
Refreshes the content and the dependencies between the resources in the Master Files directory.
Find/Replace in Files
Allows you to find and replace text in multiple files.
XPath in Files
Opens the XPath/XQuery Builder view that allows you to compose XPath and XQuery expressions and execute
them over the currently edited XML document.
Open/Find Resource
Opens the Open/Find Resource dialog box.
Check Spelling in Files
Allows you to check the spelling of multiple files.
The content of the resources used to search in is parsed from an index. The indexing is performed both automatically
and on request.
In file paths - Select this option to search for resources by their name or by its path (or a fragment of its path).
In content - Select this option to search through the content of your resources.
In reviews - Select this option to search through the comments, insertions, and deletion in your resources.
Reindex - Reindexes your resources.
Outline View
The Outline view in Text mode displays a general tag overview of the currently edited XML Document. It also shows
the correct hierarchical dependencies between elements. This makes it easier for you to be aware of the document
structure and the way element tags are nested. It allows for fast navigation of the document by displaying the start of
the content of the child elements in the node of the parent element, thus allowing you to quickly see the content of an
element without expanding it in the Outline tree. It also allows you to insert or delete nodes using contextual menu
actions.
By default it is displayed on screen, but if you closed it you can reopen it from Window > Show View > Outline.
The upper part of the view contains a filter box that allows you to focus on the relevant components. If you type a text
fragment in the filter box, the components that match it are presented. For advanced usage you can use wildcards (*, ?)
and separate multiple patterns with commas.
The Outline view offers the following functionality:
Document errors (such as an element inserted in an invalid position, or a wrong attribute name, or a missing required
attribute value) are highlighted in the Outline tree:
Modification Follow-up
When you edit a document, the Outline view dynamically follows the changes that you make, displaying the node that
you modify in the middle of the view. This functionality gives you great insight on the location of your modifications
in the document that you edit.
Drag and Drop Actions in Outline View
Entire XML elements can be moved or copied in the edited document using only the mouse in the Outline view with
drag-and-drop operations. Several drag and drop actions are possible:
If you drag an XML element in the Outline view and drop it on another one in the same panel then the dragged
element will be moved after the drop target element.
If you hold the mouse pointer over the drop target for a short time before the drop then the drop target element will
be expanded first and the dragged element will be moved inside the drop target element after its opening tag.
The drag and drop action in the Outline view can be disabled and enabled from a Preferences page.
Tip: You can select and drag multiple nodes in the Outline view when editing in Author mode.
Outline Filters
The upper part of the Outline view contains a filter box that allows you to focus on the relevant components. Type a
text fragment in the filter box and only the components that match it are presented. For advanced usage you can use
wildcard characters (*, ?) and separate multiple patterns with commas.
The following actions are available in the Settings menu of the Outline view when editing in Text mode:
Filter returns exact matches
The text filter of the Outline view returns only exact matches.
Selection update on cursor move
Controls the synchronization between Outline view and source document. The selection in the Outline view can
be synchronized with the cursor moves or the changes in the editor. Selecting one of the components from the
Outline view also selects the corresponding item in the source document.
Flat presentation mode of the filtered results
When active, the application flattens the filtered result elements to a single level.
Show comments and processing instructions
Show/hide comments and processing instructions in the Outline view.
Show element name
Show/hide element name.
Show text
Show/hide additional text content for the displayed elements.
Show attributes
Show/hide attribute values for the displayed elements. The displayed attribute values can be changed from the
Outline preferences panel.
Configure displayed attributes
Displays the XML Structured Outline preferences page.
The Contextual Menu of the Outline View
The following actions are available from the contextual menu in the Outline view in Text mode:
Append Child
Allows you to select an element (from a drop-down list) that is allowed by the associated schema and inserts it as
a child of the current element.
Insert Before
Allows you to select an element (from a drop-down list) that is allowed by the associated schema and inserts it
immediately before the current element, as a sibling.
Insert After
Allows you to select an element (from a drop-down list) that is allowed by the associated schema and inserts it
immediately after the current element, as a sibling.
The names of the attributes with a specified value are rendered with a bold font, and their value with a plain font.
Note: The names of the attributes with an empty string value are also rendered bold.
Double-click a cell in the Value column to edit the value of the corresponding attribute. If the possible values of the
attribute are specified as list in the schema of the edited document, the Value column acts as a combo box that allows
you to insert the values in the document.
You can sort the attributes table by clicking the Attribute column header. The table contents can be sorted as follows:
for the value of an attribute. After you have entered or selected a value, use the
to add the value to the attribute.
Paste
Depending on the content of the clipboard, the following cases are possible:
If the clipboard contains an attribute and its value, both of them are introduced in the Attributes view. The
attribute is selected and its value is changed if they exist in the Attributes view.
Validate action
Transform action
Check Spelling in Files action
Find All action from the Find/Replace dialog box
Find/Replace in Files dialog box
Search References action
XPath expression results
SQL results
Group the messages by the path of the validated file if there are error messages from a validation action or
spelling errors reported by the Check Spelling in Files action.
No grouping rule for the results of applying an XPath expression.
Set a specific color of the highlights depending on the type of action you make.
Set a maximum number of highlights that the application displays at any given time.
Remove selected
Removes the current selection from the view. This can be helpful if you want to reduce the number of messages or
remove those that have already been addressed or not relevant to your task.
Remove all
Removes all messages from the view.
Results View Contextual Menu Actions
The following actions are available when the contextual menu is invoked in the table grid:
Show message
Displays a dialog box with the full error message, which is useful for a long message that does not have enough
room to be displayed completely in the view.
Previous message
Navigates to the message above the current selection.
Next message
Navigates to the message below the current selection.
Remove selected
Removes selected messages from the view.
Remove all
Removes all messages from the view.
The file path of the document that triggered the output message.
The path of the main file (in the case of a validation scenario, it is the path of the file from which the validation
starts and can be different from the validated file).
Error severity (error, warning, info message, etc.)
Name of validating processor.
Name of validation scenario.
The line and column in the file that triggered the message.
Select All
Extends the selection to all the messages from the view.
Print Results
Sends the complete list of messages to a printer. For each message the included details are the same as the ones for
the Copy action.
Save Results
Saves the complete list of messages in a file in text format. For each message the included details are the same as
the ones for the Copy action.
Save Results as XML
Saves the complete list of messages in a file in XML format. For each message the included details are the same as
the ones for the Copy action.
Group by
A set of Group by toggle actions that allow you to group the messages according to a selected criteria so that they
can be presented in a hierarchical layout. The criteria used for grouping can be the severity of the errors (error,
warning, info message, etc.), the resource name, the description of the message, and so on.
Ungroup all
Removes the grouping rules so that the messages are presented in a continuous list.
Show group columns
If any of the Group by options are selected, you can use this option to show or hide grouping columns.
Restore Defaults
Restores the column size for each column and the grouping rules that were saved in the user preferences the last
time when this view was used. If it is the first time this view is used, the action sets an initial default column size
for each column and a grouping rule that is appropriate for the type of messages. For example:
Group the messages by the path of the validated file if there are error messages from a validation action or
spelling errors reported by the Check Spelling in Files action.
No grouping rule for the results of applying an XPath expression.
Expand All
Expands all the nodes of the tree, which is useful when the messages are presented in a hierarchical mode.
Collapse All
Collapses all the nodes of the tree, which is useful when the messages are presented in a hierarchical mode.
Window > Results Menu
The following actions are also available from the Window > Results menu:
Save Results
Saves the complete list of messages in a file in text format.
Print Results
Sends the complete list of messages to a printer.
Top area that contains a success validation indicator that will turn green if the validation succeeded, or red otherwise.
A more detailed report of the errors is displayed in the tooltip of the validation indicator. If there are multiple errors,
only the first three of them will be presented in the tooltip.
Middle area where the error markers are depicted in red (with a darker color tone for the current selected one). To
limit the number of markers shown open the Preferences dialog box and go to Editor > Document checking >
Maximum number of problems reported per document.
Clicking a marker will highlight the corresponding text area in the editor. The error message is displayed both in the
tool tip and in the error area on the bottom of the editor panel.
The Document checking user preferences are easily accessible from the button displayed at the beginning of the
error message on the bottom of the editor panel.
Bottom area containing two navigation arrows that will go to the next or to the previous error and a button for clearing
all the error markers from the ruler. The same actions can be triggered from menu Document > Automatic
validation > Next Error Ctrl Period (Meta Period on OS X) and Document > Automatic validation > Previous
Error Ctrl Comma (Meta Comma on OS X).
The validation status area is the line at the bottom of the editor panel that presents the message of the current validation
error selected on the right side ruler. Clicking the
Document checking options button opens the document checking
page in Oxygen XML Editor user preferences.
Action
Tab
Shift Tab
Enter
Up Arrow/Page Up
Shift
An arrow sign displayed at the left of the node name indicates that this node has child nodes. To display the children,
click this sign. The expand/collapse actions can be invoked either with the NumPad+ and NumPad- keys, or from the
Expand/Collapse submenu of the contextual menu or from Document > Grid Expand/Collapse.
The following actions are available on the Expand/Collapse menu:
Expand All
Expands the selection and all its children.
Collapse All
Collapses the selection and all its children.
Expand Children
Expands all the children of the selection but not the selection.
Collapse Children
Collapses all the children of the selection but not the selection.
Collapse Others
Collapses all the siblings of the current selection but not the selection.
Back
arrow)
Create Bookmark (F9) action from the Edit > Bookmarks menu.
A bookmark can be removed by right-clicking its icon on the vertical strip and select Remove or Remove all (Ctrl+F7)
(you can also find the Remove all (Ctrl+F7) action in the Edit > Bookmarks menu).
You can navigate the bookmarks by using one of the actions available on the Edit > Bookmarks > Go to menu or by
using the shortcut keys that are listed in that menu (for example, Ctrl+1, Ctrl+2). You can configure these shortcut
keys from Options > Menu Shortcut Keys.
Visual Hints for the Cursor Position
When the cursor is positioned inside a new context, a tooltip will be shown for a couple of seconds displaying the position
of the cursor relative to the current element context.
Here are the common situations that can be encountered:
The cursor is positioned before the first block child of the current node.
The cursor is positioned after the last block element child of the current node.
You are editing the document in one of the following tags display modes: Inline Tags, Partial Tags, No Tags.
The mouse pointer is moved between block elements.
To activate or deactivate this feature, use the Show location tooltip on mouse move option from the Cursor Navigation
preferences page.
Displaying Referenced Content
The references to entities, XInclude, and DITA conrefs are expanded by default in Author mode and the referenced
content is displayed. You can control this behavior from the Author preferences page. The referenced resources are
The top area - A success indicator square will turn green if the validation is successful, red if validation errors are
found, or yellow if validation warnings are found.More details about the errors or warnings are displayed in a tool
tip when you hover over indicator square. If there are numerous errors, only the first three are presented in the tool
tip.
The middle area - Errors are depicted with red markers, and warnings with yellow markers. If you want to limit the
number of markers that are displayed, open the Preferences dialog box and go to Editor > Document checking >
Maximum number of validation highlights.
Clicking a marker will highlight the corresponding text area in the editor. The error or warning message is also
displayed both in a tool tip (when hovering over the marker) and in the message area on the bottom of the editor
panel.
The validation status area at the bottom of the editor panel presents the message of the current validation error.
Clicking the
Document checking options button opens the Document checking user preferences page
The bottom area - Two navigation arrows ( ) allow you to skip to the next or previous error. The same actions can
be triggered from Document > Automatic validation > Next error (Ctrl Period (Meta Period on OS X)) and
Document > Automatic validation > Previous error (Ctrl Comma (Meta Comma on OS X)). Also, the
button can be used to clear all the error markers.
Status messages from every validation action are logged in the Information view.
Whitespace Handling in Author Mode
When you edit a document in Author mode, Oxygen XML Editor must serialize the resulting document as XML. Oxygen
XML Editor serializes the document when you save it or switch to another editing mode. When the document is serialized,
Oxygen XML Editor formats and indents the XML document according to the current format and indent settings.
Minimizing whitespace differences between versions
When serializing a document to XML, Author mode will only format and indent those elements of the document that
have been edited. Any element that has not been edited will be serialized exactly as it was loaded from disk. This is
useful when your content is managed in a version control systems, as it avoids introducing insignificant whitespace
differences between version, which in turn makes diff output easier to read.
Entering whitespace in Author mode
Oxygen XML Editor controls the entry of whitespace characters in Author mode according the XML whitespace rules,
which means it will not let you insert insignificant whitespace. This means that it will not let you insert extra line-breaks
or spaces inside a typical paragraph element, for instance. (Any such whitespace would be normalized away when the
document was serialized to XML, so Oxygen XML Editor is saving you from any surprises when this happens.)
Of course, you will legitimately want to enter additional spaces and returns in some cases, such as code samples. Oxygen
XML Editor will allow this in elements that are configured as preserve space elements according to the XML whitespace
rules. For all of its predefined document types, Oxygen XML Editor is correctly configured to recognize preserve space
elements and to allow you to enter additional spaces in them.
If you are using a predefined document type and you are unable to enter additional whitespace, make sure that you are
using an element from that document type that is intended to be a preserve-space element.
If you are using a custom document type, make sure that it is configured correctly so that Oxygen XML Editor recognizes
that the current element is a preserve-space element.
The files are usually organized in an XML project as a collection of folders. There are three types of resources displayed
in the Project view:
Logical folders - marked with a blue icon on Windows and Unix/Linux ( ) and a magenta icon on Mac OS X ( ).
They help you group files within the project. This folder type has no correspondent on the physical disk, since they
are used as containers for related items. Creating and deleting them does not affect the file system on disk. They are
created on the project root or inside other logical folders by using the contextual action New > Logical Folder. The
contextual menu action
Remove from Project can be used to remove them from the project.
Physical folders and files - marked with the operating system-specific icon for folders (usually a yellow icon on
Windows and a blue icon on Mac OS X). These folders and files are mirrors of real folders or files that exist in the
local file system. They are created or added to the project by using contextual menu actions (such as New > File,
New > Folder, Add Folder, etc.) Also, the contextual menu action
Remove from Disk (Shift+Delete) can be
used to remove them from the project and local file system.
Shortcut folders and files - the icons for file shortcuts include a shortcut symbol and names of folder shortcuts are
displayed in bold text. All files and folders that appear as direct descendants of a logical folder are considered
shortcuts. They are created and added with the contextual actions Add Files and Add Folder from the project root.
Both contextual menu actions
Remove from Project and
Remove from Disk (Shift+Delete) are available
for shortcuts.
Remove from Project just removes the shortcut from the project, while
Remove from Disk
(Shift+Delete) removes the shortcut and the physical resource from the local file system.
Figure 42: The Project View with Examples of all Three Types of Resources
Creating New Projects
The following action is available in the Project menu, the New menu in the contextual menu, or from the drop-down
menu in the top-left of the Project view:
New Project
Creates a new, empty project.
).
Add Files
Adds links to files on the local file system.
Add Edited File
Adds a link to the currently edited file in the project.
Managing Project Content
Creating/Adding Files and Folders
You can create linked folders (shortcuts) by dragging and dropping folders from the Windows Explorer / Mac OS X
Finder to the project tree, or by selecting Add Folder in the contextual menu from the project root. To create a file inside
a linked folder, select the New >
Note: The linked files presented in the Project view are marked with a special icon. Linked folders are displayed
in bold text.
You can create physical folders by selecting New > Folder from the contextual menu.
When adding files to a project, the default target is the project root. To change a target, select a new folder. Files may
have multiple instances within the folder system, but cannot appear twice within the same folder.
Removing Files and Folders
To remove one or more linked files or folders, select them in the project tree and press the Delete key, or select the
contextual menu action
Remove from Project. To remove a linked file or folder from both project and local file
system, select the contextual menu action
Remove from Disk (Shift+Delete). The
Remove from Disk
(Shift+Delete) action is also used to remove physical files or folders.
Caution: In most cases this action is irreversible, deleting the file permanently. Under particular circumstances
(if you are running a Windows installation of Oxygen XML Editor and the Recycle Bin is active) the file is
moved to Recycle Bin.
Cut,
Copy, and
XML Refactoring
Opens the XML Refactoring tool wizard that presents refactoring operations to assist you with managing the structure
of your XML documents.
Other Contextual Menu Actions
Other actions that are available in the contextual menu from the project tree include:
Open
Opens the selected file in the editor.
Open with submenu
This submenu allows you to open the selected file with the internal editor, a system application, or other internal
tools: DITA Maps Manager, Archive Browser, MathML Editor, Generate/Convert Schema, WSDL/SOAP Analyzer,
Large File Viewer, Hex Viewer, SVG Viewer.
Open All Files (when a folder or multiple resources are selected)
Opens all the selected files with the corresponding editors.
Show in Explorer (or Show in Finder on OS X)
In Windows, the content of the selected folder or file is presented in a specific explorer window. On MAC OS X,
the parent folder is opened and the selected folder is highlighted in a specific finder window.
Copy Location
Copies an application-specific URL for the selected resource to the clipboard.
Refresh
Refreshes the content and the dependencies between the resources in the Master Files directory.
Find/Replace in Files
Allows you to find and replace text in multiple files.
XPath in Files
Opens the XPath/XQuery Builder view that allows you to compose XPath and XQuery expressions and execute
them over the currently edited XML document.
Open/Find Resource
Opens the Open/Find Resource dialog box.
Check Spelling in Files
Allows you to check the spelling of multiple files.
The content of the resources used to search in is parsed from an index. The indexing is performed both automatically
and on request.
In file paths - Select this option to search for resources by their name or by its path (or a fragment of its path).
In content - Select this option to search through the content of your resources.
In reviews - Select this option to search through the comments, insertions, and deletion in your resources.
Reindex - Reindexes your resources.
Outline View
The Outline view in Author mode displays a general tag overview of the currently edited XML Document. It also
shows the correct hierarchical dependencies between elements. This makes it easier for you to be aware of the document
structure and the way element tags are nested. It allows for fast navigation of the document by displaying the start of
the content of the child elements in the node of the parent element, thus allowing you to quickly see the content of an
element without expanding it in the Outline tree. It also allows you to insert or delete nodes using contextual menu
actions.
By default it is displayed on screen, but if you closed it you can reopen it from Window > Show View > Outline.
The upper part of the view contains a filter box that allows you to focus on the relevant components. If you type a text
fragment in the filter box, the components that match it are presented. For advanced usage you can use wildcards (*, ?)
and separate multiple patterns with commas.
The Outline view offers the following functionality:
Document errors (such as an element inserted in an invalid position, or a wrong attribute name, or a missing required
attribute value) are highlighted in the Outline tree:
Modification Follow-up
When you edit a document, the Outline view dynamically follows the changes that you make, displaying the node that
you modify in the middle of the view. This functionality gives you great insight on the location of your modifications
in the document that you edit.
Drag and Drop Actions in Outline View
Entire XML elements can be moved or copied in the edited document using only the mouse in the Outline view with
drag-and-drop operations. Several drag and drop actions are possible:
The drag and drop action in the Outline view can be disabled and enabled from a Preferences page.
Tip: You can select and drag multiple nodes in the Outline view when editing in Author mode.
Outline Filters
The upper part of the Outline view contains a filter box that allows you to focus on the relevant components. Type a
text fragment in the filter box and only the components that match it are presented. For advanced usage you can use
wildcard characters (*, ?) and separate multiple patterns with commas.
The following actions are available in the Settings menu of the Outline view when editing in Author mode:
Filter returns exact matches
The text filter of the Outline view returns only exact matches.
Flat presentation mode of the filtered results
When active, the application flattens the filtered result elements to a single level.
Show comments and processing instructions
Show/hide comments and processing instructions in the Outline view.
Show element name
Show/hide element name.
Show text
Show/hide additional text content for the displayed elements.
Show attributes
Show/hide attribute values for the displayed elements. The displayed attribute values can be changed from the
Outline preferences panel.
Configure displayed attributes
Displays the XML Structured Outline preferences page.
The Contextual Menu of the Outline Tree
The contextual menu of the Outline view in Author mode contains the following actions:
Edit Attributes
Allows you to edit the attributes of a selected node. You can find more details about this action in the Attributes
View in Author Mode on page 112 topic.
Edit Profiling Attributes
Allows you to change the profiling attributes defined on all selected elements.
Append Child
Invokes a content completion list with the names of all the elements that are allowed by the associated schema and
inserts your selection as a child of the current element.
Insert Before
Invokes a content completion list with the names of all the elements that are allowed by the associated schema and
inserts your selection immediately before the current element, as a sibling.
The CSS stylesheet associated with the document does not specify a false value for the -oxy-editable property
associated with the element.
The element is entirely included in a deleted Track Changes marker.
The element is part of a content fragment that is referenced in Author mode from another document.
The names of the attributes with a specified value are rendered with a bold font, and their value with a plain font.
Note: The names of the attributes with an empty string value are also rendered bold.
for the value of an attribute. After you have entered or selected a value, use the
to add the value to the attribute.
Paste
Depending on the content of the clipboard, the following cases are possible:
If the clipboard contains an attribute and its value, both of them are introduced in the Attributes view. The
attribute is selected and its value is changed if they exist in the Attributes view.
If the clipboard contains an attribute name with an empty value, the attribute is introduced in the Attributes
view and you can start editing it. The attribute is selected and you can start editing it if it exists in the Attributes
view.
If the clipboard only contains text, the value of the selected attribute is modified.
Select an element or place the cursor inside it and then press the Alt Enter keyboard shortcut.
Double-click any named start tag when the document is edited in one of the following display modes.:
with Attributes,
Full Tags,
Block Tags, or
Inline Tags.
Full Tags
This opens an in-place attributes editor that contains the same content as the Attributes view. By default, this editor
presents the Name and Value fields, with the list of all the possible attributes collapsed.
Cursor - Displays a list of all the elements allowed at the current cursor location. Double-clicking any of the listed
elements inserts that element at the cursor position.
Before - Displays a list of all elements that can be inserted before the element selected in the combo box.
Double-clicking any of the listed elements inserts that element before the element at the cursor position.
After - Displays a list of all elements that can be inserted after the element selected in the combo box. Double-clicking
any of the listed elements inserts that element after the element at the cursor position.
Double clicking an element name in the list surrounds the current selection in the editor panel with the start tags and
end tags of the element. If there is no selection, just an empty element is inserted in the editor panel at the cursor position.
The Entities View
This view displays a list with all entities declared in the current document, as well as built-in ones. Double-clicking one
of the entities will insert it at the current cursor position. You can also sort entities by name and value by clicking the
column headers.
Validate action
Transform action
Check Spelling in Files action
Find All action from the Find/Replace dialog box
Find/Replace in Files dialog box
Search References action
XPath expression results
SQL results
Group the messages by the path of the validated file if there are error messages from a validation action or
spelling errors reported by the Check Spelling in Files action.
No grouping rule for the results of applying an XPath expression.
Set a specific color of the highlights depending on the type of action you make.
Set a maximum number of highlights that the application displays at any given time.
Remove selected
Removes the current selection from the view. This can be helpful if you want to reduce the number of messages or
remove those that have already been addressed or not relevant to your task.
Remove all
Removes all messages from the view.
Results View Contextual Menu Actions
The following actions are available when the contextual menu is invoked in the table grid:
Show message
Displays a dialog box with the full error message, which is useful for a long message that does not have enough
room to be displayed completely in the view.
Previous message
Navigates to the message above the current selection.
Next message
Navigates to the message below the current selection.
Remove selected
Removes selected messages from the view.
Remove all
Removes all messages from the view.
The file path of the document that triggered the output message.
The path of the main file (in the case of a validation scenario, it is the path of the file from which the validation
starts and can be different from the validated file).
Error severity (error, warning, info message, etc.)
Name of validating processor.
Name of validation scenario.
The line and column in the file that triggered the message.
Select All
Extends the selection to all the messages from the view.
Print Results
Sends the complete list of messages to a printer. For each message the included details are the same as the ones for
the Copy action.
Save Results
Saves the complete list of messages in a file in text format. For each message the included details are the same as
the ones for the Copy action.
Save Results as XML
Saves the complete list of messages in a file in XML format. For each message the included details are the same as
the ones for the Copy action.
Group by
A set of Group by toggle actions that allow you to group the messages according to a selected criteria so that they
can be presented in a hierarchical layout. The criteria used for grouping can be the severity of the errors (error,
warning, info message, etc.), the resource name, the description of the message, and so on.
Ungroup all
Removes the grouping rules so that the messages are presented in a continuous list.
Show group columns
If any of the Group by options are selected, you can use this option to show or hide grouping columns.
Restore Defaults
Restores the column size for each column and the grouping rules that were saved in the user preferences the last
time when this view was used. If it is the first time this view is used, the action sets an initial default column size
for each column and a grouping rule that is appropriate for the type of messages. For example:
Group the messages by the path of the validated file if there are error messages from a validation action or
spelling errors reported by the Check Spelling in Files action.
No grouping rule for the results of applying an XPath expression.
Expand All
Expands all the nodes of the tree, which is useful when the messages are presented in a hierarchical mode.
Collapse All
Collapses all the nodes of the tree, which is useful when the messages are presented in a hierarchical mode.
Window > Results Menu
The following actions are also available from the Window > Results menu:
Save Results
Saves the complete list of messages in a file in text format.
Print Results
Sends the complete list of messages to a printer.
Element - displays the CSS rules matching the currently selected element in the Author page (ordered from
most-specific to least-specific)
:before - displays the rules matching the :before pseudo-element
:after - displays the rules matching the :after pseudo-element
Computed - displays all the styling properties that apply to the current element, as a result of all the CSS rules
matching the element
Path - displays the path for the current element, and its attributes, allowing you to quickly see the attributes on all
parent elements, and allows you to copy fragments from this view and paste it into the associated CSS to easily create
new rules
The information displayed in each of the five tabs is updated when you click different elements in the Author editing
view. The first three tabs include the link to the associated CSS source, while the other two tabs simply display the style
properties that match the current element.
Each of the tabbed panes include a contextual menu with the following actions:
unicodeBidi
For instance, to declare an element as being Right to Left, you could use a stylesheet like the one below:
XML File:
<article>
<myRTLpara>RIGHT TO LEFT TEXT</myRTLPara>
</article>
Oxygen XML Editor recognizes the dir attribute on any XML document. The supported values are:
ltr
rtl
lro
rlo
The following XML document types make use of the dir attribute with the above values:
DITA
DocBook
TEI
XHTML
Note: When the inline element tags are visible, the text in the line is arranged according to the BIDI algorithm
after replacing the tags symbols with Object Replacement Characters. This makes it possible to get a different
text arrangement when viewing a document in the No Tags mode versus viewing it in the Full Tags mode.
LEFT-TO-RIGHT EMBEDDING
U+202B (RLE)
RIGHT-TO-LEFT EMBEDDING
U+202D (LRO)
LEFT-TO-RIGHT OVERRIDE
U+202E (RLO)
RIGHT-TO-LEFT OVERRIDE
U+202C (PDF)
U+200E (LRM)
LEFT-TO-RIGHT MARK
U+200F (RLM)
RIGHT-TO-LEFT MARK
To insert Unicode Direction Formatting Codes, use the Character Map dialog box. To easily find such a code, you can
either enter directly the hexadecimal value, or use the Details tab to enter the codes name.
Oxygen XML Editor offers the support for bi-directional text in all the side views (Outline view, Attributes view and
so on) and text fields.
Copy, reference, or move global components, attributes, and identity constraints to a different position and from one
schema to another using the Cut/Copy and Paste/Paste as Reference actions.
Go to the definition of an element or attribute with the Show Definition action.
Search in the diagram using the Find/Replace dialog box or the Quick find toolbar. You can find/replace components
only in the current file scope.
You can expand and see the contents of the imports/includes/redefines in the diagram. In order to edit components
from other schemas the schema for each component will be opened as a separate file in Oxygen XML Editor.
Tip: If an XML Schema referenced by the current opened schema was modified on disk, the change will
be detected and you will be asked to refresh the current schema contents.
* - any string
? - any character
, - patterns separator
If no wildcards are specified, the string to search will be searched as a partial match (like *textToFind*).
The content of the Outline view and the editing area are synchronized. When you select a component in the Outline
view, its definition is highlighted in the editing area.
Pin button.
Basic components: elements, group, attribute, attribute group, complex type, simple type, type alternative.
Compositors and Wildcards: sequence, choice, all, any, any attribute, open content.
Directives: import, include, redefine, override.
Identity constraints: key, keyref, unique, selector, field, assert.
Note: The type alternative, open content, override, and assert components are available for XML Schema
1.1.
Click and hold a graphic symbol from the Palette view, then drag the component into the Design view.
A line dynamically connects the component with the XML schema structure.
Release the component into a valid position.
Note: You cannot drop a component into an invalid position. When you hover the component into an invalid
position, the mouse cursor changes its shape into
. Also, the connector line changes its color from the
usual dark gray to the color defined in the Validation error highlight color option (default color is red).
To watch our video demonstration about the Schema palette and developing XML Schemas, go to
http://oxygenxml.com/demo/Schema_Palette.html and http://oxygenxml.com/demo/Developing_XML_Schemas.html
respectively.
Chapter
6
Editing Documents
Topics:
This chapter explains the editor types available in Oxygen XML Editor and how
to work with them for editing different types of documents.
Inserting Symbols
You can insert symbols by using the Character Map dialog box that can be opened with the Edit >
Insert from
Character Map action. If you have enabled the Symbols toolbar, you can also use the
Symbols drop-down menu
to insert some of the most commonly used symbols and selecting More symbols from that menu will also open the
Character Map dialog box.
hexadecimal
decimal
description
Note: Selecting the description option opens the Details tab. If you enter a character description in
the Search field, the description option is selected automatically.
Character
Character entity - decimal
Character entity - hexadecimal
You can see the character or code that will be inserted in Text mode next to the selections in this section and a box
on the right side of the dialog box allows you to see the character that will be inserted in Author mode. You can
also see the name and range name of a character either at the bottom of the dialog box, or in a tooltip when hovering
the cursor over the character.
Press the Insert button to insert the selected character in the current editor at cursor position. You will see the character
in the editor if the editor font is able to render it. The Copy button copies it to the clipboard without inserting it in the
editor.
Note: The Character Map dialog box cannot be used to insert Unicode characters in the Grid editor.
Accordingly, the Insert button of the dialog box will be disabled if the current document is edited in Grid mode.
Use a font editor (such as FontForge) to combine multiple true type fonts into a single custom font.
Install the font file into the dedicated font folder of your operating system.
In Oxygen XML Editor, open the Preferences dialog box and go to Appearance > Fonts.
Click the Choose button in the Editor option and select your custom font from the drop down list in the subsequent
dialog box.
5. Restart Oxygen XML Editor for the font changes to take full effect.
Recently used - Contains the list of the most recently used files.
New Document - Contains the list of all supported document types. This list includes XML, XSL, XML Schema,
Document Type Definition, Relax NG Schema, XQuery, web Services Definition Language, Schematron Schema,
CSS, Text, PHP, JavaScript, Java, C, C++, Batch, Shell, Properties, SQL, XML Catalog, and PERL.
Global templates - Contains the list of predefined templates as well as user-defined custom templates. You can
add custom template files to the templates folder of the Oxygen XML Editor installation directory. You can
also specify an additional directory to use for templates in the Document Templates Preferences page.
Note: You can also use editor variables in the template file content and they will be expanded when the
files are opened.
Framework templates - Contains the list of templates defined in the Document Type configuration dialog box,
Templates tab.
Customize - action available only for XML, XML Schema, Schematron, and XSL documents. Depending on
the document type, you can set different properties before you create the file.
Create - uses default settings to create a file.
If you select Create, Oxygen XML Editor opens the new file in the editor view.
4. If you select Customize, Oxygen XML Editor opens the following dialog box. You can customize different options
depending on the document type you select.
Schema URL - Specifies the path to the schema file. When you select a file, Oxygen XML Editor analyzes
its content and tries to fill the rest of the dialog box.
Schema type - Allows you to select the schema type. The following options are available: XML Schema,
DTD, RelaxNG XML syntax, RelaxNG compact syntax, and NVDL.
Public ID - Specifies the PUBLIC identifier declared in the document prolog.
Namespace - Specifies the document namespace.
Prefix - Specifies the prefix for the namespace of the document root.
Root Element - Populated with elements defined in the specified schema, enables selection of the element
used as document root.
Description - A small description of the selected document root.
Add optional content - If you select this option, the elements, and attributes defined in the XML Schema as
optional, are generated in the skeleton XML document.
Add first Choice particle - If you select this option, Oxygen XML Editor generates the first element of an
xs:choice schema element in the skeleton XML document. Oxygen XML Editor creates this document
in a new editor panel when you click OK.
Stylesheet version - Allows you to select the Stylesheet version number. You can select from: 1.0, 2.0, and
3.0.
Add documentation annotations - Enable this option to generate the stylesheet documentation.
Default XML Schema version - Uses the XML Schema version defined in the XML Schema preferences
page.
XML Schema 1.0 - Sets the minVersion attribute to 1.0 and the maxVersion attribute to 1.1.
XML Schema 1.1 - Sets the minVersion attribute to 1.1.
Target namespace - specifies the schema target namespace.
New and
Delete buttons.
Tip: For further details on how you can set the version of an XML Schema, go to Setting the XML
Schema Version.
Schematron version - Specifies the Schematron version. Possible options: 1.5 and ISO.
Note: Starting with version 16.0 of Oxygen XML Editor, the support for Schematron 1.5 is deprecated.
It is recommended to use ISO Schematron instead.
To easily create a Schematron document the application offers two predefined document templates, ISO Schematron
and Schematron 1.5.
5. Press Create to create the file.
Opening Documents
To open a document in Oxygen XML Editor, do one of the following:
Go to File >
Open (Ctrl O (Meta O on OS X)) or click the
Open toolbar button to display the Open dialog
box. The start folder of the Open dialog box can be either the last folder visited by this dialog box or the folder of
the currently edited file. This can be configured in the user preferences.
Go to File >
Open URL or click the
Open URL toolbar button to display the Open URL dialog box, which
allows you to access any resource identified through an URL (defined by a protocol, host, resource path, and an
optional port). The following actions are available in the drop-down action list:
Browse for local file - Opens a local file browser dialog box allowing you to select a local file.
Browse for remote file - Displays the Open using FTP/SFTP dialog box that allows you to open a remotely
stored document.
Browse for archived file - Displays the Archive Browser dialog box that allows you to browse the content
of an archive a choose a file to open in Oxygen XML Editor.
Browse Data Source Explorer - Opens the Data Source Explorer that allows you to browse the data
sources defined in the Data Sources preferences page.
Tip: You can get to the Data Sources preferences page, using the Configure Database Sources shortcut
from the Open URL dialog box.
Click the
Go to File >
Reload to load the last saved file content. All unsaved modifications are lost.
Go to File > Reopen to reopen one of the recently opened document files. The list containing recently opened files
can be emptied by invoking the Clear history action.
Select the Open action from the contextual menu of the Project view. This opens the selected file from the Project
view.
scriptName [pathToXMLFile1] [pathToXMLFile2] ... where scriptName is the name of the startup script for your
platform (oxygen.bat on Windows, oxygen.sh on Unix/Linux, oxygenMac.sh on Mac OS) and
pathToXMLFileN is the name of a local XML file.
an XML file and a schema file to be associated automatically to the file and used for validation and content completion:
scriptName -instance pathToXMLFile -schema pathToSchemaFile -schemaType
XML_SCHEMA|DTD_SCHEMA|RNG_SCHEMA|RNC_SCHEMA -dtName documentTypeName
where scriptName is the name of the startup script for your platform (oxygen.bat on Windows, oxygen.sh on
Unix/Linux, oxygenMac.sh on Mac OS), pathToXMLFile is the name of a local XML file, pathToSchemaFile is the
name of the schema which you want to associate to the XML file, the four constants (XML_SCHEMA,
DTD_SCHEMA, RNG_SCHEMA, RNC_SCHEMA) are the possible schema types (W3C XML Schema, DTD,
Relax NG schema in full syntax, Relax NG schema in compact syntax). The next parameter, documentTypeName,
specifies the name of the Document Type for which the schema is defined. If the Document Type is already set in
preferences, its schema and type are updated.
The two possibilities of opening files at startup by specifying them in the command line are explained also if the startup
script receives one of the -h or --help parameters.
Opening a File at a Specific Position Using the Command Line Interface
Oxygen XML Editor offers support for opening a file at a specific position using the command line interface, by
transmitting parameters to the Oxygen XML Editor batch script file. The following methods are available, depending
on how you identify the position needed:
1. Specific position values (line and column number , or character offset)
Oxygen XML Editor supports the following position parameters:
file:samples/personal.xml#line=4
file:samples/personal.xml#line=4column=5
file:samples/personal.xml#line=4;column=5
file:samples/personal.xml#char=334
file:samples/personal.xml#element(1/3)
file:samples/personal.xml#titleID
Saving Documents
You can save the document you are editing with one of the following actions:
File >
Save toolbar button - If the document was not yet saved, it displays the Save As dialog box.
File > Save As - Displays the Save As dialog box, used either to name and save an open document to a file or to
save an existing file with a new name.
File > Save To URL - Displays the Save to URL dialog box that can be used to save a file identified by its URL
(defined by a protocol, host, resource path, and an optional port). Use the drop-down action list to choose one of the
available save actions:
Save.
Browse for local file - Opens a local file browser dialog box allowing you to save the document locally.
Browse for remote file - Displays the Save to URL dialog box that allows you to save the document to a
remote location (accessible through FTP, SFTP or WebDAV).
Browse for archived file - Displays the Archive Browser dialog box that allows you to save the document
inside an archive.
Browse Data Source Explorer - Opens the Data Source Explorer that allows you to browse the data
sources defined in the Data Sources preferences page.
Tip: You can get to the Data Sources preferences page, using the Configure Database Sources shortcut
from the Save to URL dialog box.
File > Save All - Saves all open documents. If any document does not have a file, displays the Save As dialog box.
Browse for remote file option from the drop down action list.
In the server combo you can specify the protocol (HTTP, HTTPS or FTP) and the host name or IP of the server.
Tip: When specifying a URL, follow these rules:
To access an FTP server, write the protocol, host, and port (if using a non-standard one), like
ftp://server.com or ftp://server.com:7800/.
To access a WebDAV server, write the path to the directory of the WebDAV repository along with the
protocol and the host name, like
https://www.some-webdav-server.com:443/webdav-repository/.
Important:
Make sure that the repository directory ends in a slash "/", like
https://www.some-webdav-server.com:443/webdav-repository/
By pressing the Connect button the directory listing will be shown in the component below. If the selected URL
points to a SharePoint server, a dedicated SharePoint browsing component is presented. When Autoconnect is
selected, the browse action is performed every time when you open the dialog box.
If you are browsing a WebDAV or FTP repository, the items are presented in a tree-like fashion. You can browse
the directories, and make multiple selections. Additionally, you may use the Rename, Delete, and New Folder
actions to manage the file repository.
Note: The file names are sorted in a case-insensitive way.
When you browse a SharePoint repository, a specialized component renders the SharePoint site content.
Depending on the type of node, a contextual menu offers customized actions that can be performed on that node.
The contextual menu of a folder allows you to create new folders and documents, import folders and files, and
to rename and delete the folder.
Note: The rename and delete actions are not available for library root folders (folders located at first
level in a SharePoint library).
Each library node display next to its name a drop down box where you can select the current library view. This
functionality is also available on the node's contextual menu, under the Current View submenu.
The content of a folder is displayed in a tabular form, where each row represents the properties of a folder or
document. The list of columns and the way the documents and folders are organized depends on the currently
selected view of the parent library.
You can filter and sort the displayed items. To display the available filters of a column, click the filter widget
located on the column's header. You can apply multiple filters at the same time.
Note: A column can be filtered or sorted only if it was configured this way on the server side.
The editable combo box, in which it can be specified directly the URL to be opened or saved.
Tip: You can type a URL, such as http://some.site/test.xml (if the file is accessible through
normal HTTP protocol), or ftp://[email protected]/home/test.xml (if the file is accessible
through anonymous FTP).
This combo box is also displaying the current selection when the user changes selection by browsing the tree of
folders and files on the server.
Export a certificate to a local file using any HTTPS-capable Web browser (for example Internet Explorer).
Import the certificate file into the JRE using the keytool tool that comes bundled with Oxygen XML Editor.
Kerberos - An authentication protocol that works on the basis of tickets to allow nodes communicating over a
non-secure network to prove their identity to one another in a secure manner.
Single Sign-on
Oxygen XML Editor implements the Single sign-on property (meaning that you can log on once and gain access to
multiple services without being prompted to log on for each of them), based on the Kerberos protocol and relies on a
ticket-granting ticket (TGT) that Oxygen XML Editor obtains from the operating system.
To turn on the Kerberos-based authentication, you need to add the following system property in the .vmoptions
configuration file or start-up script:
-Djavax.security.auth.useSubjectCredsOnly=false
Searching Documents
Oxygen XML Editor includes advanced search capabilities to help you locate documents and resources.
The content of the resources used to search in is parsed from an index. The indexing is performed both automatically
and on request.
In file paths - Select this option to search for resources by their name or by its path (or a fragment of its path).
In content - Select this option to search through the content of your resources.
In reviews - Select this option to search through the comments, insertions, and deletion in your resources.
Reindex - Reindexes your resources.
Open/Find Resource (Ctrl Shift R (Meta Shift R on OS X)). You can also click the
Search for file action, available for some URL input fields.
In file paths - Select this option to search for resources by their name or by its path (or a fragment of its path).
In content - Select this option to search through the content of your resources.
In reviews - Select this option to search through the comments, insertions, and deletion in your resources.
Options - Opens the Open/Find Resource preferences page.
A contextual menu available on each search result provides actions applicable to the document that contains it. These
actions allow you to:
When you perform a search a caching mechanism is used to gather the paths of all files linked in the current project.
When the first search is performed, all project files are indexed and added to the cache. The next search operations use
the information extracted from the cache, thus improving the processing time. The cache is kept for the currently loaded
project only, so when you perform a search in a new project the cache is rewritten. Also, the cache is reset when you
press the Reindex button.
Important: Files larger than 2GB are not indexed.
If there is no file found that matches your file pattern or text search, a possible cause is that the file you are searching
for was added to the Oxygen XML Editor project after the last caching operation. In this case, re-indexing the project
files from the Reindex button enables the file to be found. The date and time of the last index operation are displayed
below the file list.
Once you find the files that you want to open, select them in the list and press the Open button. Each of the selected
files is opened in the editor associated with the type of the file.
To watch our video demonstration about the Open/Find Resource dialog box and search capabilities, go to
http://oxygenxml.com/demo/Open_Find_Resource.html.
Searching in Content
To perform a search through the content of your resources, open the Open/Find Resources dialog box or the Open/Find
Resource view, enable the in content option, and in the search field enter the terms that you want to search for.
The Open/Find Resource feature is powered by Apache Lucene. Apache Lucene is a free open source information
retrieval software library.
You can use the Open/Find Resource dialog box and the Open/Find Resource view either to perform a simple text
search or to perform a more complex search using the Apache Lucene - Query Parser Syntax. Using the Apache Lucene
- Query Parser Syntax means you can perform any of the following searches:
Term Searches
Use the Open/Find Resource view or dialog box to search for plain text:
Garden Preparation
Fuzzy Searches
If you are not sure of the exact form of a term that you are interested in, use the fuzzy search to find
the terms that are similar to what you introduce in the Open/Find Resource view or dialog box. To
perform a fuzzy search, use the ~ symbol after the word that you are not sure of:
Garden Preparing~
Proximity Searches
Use proximity searches to find words that are within a specific distance away. To perform a proximity
search, use the ~ symbol at the end of your search. For example, to search for the word Garden and
the word Preparation within 6 words of each other use:
"Garden Preparation"~6
Range Searches
Use range searches to match documents whose element values are between the lower and upper bound
specified in the range query. For example, to find all documents whose titles are between Iris and
Lilac, use:
title:{Iris TO Lilac}
The curly brackets denote an exclusive query. The results you get when using this query are all the
documents whose titles are between Iris and Lilac, but not including Iris and Lilac. To create an
inclusive query use square brackets:
title:[Iris to Lilac]
To search for documents that contain either the word Garden or the word Preparation, use:
Garden OR Preparation
To search for documents that contain Garden Preparation but not Preparation of the Flowers, use:
"Garden Preparation" - "Preparation of the Flowers"
For example, if you search for *-preferences-page you will find all the resources that contain the -preferences-page
fragment in their name. If you search for */samples/*.gif, you will find all the .gif images from the samples directory.
Searching in Reviews
To perform a search in the edits of your resources, open the Open/Find Resource dialog box or the Open/Find Resource
view, enable the In reviews option, and in the search field enter the terms that you want to search for.
The following options are available:
Type - Specifies whether you want to search for content in comments, insertions, deletions, or highlighted content.
Author - Displays all the authors of the edits in your resources. The authors are collected when indexing. You can
set a specific author for your search or all of them.
Time- Specifies the time when the edits that you are searching through were created.
Both the view and the dialog box display the edits that contain the search results and their parent topics along with a
short description. To hide this description, go to Settings and disable the Show Description option.
Technical Aspects
When Oxygen XML Editor performs the indexing of your resources, the refereed content from your documents is not
taken into account. For example, when DITA documents are indexed, the content from the conref elements is not
Closing Documents
To close open documents, use one of the following methods:
Click Close(Ctrl W (Meta W on OS X)) in the contextual menu of an open tab (or from the File menu) to close it.
Click Close Other Files in the contextual menu of an open tab (or from the File menu) to close all the open tabs
except the selected one.
Click Close All(Ctrl Shift F4 (Meta Shift F4 on OS X)) in the contextual menu of an open tab (or from the File
menu) to close all open tabs.
Character encoding.
Full path on the file system.
Schema used for content completion and document validation.
Document type name and path.
Associated transformation scenario.
Read-only state of a file.
Bidirectional text (left to right and right to left) state.
Total number of characters in the document.
Line width.
Indent with tabs state.
Indent size.
The view can be accessed from Window > Show View > Properties.
Logical Folder
Creates a logical folder in the tree structure (the icon is a magenta folder on Mac OS X - ).
New > Logical Folders from Web
Replicates the structure of a remote folder accessible over FTP/SFTP/WebDAV, as a structure of logical folders.
The newly created logical folders contain the file structure of the folder it points to.
Add Folder
Adds a link to a physical folder, whose name and content mirror a real folder that exists in the local file system (the
icon of this action is different on Mac OS X
).
Add Files
Adds links to files on the local file system.
Add Edited File
Adds a link to the currently edited file in the project.
Using Linked Folders (Shortcuts)
Another easy way to organize your XML working files is to place them in a directory and then to create a corresponding
linked folder in you project. If you add new files to that folder, you can simply use the
Refresh (F5) action from
the toolbar or contextual menu and the Project view will display the existing files and subdirectories. If your files are
Add Folder in the contextual menu from the project root. Linked folders
are displayed in the Project view with bold text. To create a file inside a linked folder, select the New >
from the contextual menu. The linked files presented in the Project view are marked with a special icon.
File action
Note: Files may have multiple instances within the folder system, but cannot appear twice within the same
folder.
For much more information on managing projects and their content, see the The Project View on page 71 section.
For more details about how you can share projects with other users, see the Sharing a Project - Team Collaboration on
page 164 section.
Use only Master Files, if enabled - Restricts Oxygen XML Editor to perform the search and refactor
operations starting from the master files that are defined for the current resource. This option is available
when you select Project in the Select the scope for Search and Refactor operations dialog box and the
Master Files support is enabled.
Working sets - Allow you to specify the set of files on which the search and refactor operations will act on.
The files are usually organized in an XML project as a collection of folders. There are three types of resources displayed
in the Project view:
Logical folders - marked with a blue icon on Windows and Unix/Linux ( ) and a magenta icon on Mac OS X ( ).
They help you group files within the project. This folder type has no correspondent on the physical disk, since they
are used as containers for related items. Creating and deleting them does not affect the file system on disk. They are
created on the project root or inside other logical folders by using the contextual action New > Logical Folder. The
contextual menu action
Remove from Project can be used to remove them from the project.
Physical folders and files - marked with the operating system-specific icon for folders (usually a yellow icon on
Windows and a blue icon on Mac OS X). These folders and files are mirrors of real folders or files that exist in the
local file system. They are created or added to the project by using contextual menu actions (such as New > File,
New > Folder, Add Folder, etc.) Also, the contextual menu action
Remove from Disk (Shift+Delete) can be
used to remove them from the project and local file system.
Shortcut folders and files - the icons for file shortcuts include a shortcut symbol and names of folder shortcuts are
displayed in bold text. All files and folders that appear as direct descendants of a logical folder are considered
shortcuts. They are created and added with the contextual actions Add Files and Add Folder from the project root.
Both contextual menu actions
Remove from Project and
Remove from Disk (Shift+Delete) are available
for shortcuts.
Remove from Project just removes the shortcut from the project, while
Remove from Disk
(Shift+Delete) removes the shortcut and the physical resource from the local file system.
Figure 71: The Project View with Examples of all Three Types of Resources
Creating New Projects
The following action is available in the Project menu, the New menu in the contextual menu, or from the drop-down
menu in the top-left of the Project view:
New Project
Creates a new, empty project.
Creating New Project Items
The following actions are available by selecting New from the contextual menu, when invoked from the Project view:
New >
File
Opens a New file dialog box that helps you create a new file and adds it to the project structure.
New >
Folder
Opens a New Folder dialog box that allows you to specify a name for a new folder and adds it to the structure of
the project.
New >
Logical Folder
Available when invoked from the project root, this action creates a logical folder in the tree structure (the icon is a
magenta folder on Mac OS X - ).
New > Logical Folders from Web
Available when invoked from the project root, this action replicates the structure of a remote folder accessible over
FTP/SFTP/WebDAV, as a structure of logical folders. The newly created logical folders contain the file structure
of the folder it points to.
Add Content to a Logical Folder
The project itself is considered a logical folder. You can add content to a logical folder using one of the actions available
in the contextual menu, when invoked from the project root:
).
Add Files
Adds links to files on the local file system.
Add Edited File
Adds a link to the currently edited file in the project.
Managing Project Content
Creating/Adding Files and Folders
You can create linked folders (shortcuts) by dragging and dropping folders from the Windows Explorer / Mac OS X
Finder to the project tree, or by selecting Add Folder in the contextual menu from the project root. To create a file inside
a linked folder, select the New >
Note: The linked files presented in the Project view are marked with a special icon. Linked folders are displayed
in bold text.
You can create physical folders by selecting New > Folder from the contextual menu.
When adding files to a project, the default target is the project root. To change a target, select a new folder. Files may
have multiple instances within the folder system, but cannot appear twice within the same folder.
Removing Files and Folders
To remove one or more linked files or folders, select them in the project tree and press the Delete key, or select the
contextual menu action
Remove from Project. To remove a linked file or folder from both project and local file
system, select the contextual menu action
Remove from Disk (Shift+Delete). The
Remove from Disk
(Shift+Delete) action is also used to remove physical files or folders.
Caution: In most cases this action is irreversible, deleting the file permanently. Under particular circumstances
(if you are running a Windows installation of Oxygen XML Editor and the Recycle Bin is active) the file is
moved to Recycle Bin.
Moving Files and Folders
You can move the resources of the project with drag and drop operations on the files and folders of the tree.
You can also use the usual
Cut,
Copy, and
Copy and
Paste
You can also move certain types of files (such as XML, XML Schema, Relax NG, WSDL, and XSLT) by using the
Refactoring > Move resource action from the contextual menu. This action opens the Move resource dialog box that
includes the following options:
Destination - Presents the path to the current location of the resource you want to move and gives you the option to
introduce a new location.
New name - Presents the current name of the moved resource and gives you the option to change it.
Update references of the moved resource(s) - Enable this option to update the references to the resource you are
moving, based upon the selected scope. You can select or configure the scope by using the
button.
New name - Presents the current name of the edited resource and allows you to modify it.
Update references of the renamed resource - Enable this option to update the references to the resource you are
renaming. You can select or configure the scope by using the
button.
You many want to use a fresh install for this procedure, to make sure that you do not copy personal or local preferences.
In the Project view, create a project or open an existing one.
Open the Preferences dialog box.
Configure the options in each preferences page that you want to be included in the project file and switch the storage
preference to Project Options in each page.
Note: Some pages do not have the Project Options switch, since the options they host might contain
sensitive data (such as passwords, for example) that is unsuitable for sharing with other users.
When the module is validated, Oxygen XML Editor automatically identifies the master files that include the module
and validates all of them.
The Content Completion Assistant presents all the components that are collected, from the master files to the modules
they include.
The Outline view displays all the components that are defined in the master files hierarchy.
The master files that are defined for the current module determines the scope of the search and refactoring actions.
Oxygen XML Editor performs the search and refactoring actions in the context that the master files determine, thus
improving the speed of execution.
Use the
folder.
Detect Master Files from Project option, available in the contextual menu of the Master Files
Both of these options display the Detect Master Files wizard. In the first panel you can select the type of master files
you want Oxygen XML Editor to detect. In the subsequent panel the detected master files are presented in a tree-like
fashion.The resources are grouped into three categories:
Possible master files - the files presented on the first level in this category are not imported/included from other files.
These files are most likely to be set as master files.
Cycles - the files that are presented on the first level have circular dependencies between them. Any of the files
presented on the first level of a cycle is a possible master file.
Standalone - files that do not include/import other files and are also not included/imported themselves. It is not
necessary to set them as master files.
To set them as master files, enable their check-boxes. Oxygen XML Editor marks all the children of a master file as
modules. Modules are rendered in gray and their tool-tip presents a list of their master files. A module can be accessed
from more than one master file.
The master files that are already defined in the project are automatically marked in the tree and cannot be removed. The
only way to disable a master file is to delete it from the Master Files folder.
The next panel displays a list with the selected master files. Click the Finish button to add the master files in the Master
Files folder.
You can use the Select Master Files option to automatically mark all master files. This action sets all the resources
from the Possible Master Files category and the first resource of each Cycle as master files .
Tip: We recommend you to only add top-level files (files that are at the root of the include/import graph) in
the Master Files directory. Keep the file set to a minimum and only add files that import or include other
files.
Attention: If the Master Files Support is disabled, the Master Files directory is rendered only if it contains
master files.
Select
Add Files or
Add Edited File from the contextual menu of the Master Files directory.
Drag and drop files into the Master Files directory.
You can view the master files for the current resource in the Properties dialog of the Project view and the master files
for the current editor in the Properties and Information views.
Project Validation and Transformation
The Master Files Support is also useful for project level validation and transformation. When you hover the cursor
over a file in the Master Files directory, Oxygen XML Editor displays the
Validate and
Transform buttons
at the right of the file. Select one of these buttons to run a transformation, or validation scenario. If the current node is
selected, Oxygen XML Editor executes a batch transformation and validation. If the current node is not selected, Oxygen
XML Editor executes the validation and transformation for the current node only. The behavior of these actions is the
same as the behavior of the transformation actions that are available in the contextual menu.
Note: The tooltip of the
can apply.
Validate and
When you hover the cursor over the Master Files directory itself, apart from the
Validate and
Transform
place the cursor at the right side of a valid hexadecimal sequence, then press Alt X (Meta Shift X on OS
X) on your keyboard
select a valid hexadecimal sequence, then press Alt X (Meta Shift X on OS X) on your keyboard
If you select the Rename current element prefix option, the application will recursively traverse the current
element and all its children.
Note: For example, to change the xmlns:p1="ns1" association in the current element to
xmlns:p5="ns1", if the xmlns:p1="ns1" association is applied on the parent element, then
Oxygen XML Editor will introduce xmlns:p5="ns1" as a new declaration in the current element
and will change the prefix from p1 to p5. If p5 is already associated with another namespace in
the current element, then the conflict will be displayed in a dialog box. By pressing OK, the prefix
is modified from p1 to p5 without inserting a new declaration.
If you select the Rename current prefix in all document option, the application will apply the change on
the entire document.
To also apply the action inside attribute values, check the Rename also attribute values that start with
the same prefix checkbox.
If the Cursor position between tags option is enabled in the Content Completion Preferences page, the
cursor is placed between the start and end tag.
Closing tag auto-expansion - This feature helps save some keystrokes by automatically inserting a closing tag when
you insert a complete start tag and the cursor is automatically placed in between the start and end tags. For instance,
after entering a start <tag>, the corresponding closing </tag> is automatically inserted and the cursor is placed
between the two (<tag>|</tag>.
Auto-rename matching tag - When you edit the name of a start tag, Oxygen XML Editor will mirror-edit the name
of the matching end tag. This feature can be controlled from the Content Completion option page.
Auto-breaking the edited line - The Hard line wrap option automatically breaks the edited line when its length
exceeds the maximum line length defined for the format and indent operation.
Indent on Enter - The Indent on Enter option indents the new line inserted when you press Enter.
Smart Enter - The Smart Enter option inserts an empty line between the start and end tags. If you press Enter between
a start and end tag, the action places the cursor in an indented position on the empty line between the lines that contain
the start and end tag.
Double-click - A double-click selects a certain text, depending on the position of the click in the document:
If the click position is on a start tag or end tag, then the element name is selected.
If the click position is immediately after the opening quote or immediately before the closing quote of an attribute
value, then the entire attribute value is selected.
Otherwise, a double-click selects contiguous text.
Triple-click - A triple-click selects entire regions of text, depending on the click position:
If the click position is on a start or end tag, then the entire tag is selected, including the start and end tags, and
the content in between.
If the click position is after a start tag or before an end tag, then the entire content of the element without the start
and end tags is selected.
If the click position is before a start tag or after an end tag, then the entire tag is selected, including the start and
end tags, and the content in between.
If the click position is immediately before an attribute, then the entire attribute and its value is selected.
If the click position is in between the opening and closing quotes of an attribute value, then the entire attribute
value is selected.
Otherwise, it selects the entire current line of text.
Any absolute URL (URLs that have a protocol), regardless of their location in the document.
URI attributes such as: schemaLocation, noNamespaceSchemaLocation, href and others.
Processing instructions used for associating resources, xml-models, xml-stylesheets.
Ctrl Shift Y (Meta Shift Y on OS X) (Document > Edit > Toggle Line Wrap)
Enables or disables line wrapping. When enabled, if text exceeds the width of the displayed editor, content is wrapped
so that you do not have to scroll horizontally.
Inserting or Opening a File at Cursor Location
When editing content in Text mode, the following actions (in regards to inserting, opening, or comparing files) are
available in the Document > File menu:
Insert File
Inserts the content of the file with the specified file path into the current document, at the current position of the
cursor.
Open File at Cursor
Opens the file at the cursor position in a new panel. If the file path represents a directory path, it will be opened in
system file browser. If the file at the specified location does not exist, an error dialog box is displayed and it includes
a Create new file button that starts the New document wizard. This allows you to choose the type or the template
for the file. If the action succeeds, the file is created with the referenced location and name and is opened in a new
editor panel.
Open File at Cursor in System Application
Opens the file (identified by its link) or web page (identified by a web link) found at cursor position. The target is
opened in the default system application associated with that file type.
Compare
Opens the current file in the Compare Files tool.
Formatting and Indenting XML Documents
Oxygen XML Editor creates XML documents using several different edit modes. In text mode, you as the author decide
how the XML file is formatted and indented. In the other modes, and when you switch between modes, Oxygen XML
Editor must decide how to format and indent the XML. Oxygen XML Editor will also format and indent your XML for
you in text mode if you use one of the Format and Indent options:
A number of settings affect how Oxygen XML Editor formats and indents XML. Many of these settings have to do with
how whitespace is handled.
Significant and insignificant whitespace in XML
XML documents are text files that describe complex documents. Some of the white space (spaces, tabs, line feeds, etc.)
in the XML document belongs to the document it describes (such as the space between words in a paragraph) and some
of it belongs to the XML document (such as a line break between two XML elements). Whitespace belonging to the
XML file is called insignificant whitespace. The meaning of the XML would be the same if the insignificant whitespace
were removed. Whitespace belonging to the document being described is called significant whitespace.
Knowing when whitespace is significant or insignificant is not always easy. For instance, a paragraph in an XML
document might be laid out like this:
<p>
NO Freeman shall be taken or imprisoned, or be disseised of his Freehold, or Liberties, or
free Customs, or be outlawed, or exiled, or any other wise destroyed; nor will We not pass
upon him, nor condemn him, but by lawful judgment of his Peers, or by the <xref
href="http://en.wikipedia.org/wiki/Law_of_the_land" format="html" scope="external">Law of the land</xref>.
We will sell to no man, we will not deny or defer to any man either Justice or Right.
</p>
By default, XML considers a single whitespace between words to be significant, and all other whitespace to be
insignificant. Thus the paragraph above could be written all on one line with no spaces between the start tag and the
first word or between the last word and the end tag and the XML parser would see it as exactly the same paragraph.
Removing the insignificant space in markup like this is called normalizing space.
In some cases, all the spaces inside an element should be treated as significant. For example, in a code sample:
<codeblock>
class HelloWorld
{
public static void main(String args[])
{
System.out.println("Hello World");
}
}
</codeblock>
Here every whitespace character between the codeblock tags should be treated as significant.
How Oxygen XML Editor determines when whitespace is significant
When Oxygen XML Editor formats and indents an XML document, it introduces or removes insignificant whitespace
to produce a layout with reasonable line lengths and elements indented to show their place in the hierarchy of the
document. To correctly format and indent the XML source, Oxygen XML Editor needs to know when to treat whitespace
as significant and when to treat it as insignificant. However it is not always possible to tell this from the XML source
file alone. To determine what whitespace is significant, Oxygen XML Editor assigns each element in the document to
one of four categories:
Ignore space
In the ignore space category, all whitespace is considered insignificant. This generally applies to content that consists
only of elements nested inside other elements, with no text content.
Normalize space
In the normalize space category, a single whitespace character between character strings is considered significant
and all other spaces are considered insignificant. This generally applies to elements that contain text content only.
This content can be normalized by removing insignificant whitespace. Insignificant whitespace may then be added
to format and indent the content.
Whitespace between two child elements embedded in the text is normalized to a single space (rather than to zero
spaces as would normally be the case for a text node with only whitespace characters, or the space between
elements generally).
The lack of whitespace between a child element embedded in the text and either adjacent text or another child
element is considered significant. That is, no whitespace can be introduced here when formatting and indenting
the file.
For example:
<p>The file is located in <i>HOME</i>/<i>USER</i>/hello. This is s <strong>big</strong>
<emphasis>deal</emphasis>.
</p>
In this example, whitespace should not be introduced around the i tags as it would introduce extra significant
whitespace into the document. The space between the end </strong> tag and the beginning <emphasis> tag
should be normalized to a single space, not zero spaces.
Preserve space
In the preserve space category, all whitespace in the element is regarded as significant. No changes are made to the
spaces in elements in this category. Note, however, that child elements may be in a different category, and may be
treated differently.
Attribute values are always in the preserve space category. The spaces between attributes in an element tag are always
in the default space category.
Oxygen XML Editor consults several pieces of information to assign an element to one of these categories. An element
is always assigned to the most restrictive category (from Ignore to Preserve) that it is assigned to by any of the sources
Oxygen XML Editor consults. For instance, if the element is named on the Default elements list (as described below)
but it has an xml:space="preserve" attribute in the source file, it will be assigned to the preserve space category.
If an element has the xml:space="default" attribute in the source, but is listed on the Mixed content elements
list, it will be assigned to the mixed content category.
To assign elements to these categories, Oxygen XML Editor consults information from the following sources:
xml:space
If the XML element contains the xml:space attribute, the element is promoted to the appropriate category based
on the value of the attribute.
CSS whitespace property
If the CSS stylesheet controlling the Author mode editor applies the whitespace: pre setting to an element,
it is promoted to the preserve space category.
CSS display property
If a text node contains only white-spaces:
If the node has a parent element with the CSS display property set to inline then the node is promoted to
the mixed content category.
If the left or right sibling is an element with the CSS display property set to inline then the node is promoted
to the mixed content category.
If one of its ancestors is an element with the CSS display property set to table then the node is assigned
to the ignore space category.
If the schema declares an element to be mixed content, it will be promoted to the mixed content category.
To turn it on or off for Author mode, open the Preferences dialog box and go to Editor > Edit modes > Author >
Schema aware > Schema aware normalization, format and indent.
To turn it on or off for the Text editing mode ,open the Preferences dialog box and go to Editor > Format >
XML > Schema aware format and indent.
All opened files - The pretty print is performed in all opened files.
Directory of the current file - All the files in the folder of the current edited file.
Project files - All files from the current project.
Selected project files - The selected files from the current project.
Specified path - Pretty prints the files located at a specified path.
File filter - Allow you to filter the files from the selected scope.
Recurse subdirectories - When enabled, the pretty print is performed recursively for the specified scope. The one
exception is that this option is ignored if the scope is set to All opened files.
Include hidden files - When enabled, the pretty print is also performed in the hidden files.
Make backup files with extension - When enabled, Oxygen XML Editor makes backup files of the modified files.
The default extension is .bak, but you can change the extension as you prefer.
Modify All - Use this option to modify (in-place) all the occurrences of the selected content. When you use this
option, a thin rectangle replaces the highlights and allows you to start editing. If matches with different letter cases
are found, a dialog box is displayed that allows you select whether you want to modify only matches with the same
letter case or all matches.
Note: If you select a very large number of highlights that you want to modify using this feature, a dialog
box informs you that you may experience performance issues. You have the option to either use the
Find/Replace operation, or continue the operation.
Surround All - Use this option to surround the highlighted content with a specific tag. This option opens the Tag
dialog box. The Specify the tag drop-down menu presents all the available elements that you can choose from.
If you right-click content in another part of the document, other than a highlight, you have the option to select the
following option:
Modify All Matches - Use this option to modify (in-place) all the occurrences of the selected content (or the
contiguous fragment in which the cursor is located). When you use this option, a thin rectangle replaces the highlights
and allows you to start editing. If matches with different letter cases are found, a dialog box is displayed that allows
you select whether you want to modify only matches with the same letter case or all matches.
Sort ascending or
The sorting result depends on the data type of the column content. It can be different in case of number (numerical
sorting) or text information (alphabetical sorting). The editor automatically analyzes the content and decides what type
of sorting to apply. When a mixed set of values is present in the sorted column, a dialog box is displayed that allows
you to choose the desired type of sorting between numerical and alphabetical.
Inserting a Row in a Table
You can add a new row using the Copy/Paste actions, or by selecting
Grid toolbar.
For a faster way to insert a new row, move the selection over the row header, and then press Enter. The row header is
the zone in the left of the row that holds the row number. The new row is inserted below the selection.
Inserting a Column in a Table
You can insert a column after the selected column by using the
the Grid toolbar.
Insert before - Offers a list of valid nodes, depending on the context, and inserts your selection before the currently
selected node, as a sibling.
Insert after - Offers a list of valid nodes, depending on the context, and inserts your selection after the currently
selected node, as a sibling.
Append child - Offers a list of valid nodes, depending on the context, and appends your selection as a child of the
currently selected node.
Duplicating Nodes
You can quickly create new nodes by duplicating existing ones. The Duplicate action is available in the contextual
menu and in the Document > Grid Edit menu.
Refresh selected action that is available in the contextual menu and in the Document > Grid Edit
To cancel the editing without saving the current changes in the document, press the (Esc) key.
Drag and Drop in the Grid Editor
You are able to easily arrange different sections in your XML document in the Grid mode by using drag and drop
actions.
You can do the following with drag and drop:
These operations are available for both single and multiple selections. To deselect one of the selected fragments, use
Ctrl Single-Click (Command Single-Click on OS X).
While dragging, the editor paints guide-lines showing the locations where you can drop the nodes. You can also drag
nodes outside the Grid editor and text from other applications into the Grid. For more information, see Copy and Paste
in the Grid Editor.
Copy and Paste in the Grid Editor
The selection in the Grid mode is a bit complex compared to the selection in a text component. It consists of a current
selected cell and additional selected cells. These additional cells are either selected with the cursor, or implied by the
currently selected cell. To be more specific, consider that you click the name of the column (this becomes the current
selected cell), but the editor automatically extends the selection so that it contains all the cells from that column. The
current selected cell is painted with a color that is different from the rest of the selection.
You can select discontinuous regions of nodes and place them in the clipboard using the copy action. To deselect one
of the selected fragments, use Ctrl Single-Click (Command Single-Click on OS X). Pasting these nodes relative to
the current selected cell may be done in two ways: just below (after) as a brother, which is the default behavior, or as
the last child of the selected cell.
The Paste as Child action is available in the contextual menu.
The same action can be found in the menu Document > Grid Edit > Paste as Child.
The nodes copied from the Grid editor can also be pasted into the Text editor or other applications. When copying from
the Grid into the Text editor or other text based applications, the inserted string represents the nodes serialization. The
nodes from tables can be copied using HTML or RTF in table format. The resulting cells contain only the concatenated
values of the text nodes.
LESS example:
<?xml-stylesheet type="text/css" href="test.less"?>
Note: XHTML documents need a link element, with the href and type attributes in the head child
element, as specified in the W3C CSS specification. XHTML example:
<link href="/style/screen.css" rel="stylesheet" type="text/css"/>
Tip: You can also insert the xml-stylesheet processing instruction by using the
Associate
XSLT/CSS Stylesheet action that is available on the toolbar or in the Document > XML Document menu.
2. Configure a Document Type Association by adding a new CSS or LESS file in the settings. To do so, open the
Preferences dialog box and go to Document Type Association. Edit the appropriate framework, open the Author
tab, then the CSS tab. Press the
Note: The Document Type Associations are read-only, so you need to extend an existing one.
You can read more about associating a CSS to a document in the section about customizing the CSS of a document type.
If a document has no CSS association or the referenced stylesheet files cannot be loaded, a default one is used. A warning
message is also displayed at the beginning of the document, presenting the reason why the CSS cannot be loaded.
The CSS stylesheet that drives the tagless visual rendering of the document.
The rules for associating an XML schema with the document, which is needed for content completion and validation
of the document.
The tagless editor comes with some ready-to-use predefined document types for XML frameworks such as DocBook,
DITA, TEI, and XHTML.
To watch our video demonstration about the basic functionality of the Author mode, go to
http://oxygenxml.com/demo/WYSIWYG_XML_Editing.html.
Contextual Menu Actions in Author Mode
Oxygen XML Editor includes powerful support for editing XML documents through actions included in the contextual
menu. When editing XML documents in Author mode, the contextual menu includes general actions that are available
for all of the recognized document types and document type-specific actions that are configured for each document type.
General Contextual Menu Actions in Author Mode
The general actions that are available in the contextual menu (some of them are also available in the submenus of the
Document menu) for all document types include the following:
Quick Fix (Alt 1 (Meta Alt 1 on OS X))
Available when the contextual menu is invoked on an error where Oxygen XML Editor can provide a quick fix.
Open Image
Available when the contextual menu is invoked on an image. This action allows you to open an image in the Oxygen
XML Editor's Image Viewer or in a default system application associated with the current image type.
Track Changes Actions
Available when the Track Changes feature is enabled and the contextual menu is invoked on a change. The following
options are available:
Accept Change(s)
Accepts the tracked change located at the cursor position. If you select a part of a delete or insert change, only
the selected content is accepted. If you select multiple changes, all of them are accepted. For an insert change,
it means keeping the inserted text and for a delete change, it means removing the content from the document.
Reject Change(s)
Rejects the tracked change located at the cursor position. If you select a part of a delete or insert change, only
the selected content is rejected. If you select multiple changes, all of them are rejected. For an insert change, it
means removing the inserted text and for a delete change, it means preserving the original content from the
document.
Comment Change
Opens a dialog box that allows you to add a comment to an existing tracked change. The comment appears in
a callout box and a tooltip (when hovering over the change).
Author Callout Actions
Available when the contextual menu is invoked on a callout. If enabled in the Callouts preferences page, the callouts
are displayed in Author mode for comments, tracked insertion changes, or tracked deletion changes.
The following actions are available in the contextual menu of an insertion or deletion callout:
Accept Change(s)
Accepts the tracked change located at the cursor position. If you select a part of a delete or insert change, only
the selected content is accepted. If you select multiple changes, all of them are accepted. For an insert change,
it means keeping the inserted text and for a delete change, it means removing the content from the document.
Reject Change(s)
Rejects the tracked change located at the cursor position. If you select a part of a delete or insert change, only
the selected content is rejected. If you select multiple changes, all of them are rejected. For an insert change, it
place the cursor at the right side of a valid hexadecimal sequence, then press Alt X (Meta Shift X on OS
X) on your keyboard
select a valid hexadecimal sequence, then press Alt X (Meta Shift X on OS X) on your keyboard
Refactoring submenu
Contains a series of actions designed to alter the XML structure of the document:
Toggle Comment
Encloses the currently selected text in an XML comment, or removes the comment if it is commented.
Move Up
Moves the current node or selected nodes in front of the previous node.
Move Down
Moves the current node or selected nodes after the successive node.
Split Element
Splits the content of the closest element that contains the position of the cursor. Thus, if the cursor is positioned
at the beginning or at the end of the element, the newly created sibling will be empty.
When both of the drag and drop sources are from the Author mode editor, a well-formed XML fragment is transferred.
The section is balanced before dropping it by adding matching tags when needed.
When the drag source is from the Author mode editor but the drop target is a text-based editor, only the text inside
the selection is transferred as it is.
The text dropped from another text editor or another application into the Author mode editor is inserted without
changes.
Inserting allowed elements for the current context according to the associated schema.
Inserting element values if such values are specified in the schema for the current context.
Inserting new undeclared elements by entering their name in the text field.
Inserting CDATA sections, comments, processing instructions.
Inserting code templates.
If the Show all possible elements in the content completion list option from the Schema aware preferences page
is enabled, the content completion pop-up window will present all the elements defined by the schema. When choosing
an element from this section, the insertion will be performed using the schema aware smart editing features.
The cursor is located before the end position of the first element and (Delete) key is pressed.
The cursor is located after the end position of the first element and (Backspace) key is pressed.
The cursor is located before the start position of the second element and (Delete) key is pressed.
The cursor is located after the start position of the second element and (Backspace) key is pressed.
In either of the described cases, if the element has no sibling or the sibling element has a different name, Unwrap
operation will be performed automatically.
Unwrapping the content of an element - You can unwrap the content of an element by deleting its tags using the
Delete element tags action from the editor contextual menu.
The same action can be triggered in the next situations:
The cursor is located before the start position of the element and (Delete) key is pressed.
The cursor is located after the start position of the element and (Backspace) key is pressed.
The cursor is located before the end position of the element and (Delete) key is pressed.
The cursor is located after the end position of the element and (Backspace) key is pressed.
Removing all the markup of an element - You can remove the markup of the current element and keep only the text
content by highlighting the appropriate block of content and use the
Remove All Markup action that is available
in the Refactoring submenu of the contextual menu and in the Document > Markup menu.
When you press (Delete) or (Backspace) in the presented cases the element is unwrapped or it is joined with its sibling.
If the current element is empty, the element tags will be deleted.
When you click a marker representing the start or end tag of an element, the entire element is selected and numerous
context specific actions are available in the various menus and the contextual menu.
Code Templates
Code templates are code fragments that can be inserted quickly at the current editing position . Oxygen XML Editor
comes with a set of built-in code templates for CSS, LESS, Schematron, XSL, XQuery, and XML Schema document
types. You can also define you own code templates and share them with others.
To get a complete list of available code templates, press Ctrl Shift Space in Text mode. To enter the code template,
select it from the list or type its code and press Enter. If a shortcut key has been assigned to the code template, you can
also use the shortcut key to enter it. Code templates are displayed with a symbol in the content completion list.
When the Content Completion Assistant is invoked (Ctrl Space (Command Space on OS X) in Text mode or Enter
in Author mode), it also presents a list of code templates specific to the type of the active editor.
Complex search operations may take some time to complete. If a search operation takes more than 5 seconds, you are
prompted to decide whether you want to continue the operation or stop it.
Smart Paste Support
You can paste content from various sources, such as web pages and Office-type documents, and paste it into DITA,
TEI, DocBook, JATS, and XHTML documents. Oxygen XML Editor keeps the original text styling (such as bold, italics,
etc.) and formatting (such as lists, tables, paragraphs, etc.), and helps you make the resulting document valid.
The following document types include support for Smart Paste:
DITA
DocBook 4
DocBook 5
TEI 4
TEI 5
XHTML
JATS
The styles and general layout of the pasted content are transformed to the equivalent XML markup of the target document
type.
You can disable the Smart Paste feature by deselecting Convert external content on paste in the Schema Aware
preferences.
If you paste the content in a location where the resulting XML would not be valid, Oxygen XML Editor will attempt to
place it in a valid location, and may prompt you with one or more choices for where to place it. You can disable this
location selection feature by deselecting Smart paste and drag and drop option, available in the Schema Aware
preferences.
To watch our video demonstration about the Smart Paste support, go to
http://oxygenxml.com/demo/Smart_Paste_Copy_Paste_from_Web_Office_Documents_to_DITA_DocBook_TEI_XHTML_Documents.html.
Reviewing Documents
Tracking Document Changes
Track Changes is a way to keep track of the changes you make to a document. To activate track changes for the current
document, either choose Edit > Review >
Track Changes or click the
Track Changes button on the Review
toolbar. When Track Changes is enabled, your modifications are highlighted using a distinctive color. The name of
the author who is currently making changes and the colors can be customized from the Review preferences page.
If the selection in the Author view contains tracked changes and you are copying it, the clipboard contains the selection
with all the accepted changes. This filtering is performed only if the selection is not entirely inside a tracked change.
The changes are stored in the document as processing instructions and they do not interfere with validating and
transforming it. For each change, the author name and the modification time are preserved.
Note: Tracked changes are also shown in the Outline view. Deleted content is rendered with a strike through.
Adding Document Comments
You can associate a note or a comment to a selected area of content. Comments can highlight virtually any content from
your document, except read-only text. The difference between such comments and change tracking is that a comment
can be associated to an area of text without modifying or deleting the text.
The actions for managing comments are
Add Comment,
Edit Comment,
Manage reviews. They are available on the Review toolbar and in the Review submenu of the contextual menu in
Author mode.
Tip: The comments are stored in the document as processing instructions, containing information about the
author name and the comment time:
<?oxy_comment_start author="John Doe" timestamp="20090508T164459+0300" comment="Do not change this
content"?>
Important content
<?oxy_comment_end?>
Comments are persistent highlights with a colored background. The background color is customizable or can be assigned
automatically by the application. This behavior can be controlled from the Review preferences page.
Note: Oxygen XML Editor presents the tracked changes in DITA conrefs and XInclude fragments.
Managing Changes
You can review the changes that you or other authors have made and then accept or reject them using the Track Changes
toolbar buttons
Track Changes
Enables or disables the track changes support for the current document.
Accept Change(s)
Accepts the tracked change located at the cursor position. If you select a part of a delete or insert change, only the
selected content is accepted. If you select multiple changes, all of them are accepted. For an insert change, it means
keeping the inserted text and for a delete change, it means removing the content from the document.
Reject Change(s)
Rejects the tracked change located at the cursor position. If you select a part of a delete or insert change, only the
selected content is rejected. If you select multiple changes, all of them are rejected. For an insert change, it means
removing the inserted text and for a delete change, it means preserving the original content from the document.
Comment Change
Opens a dialog box that allows you to add a comment to an existing tracked change. The comment appears in a
callout box and a tooltip (when hovering over the change).
Add Comment
Inserts a comment at the cursor position. The comment appears in a callout box and a tooltip (when hovering over
the change).
Edit comment
Opens the Edit Comment dialog box that allows you to edit the selected comment.
Remove comment
Removes a selected comment.
Manage Reviews
Opens the Review view.
Track Changes Visualization Modes Drop-Down Menu
This drop-down menu includes specialized actions that allow you to switch between the following visualization modes:
View All Changes/Comments - This mode is active by default. When you use this mode, all tracked changes
are represented in the Author mode.
View only Changes/Comments by - Only the tracked changes made by the author you select are presented.
View Final - This mode offers a preview of the document as if all tracked changes (both inserted and deleted)
were accepted.
View Original -this mode offers a preview of the document as if all tracked changes (both inserted and deleted)
were rejected. You cannot edit the document in this mode. Attempting to do so switches the view mode to View All
Changes.
All four actions are available only in the drop-down menu in the Review toolbar. If you use
View Final mode and
View Original mode, highlighted comments are not displayed. To display highlighted comments, use
View All
Changes/Comments.
To watch our video demonstration about the Track Changes support, go to
http://oxygenxml.com/demo/Change_Tracking.html.
Track Changes Behavior
This section explains the behavior of the Track Changes feature depending on the context and whether it is activated.
You can use the Track Changes feature to keep track of multiple actions.
Possible change tracking scenarios:
Inserted content
Surrounded content
Deleted characters
Deleted content
Copied content
Pasted content
Attribute changes
Making an insertion in a Delete change results in the change being split in two and the content is inserted without
being marked as change.
When Track Changes is enabled and you insert content, the following are possible:
Making an insertion in a Delete change results in the change being split in two and the current inserted content
appears marked as an INSERT.
Making an insertion in an Insert change results in the following:
If the original insertion was made by another user, the change is split in two and the current inserted content
appears marked as an INSERT by the current author.
If the original Insert change was made by the same user, the change is just expanded to contain the inserted
content. The creation time-stamp of the previous insert is preserved.
If we insert in regular content, the current inserted content appears marked as an Insert change.
If the original insertion was made by another user, the change is split in two and the surround operation appears
marked as being performed by the current author.
If the original Insert change was made by the same user, the existing change is just expanded to contain the
surrounded content.
Making a surround in regular content results in the operation being marked as a surround change.
When Track Changes is enabled and you delete content character by character, the following is possible:
If the same author created the Delete change, the previous change is marked as deleted by the current author.
If another author created the Delete change, nothing happens.
If the same author created the Insert change, the content is deleted and the Insert change shrinks accordingly.
If another author created the Insert change, the Insert change is split in two and the deleted content appears
marked as a Delete change by the current author.
Deleting in regular content results in the content being marked as Delete change by the current author.
If the selection contains an entire Delete change, the change disappears and the content is deleted.
If the selection intersects with a Delete change (starts or ends in one), it results in nothing happening.
If the selection contains an entire Insert change, the change disappears and the content is deleted.
If the selection intersects with an Insert change (starts or ends in one), the Insert change is shrunk and the content
is deleted.
If the selection contains an entire Delete change, the change is considered as rejected and then marked as deleted by
the current author, along with the other selected content.
If the selection intersects a Delete change (starts or ends in one), the change is considered as rejected and marked
as deleted by the current author, along with the other selected content.
If the selection contains an entire Insert change, the following is possible:
If the Insert is made by the same author, the change disappears and the content is deleted.
If the Insert is made by another author, the change is considered as accepted and then marked as deleted by the
current author, along with the other selected content.
If the selection intersects an Insert change (starts or ends in one), the Insert change shrinks and the part of the Insert
change that intersects with the selection is deleted.
If the copied area contains Insert or Delete changes, these are also copied to the clipboard.
When Track Changes is enabled and you copy content, the following is possible:
If the copied area contains Insert or Delete changes, these are all accepted in the content of the clipboard (the changes
will no longer be in the clipboard).
If the clipboard content contains Insert or Delete changes, they will be preserved on paste.
When Track Changes is enabled and you paste content, the following is possible:
If the clipboard content contains Insert or Delete changes, all the changes are accepted and then the paste operation
proceeds according to the insertion rules.
If you perform the copy operation with Track Changes enabled, all the attribute changes in the fragment are accepted.
If you perform the copy operation with Track Changes disabled, the fragment holds the attribute changes inside it.
When you paste a fragment that contains tracked attribute changes, the following is possible:
If you perform the paste operation with Track Changes enabled, the changes are accepted before the paste operation.
If you perform the paste operation with Track Changes disabled, the changes are pasted in the document.
Attributes
Insertion
<?oxy_insert_start?>
<?oxy_insert_end?>
author, timestamp
Split
<?oxy_insert_start?>
<?oxy_insert_end?>
author, timestamp,
type="split"
Surround
<?oxy_insert_start?>
<?oxy_insert_end?>
author, timestamp,
type="surround"
Deletion
<?oxy_delete?>
Comment
<?oxy_comment_start?> <?oxy_comment_end?>
Attribute
Change
<?oxy_attributes?>
author, timestamp,
comment, mid
id, type, oldValue, author,
timestamp
If a comment intersects another, the mid attribute is used to correctly identify start and end processing instruction
markers.
Intersecting Comments Markup
<?oxy_comment_start author="Andrew" timestamp="20130111T151520+0200" comment="Do we have a
task about pruning trees?"?>Unpruned
<?oxy_comment_start author="Matthew" timestamp="20130111T151623+0200" comment="What time
of the year do they flower?" mid="3"?>lilacs<?oxy_comment_end?>
flower reliably every year<?oxy_comment_end mid="3"?>
Managing Comments
A comment is marked in the Author mode with a background that is configured for each user name.
To watch our video demonstration about using the Highlight tool, go to http://oxygenxml.com/demo/Highlight_Tool.html.
Mark Selected Text
To mark the text you select in a document:
1. Select the text you want to highlight.
Note: To mark more than one part of the document you are editing, press and hold Ctrl (Meta on Mac OS)
and using you cursor select the parts you want to highlight.
2. Click the small arrow next to the
Highlight icon and select the colour that you want to use for highlighting.
The selected text is highlighted.
3. Click the Highlight icon to exit the highlighting mode.
Mark Document Fragments
To mark fragments in a document, follow these steps:
1. Click the
Highlight icon on the toolbar.
The highlighting mode is on. The cursor changes to a dedicated symbol that has the same color with the one set in
the Highlight palette.
2. Select the text you want to highlight with your cursor.
3. To highlight different fragments using multiple colors, click the small arrow next to the
Highlight icon, choose
the colour that you want to use for highlighting, and repeat step 2.
The fragments are highlighted.
4. To exist the highlighting mode, press Esc on your keyboard, click the
document.
Comments - Oxygen XML Editor displays comment callouts when you insert a comment. You can use two types
of comments in Oxygen XML Editor:
Author Review Comments - Comments that you associate with specific fragments of text.
Callout Comments - Comments that you add in an already existing insertion or deletion callout.
By default, the fragment of text that you comment is highlighted and a horizontal line connects it with the comment
callout. A comment callout contains the name of the author who inserts the callout and the comment itself. To
customize how comments are displayed, open the Preferences dialog box, go to Editor > Edit Modes > Author >
Review > Callouts, and enable Show review time.
Track Changes deletions - Oxygen XML Editor displays deletion callouts when you delete a fragment of text. By
default, a deletion callout contains the type of callout (Deleted) and the name of the author that makes the deletion.
You are able to customize the content of a deletion callout to display the date and time of the deletion and the deleted
fragment itself. To do this, open the Preferences dialog box, go to Editor > Edit Modes > Author > Review >
Callouts, and enable Show review time and Show deleted content in callout.
Track Changes insertions - Oxygen XML Editor displays insertion callouts when you insert a fragment of text. By
default, an insertion callout contains the type of callout (Inserted) and the name of the author that makes the insertion.
You are able to customize the content of an insertion callout to contain the date and time of the insertion and the
inserted fragment itself. Open the Preferences dialog box, go to Editor > Edit Modes > Author > Review >
Callouts, and enable Show review time and Show inserted content in callout.
Accept Change - Select this option to accept the changes you or other authors make to a document.
Reject Change - Select this option to reject the changes you or other authors make to a document.
Comment Change - Select this option to comment an existing change in your document. You are also able to
add a comment to a change from the
The following options are available in the contextual menu of a comment callout:
Edit Comment - Select this option to modify the content of a comment callout.
Note: The text area is disabled if you are not the author which inserted the comment.
When you print a document from Oxygen XML Editor, all callouts you, or other authors added to the document are
printed. For a preview of the document and its callouts, go to File > Print preview.
To watch our video demonstration about the Callouts support, go to http://oxygenxml.com/demo/CalloutsSupport.html.
The Review View
The Review view is a framework-independent panel, available both for built-in, and custom XML document frameworks.
It is designed to offer an enhanced way of monitoring all the changes that you make to a document. This means you are
able to view and control highlighted, commented, inserted, and deleted content, or even changes made to attributes,
using a single view.
The Review view is useful when you are working with documents that contain large quantities of edits. The edits are
presented in a compact form, in the order they appear in the document. Each edit is marked with a type-specific icon.
Click the
Manage reviews button on the Review toolbar.
Right-click in a document and from the contextual menu go to Review, Manage reviews.
Go to Window > Show View > Review.
This view and the editing area are synchronized. When you select an edit listed in the Review view, its corresponding
fragment of text is highlighted in the editing area and the reverse is also true. For example, when you place the cursor
inside an area of text marked as inserted, its corresponding edit is selected in the list.
The upper part of the view contains a filtering area which allows you to search for specific edits. Use the small arrow
symbol from the right side of the search field to display the search history. The Settings button allows you to:
Show highlights - controls whether the Review view displays the highlighting in your document.
Show comments - controls whether the Review view displays the comments in the document you are editing.
Show track changes - controls whether the Review view displays the inserted and deleted content in your document.
Show review time - displays the time when the edits from the Review view were made.
The following actions are available when you hover the edits in the Review view, using the cursor:
Remove
Action available for highlights and comments presented in the Review view. Use this action to remove these
highlights or comments from your document;
Accept
Action available for inserted and deleted content presented in the Review view. Use this action to accept the changes
in your document;
The benefits of using conditional text include reduced effort for updating and translating your content and an easy way
to customize the output for various audiences.
Oxygen XML Editor comes with a preconfigured set of profiling attribute values for some of the most popular document
types. These attributes can be redefined to match your specific needs. Also, you can define your own profiling attributes
for a custom document type.
Create Profiling Attributes
Note: To ensure the validity of the document, the attribute must already be defined in the document DTD or
schema before referencing it here.
To create custom profiling attributes for a specific document type, follow these steps:
1. Open the Preferences dialog box and go to Editor > Edit modes > Author > Profiling/Conditional Text .
2. In the Profiling Attributes area, press the New button.
The Profiling Attribute dialog box is opened.
If you apply the following condition set it means that you want to filter-out the content written for non-expert audience
and having the Other attribute value different than prop1.
And this is how the document looks like after you apply the Expert user condition set:
Choosing the right style for a specific profiling attribute is a matter of personal taste, but you should keep in mind that:
If the same block of text is profiled with two or more profiling attributes, their associated styles combine. Depending
on the styling, this might result in an excessively styled content that may prove difficult to read or work with.
Profile only differences. There is no need to profile common content, since excessive profiling can visually pollute
the document.
A mnemonic associated with a style will help you spot instantly different types of content.
Enable the Show Profiling Colors and Styles option from the
menu.
Note that the styling is now applied in the Author editing mode, the Outline view and DITA Maps Manager view.
Also, to help you identify more easily the profiling you want to apply in the current context, the styling is applied in the
Edit Profiling Attributes dialog box and in the inline form control that allows you to quickly set the profiling attributes.
Table Layout and Operations
Oxygen XML Editor provides support for editing data in a tabular form. The following operations are available:
Cell selection
To select a cell in a table, press and hold the Ctrl key and click anywhere inside the cell. You can use this action to
select one or more cells, and also to deselect cells from a selection. Alternatively, you can click one of the left corners
of a cell (right corners if you are editing a RTL document). The cursor changes to
of the cell.
Rectangular selection
To select a rectangular block of cells do one of the following:
Content deletion
To delete a group of cells (can be columns, rows, or rectangular block of cells), select them and do one of the
following:
Press either Delete, or Backspace on your keyboard to delete the cells' content. Press again Delete, or Backspace
to remove the selected table structure.
Table - The horizontal alignment, row and column separators, and the frame.
Table - The horizontal alignment, row and column separators, and the frame.
Row - The row type, vertical alignment, and row separator.
Column - The horizontal alignment, and column and row separators.
Cell - The horizontal alignment, vertical alignment, and column and row separators.
Sorting a Table
To sort rows in a table, select the entire table (or specific rows) and use the
the contextual menu. This opens the Sort dialog box.
The sort criteria is automatically set to the column where the cursor is located at the time when the sorting operation is
invoked.
After you finish configuring the options in the Sort dialog box, click OK to complete the sorting operation. If you want
to revert to the initial order of your content, press Ctrl Z (Meta Z on OS X) on your keyboard.
Note: The sorting support takes the value of the xml:lang attribute into account and sorts the content in a
natural order.
Sorting a Selection of Rows
To sort a selection of rows in a table, select the rows that you want to sort and either right click the selection and choose
Sort, or click
Sort on the main toolbar. This opens the Sort dialog box.
The sort criteria is automatically set to the column where the cursor is located at the time when the sorting operation is
invoked.
After you finish configuring the options in the Sort dialog box, click OK to complete the sorting operation. If you want
to revert to the initial order of your content, press Ctrl Z (Meta Z on OS X) on your keyboard.
Note: The sorting support takes the value of the xml:lang attribute into account and sorts the content in a
natural order.
Sort Using Multiple Criteria
You can also sort an entire table or a selection of its rows based on multiple sorting criteria. To do so, enable the rest of
boxes in the Criteria section of the Sort dialog box, configure the applicable items, and click OK to complete the sorting
operation.
The sorting mechanism works on an entire list or on a selection of list items. To sort items in a list, select the items or
list and use the
Sort action from the main toolbar or the contextual menu. This opens the Sort dialog box.
After you finish configuring the options in the Sort dialog box, click OK to complete the sorting operation. If you want
to revert to the initial order of your content, press Ctrl Z (Meta Z on OS X) on your keyboard.
Note: The sorting support takes the value of the xml:lang attribute into account and sorts the content in a
natural order.
Image Rendering
The Author mode and the output transformation process might render the images referenced in an XML document
differently, since they use different rendering engines.
Table 5: Supported Image Formats
Image Type
Support
Additional Information
GIF
built-in
JPG, JPEG
built-in
JPEG images with CMYK color profiles are properly rendered only if color profile is
inside the image.
PNG
built-in
SVG, SVGZ,
WMF
built-in
BMP
built-in
TIFF
built-in
EPS
built-in
AI
built-in
JPEG 2000,
WBMP
plug-in
Renders by installing the Java Advanced Imaging (JAI) Image I/O Tools plug-in.
CGM
plug-in
plug-in
Rendered using the open-source Apache Batik library which supports SVG 1.1.
When an image cannot be rendered, Oxygen XML Editor Author mode displays a warning message that contains the
reason why this is happening. Possible causes include the following:
The image is too large. Enable the Show very large images option.
The image format is not supported by default. It is recommended to install the Java Advanced Imaging(JAI) Image
I/O Tools plug-in.
Scaling Images
Image dimension and scaling attributes are taken into account when an image is rendered. The following rules apply:
http://search.maven.org/remotecontent?filepath=com/twelvemonkeys/common/common-lang/3.1.0/common-lang-3.1.0.jar
http://search.maven.org/remotecontent?filepath=com/twelvemonkeys/common/common-io/3.1.0/common-io-3.1.0.jar
http://search.maven.org/remotecontent?filepath=com/twelvemonkeys/common/common-image/3.1.0/common-image-3.1.0.jar
The EPS or AI image does not include the preview picture. Oxygen XML Editor cannot render the image.
The EPS image includes a TIFF preview picture.
Note: Some newer versions of the TIFF picture preview are rendered in gray-scale.
The AI image contains a JPEG preview picture. Oxygen XML Editor renders the image correctly.
Adding an Image
To insert an image in a document while editing in Author mode, use one of the following methods:
Click the
Insert Image action from the toolbar and choose the image file you want to insert. Oxygen XML Editor
tries to reference the image with a path that is relative to that of the document you are currently editing. For example,
if you want to add the file:/C:/project/xml/dir/img1.jpg image into the
file:/C:/project/xml/doc1.xml document, Oxygen XML Editor inserts a reference to dir/img1.jpg.
This is useful when multiple users work on a common project and they have it stored in different locations in their
computers.
Note: The
Insert Image action is available for the following document types: DocBook 4, DocBook 5,
DITA, TEI P4, TEI P5, XHTML.
Drag an image from other application and drop it in the Author editing mode. If it is an image file, it is inserted as
a reference to the image file. For example, in a DITA topic the path of the image file is inserted as the value of the
href attribute in an image element:
<image href="../images/image_file.png"/>
Note: To replace an image, just drag and drop a new image over the existing one. Oxygen XML Editor will
automatically update the reference to the new image.
Copy the image from another application (such as an image editor) and paste it into your document. Oxygen XML
Editor prompts you to first save it. After saving the image, a reference to that file path is inserted at the paste position.
For DITA documents, you can also edit the DITA Map WebHelp transformation scenario and set the args.hdf
parameter to point to the footer.html resource. Then transform to WebHelp and the equation should be properly
rendered in the browsers such as IE, Chrome, and Firefox.
Refreshing the Content
On occasion you may need to reload the content of the document from the disk or reapply the CSS. This can be performed
by using the
Reload action.
To refresh the content of the referenced resources you can use the
will not refresh the expanded external entities, for which you will need to use the
Reload action.
Select an element or place the cursor inside it and then press the Alt Enter keyboard shortcut.
Double-click any named start tag when the document is edited in one of the following display modes.:
with Attributes,
Full Tags,
Block Tags, or
Inline Tags.
Full Tags
This opens an in-place attributes editor that contains the same content as the Attributes view. By default, this editor
presents the Name and Value fields, with the list of all the possible attributes collapsed.
If the Auto generate IDs for elements option is enabled and you duplicate elements with existing IDs, Oxygen
XML Editor assigns new, unique ID values to the duplicates.
If the Auto generate IDs for elements option is disabled and you duplicate elements with existing IDs, the ID values
are removed from the duplicates. However, when elements are duplicated in the same document, this option has no
effect and IDs are preserved if the Remove IDs when copying content in the same document option is disabled.
If the Remove IDs when copying content in the same document option is enabled, the ID values are removed
from elements that are duplicated in the same document. However, enabling this option has no effect if the Auto
generate IDs for elements option is enabled.
If the Remove IDs when copying content in the same document option is disabled, the ID values are preserved
when elements are duplicated in the same document. This option has no affect on elements that are duplicated in
other documents.
Text Field - A graphical user interface box that allows you to enter a single line of text.
Combo Box - A graphical user interface object that can be a drop-down menu or a combination of a drop-down menu
and a single-line text field.
Check Box - A graphical user interface box that you can click to select or deselect a value.
Pop-up - A contextual menu that provides quick access to various actions.
Button - A graphical user interface object that performs a specific action.
Button Group - A graphical user interface group of buttons (such as radio buttons) that perform specific actions.
Text Area - A box that allows you to enter multiple lines of text.
URL Chooser - A dialog box that allows you to select the location of local or remote resources.
Date Picker - A form control object that allows you to select a date in a specified format.
HTML Content - A graphical user interface box that is used for rendering HTML content.
You can also implement custom form controls for more specific needs.
W3C XML Schema 1.0 and 1.1 (with and without embedded Schematron rules);
DTD;
Relax NG - XML syntax (with and without embedded Schematron rules);
Relax NG - compact syntax;
NVDL;
Schematron (both ISO Schematron and Schematron 1.5).
The schema has one of the following types: XML Schema, XML Schema with embedded Schematron rules, Relax NG
(XML syntax or compact syntax), Relax NG (XML syntax) with embedded Schematron rules, Schematron, DTD, NVDL.
The rules are applied in the order they appear in the table and take into account the local name of the root element, the
default namespace and the file name of the document.
Important:
The editor is creating the content completion lists by analysing the specified schema and the current context
(the position in the editor). If you change the schema, then the list of tags to be inserted is updated.
The association can specify a relative file path or a URL of the schema. The advantage of relative file path is that you
can configure the schema at file level instead of document type level.
Select the
Associate schema action from the Document > Schema menu or the Document toolbar to select the
schema that will be associated with the XML document. The Associate Schema dialog box is displayed:
URL - Contains a predefined set of schemas that are used more often and it also keeps a history of the last used
schemas. The URL must point to the schema file which can be loaded from the local disk or from a remote server
through HTTP(S), FTP(S) or a custom protocol.
Schema type - Selected automatically from the list of possible types in the Schema type combo box (XML Schema,
DTD, Relax NG, Relax NG Compact, Schematron, NVDL) based on the extension of the schema file that was entered
in the URL field.
Public ID - Specify a public ID if you have selected a DTD.
Add additional association for embedded schematron rules - If you have selected XML Schema or Relax NG
schemas with embedded Schematron rules, enable this option.
Use path relative to file location - Enable this option if the XML instance document and the associated schema
contain relative paths. The location of the schema file is inserted in the XML instance document as a relative file
path. This practice allows you, for example, to share these documents with other users, without running into problems
caused by different project locations on physical disk.
Keep existing schema associations - Enable this option to keep the associations of the currently edited document
with a Schema when you associate a new one.
The association with an XML Schema is added as an attribute of the root element. The Associate schema action adds
one of the following:
xsi:schemaLocation attribute, if the root element of the document sets a default namespace with an xmlns
attribute.
xsi:noNamespaceSchemaLocation attribute, if the root element does not set a default namespace.
The association with a DTD is added as a DOCTYPE declaration. The association with a Relax NG , Schematron or
NVDL schema is added as xml-model processing instruction.
Associating a Schema With the Namespace of the Root Element
The namespace of the root element of an XML document can be associated with an XML Schema using an XML catalog.
If there is no xsi:schemaLocation attribute on the root element and the XML document is not matched with a
document type, the namespace of the root element is searched in the XML catalogs set in Preferences.
If the XML catalog contains an uri or rewriteUri or delegateUri element, its schema will be used by the
application to drive the content completion and document validation.
It is available in the Content Completion Assistant, before XML document root element, and includes the following
attributes:
schematypens - The namespace for the schema language of the referenced schema with the following possible
values:
phase - The phase name for the validation function in Schematron schema. This is an optional attribute. To run all
phases from the Schematron, use the special #ALL value. If the phase is not specified, the default phase that is
configured in the Schematron will be applied.
title - The title for the associated schema. This is an optional attribute.
Older versions of Oxygen XML Editor used the oxygen processing instruction with the following attributes:
RNGSchema - Specifies the path to the Relax NG schema that is associated with the current document.
type - Specifies the type of Relax NG schema. It is used along with the RNGSchema attribute and can have the
value xml or compact.
NVDLSchema - Specifies the path to the NVDL schema that is associated with the current document.
SCHSchema - Specifies the path to the SCH schema that is associated with the current document.
Note: Documents that use the oxygen processing instruction are compatible with newer versions of Oxygen
XML Editor.
Automatically, after a configurable delay from the last key press of the < character. You can adjust the delay from
the Content Completion preferences page.
On demand, by pressing Ctrl Space (Command Space on OS X) on a partial element or attribute name.
Note: If the Content Completion list contains only one valid proposal, when you press the Ctrl Space
(Command Space on OS X) shortcut key, the proposal is automatically inserted.
Note: You can also start the Content Completion Assistant from Document > Content Completion >
Start Content Completion.
When active, it displays a list of context-sensitive proposals valid at the current cursor position. Elements are selected
in the list using the Up and Down cursor keys on your keyboard. For each selected item in the list, the Content Completion
Assistant displays a documentation window. You can customize the size of the documentation window by dragging its
top, right, and bottom borders.
To insert the selected content, do one of the following:
Press Enter or Tab key on your keyboard to insert both the start and end tags. The cursor is positioned inside the
start tag, in a position suitable for inserting attributes.
Before the > character of the start tag, if the element allows attributes, in order to enable rapid insertion of any of
the attributes supported by the element. Pressing the space bar displays the Content Completion list once again. This
time it contains the list of allowed attribute names. If the attribute supports a fixed set of parameters, the assistant
list displays the list of valid parameters. If the parameter setting is user-defined and therefore variable, the assistant
is closed to enable manual insertion. The values of the attributes can be learned from the same elements in the current
document
After the > character of the start tag if the element has no attributes.
Anywhere within a tag name or at the beginning of a tag name in an XML document, XML Schema, DTD,or Relax
NG (full or compact syntax) schema
Anywhere within an attribute name or at the beginning of an attribute name in any XML document with an associated
schema
Within attribute values or at the beginning of attribute values in XML documents where lists of possible values have
been defined for that element in the schema associated with the document.
The items that populate the Content Completion Assistant depend on the element structure specified in the DTD, XML
Schema, Relax NG (full or compact syntax) schema, or NVDL schema associated with the edited document.
Note: The Content Completion Assistant is able to offer elements defined both by XML Schemas version
1.0 and 1.1.
The number and type of elements displayed by the Content Completion Assistant is dependent on the cursor's current
position in the structured document. The child elements displayed within a given element are defined by the structure
of the specified DTD, XML Schema, Relax NG (full or compact syntax) schema, or NVDL schema.
A schema may declare certain attributes as ID or IDREF/IDREFS. When the document is validated, Oxygen XML Editor
checks the uniqueness and correctness of the ID attributes. It also collects the attribute values declared in the document
to prepare the Content Completion Assistant's list of proposals. This is available for documents that use DTD, XML
Schema, and Relax NG schema.
Also, values of all the xml:id attributes are handled as ID attributes. They are collected and displayed by the Content
Completion Assistant as possible values for anyURI attributes defined in the schema of the edited document. This
works only for XML Schema and Relax NG schemas.
For documents that use an XML Schema or Relax NG schema, the content assistant offers proposals for attributes and
elements values that have as type an enumeration of tokens. Also, if a default value or a fixed value is defined in the
XML Schema used in validation for an attribute or element, then that value is offered in the Content Completion
Assistant window.
Set Schema for Content Completion
The DTD, XML Schema, Relax NG, or NVDL schema used to populate the Content Completion Assistant is specified
in the following methods, in order of precedence:
The schema specified explicitly in the document. In this case Oxygen XML Editor reads the beginning of the document
and resolves the location of the DTD, XML Schema, Relax NG schema, or NVDL schema.
The default schema declared in the Document Type configuration dialog box that matches the edited document.
In documents based on this schema, the Content Completion Assistant offers the following list of values:
The schema annotations support is available the schema type is one of the following: XML Schema, Relax NG, NVDL,
or DTD. If you want to turn off this feature, disable the Show annotations in Content Completion Assistant option.
Styling Annotations with HTML
You can use HTML format in the annotations you add in an XML Schema or Relax NG schema. This improves the
visual appearance and readability of the documentation window displayed when editing XML documents validated
against such a schema. An annotation is recognized and displayed as HTML if it contains at least one HTML element,
like: div, body, p, br, table, ul, or ol.
The HTML rendering is controlled by the Show annotations using HTML format, if possible option. When this
options is disabled, the annotations are converted and displayed as plain text. If the annotation contains one or more
HTML tags (p, br, ul, li), they are rendered as an HTML document loaded in a web browser: p begins a new paragraph,
br breaks the current line, ul encloses a list of items, li encloses an item of the list.
Collecting Annotations from XML Schemas
In an XML Schema the annotations are specified in an <xs:annotation> element like this:
<xs:annotation>
<xs:documentation>
Description of the element.
For XML Schema, if an element or attribute does not have a specific annotation, then Oxygen XML Editor looks for an
annotation in the type definition of that element or attribute.
Collecting Annotations from Relax NG Schemas
For Relax NG schema element / attribute annotation are made using the <documentation> element from the
http://relaxng.org/ns/compatibility/annotations/1.0 namespace. However, any element outside
the Relax NG namespace (http://relaxng.org/ns/structure/1.0) is handled as annotation and the text
content is displayed in the annotation window. To activate this behavior, enable the Use all Relax NG annotations as
documentation option.
Collecting Annotation from DTDs
For DTD Oxygen XML Editor defines a custom mechanism for annotation using comments enabled from the option
Use DTD comments as annotations. Following is an example of a DTD annotation:
<!--doc:Description of the element. -->
The names of the attributes with a specified value are rendered with a bold font, and their value with a plain font.
Note: The names of the attributes with an empty string value are also rendered bold.
Double-click a cell in the Value column to edit the value of the corresponding attribute. If the possible values of the
attribute are specified as list in the schema of the edited document, the Value column acts as a combo box that allows
you to insert the values in the document.
You can sort the attributes table by clicking the Attribute column header. The table contents can be sorted as follows:
for the value of an attribute. After you have entered or selected a value, use the
to add the value to the attribute.
Paste
Depending on the content of the clipboard, the following cases are possible:
append - Adds new values to appear in the proposals list (default value).
addIfEmpty - Adds new values to the proposals list, only if no other values are contributed by the schema.
replace - Replaces the values contributed by the schema with new values to appear in the proposals list.
The values in the configuration file can be specified either directly or by calling an external XSLT file that will extract
data from any external source.
Example - Specifying Values Directly
<!-- Replaces the values for an element with the local name "lg", from the given namespace -->
<match elementName="lg" elementNS="http://www.oxygenxml.com/ns/samples">
<items action="replace">
<item value="stanza"/>
<item value="refrain"/>
</items>
</match>
<!-- Adds two values for an attribute with the local name "type", from any namespace -->
In this example, the get_values_from_db.xsl is executed in order to extract values from a database.
Note: A comprehensive XSLT sample is included in the Content Completion Configuration file template.
Configuring Proposals in the Context for which the Content Completion was Invoked
A more complex scenario for configuring the content completion proposals would be if you want to choose the possible
values to provide, depending on the context of the element in which the content completion was invoked.
Suppose that you want to propose certain possible values for one property (for example, color) and other values for
another property (for example, shape). If the property represents a color, then the values should represent applicable
colors, while if the property represents a shape, then the values should represent applicable shapes. See the following
code snippets:
Your main document:
<sampleArticle>
<!-- The possible values for @value should be "red" and "blue" -->
<property name="color" value=""/>
<!-- The possible values for @value should be "square" and "rectangle" -->
<property name="shape" value=""/>
</sampleArticle>
The stylesheet that defines the possible values based on the context of the property on which the content completion
was invoked:
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:saxon="http://saxon.sf.net/"
exclude-result-prefixes="xs"
version="2.0">
<xsl:param name="documentSystemID" as="xs:string"></xsl:param>
<xsl:param name="contextElementXPathExpression" as="xs:string"></xsl:param>
<xsl:template name="start">
<xsl:apply-templates select="doc($documentSystemID)"/>
</xsl:template>
<xsl:template match="/">
<xsl:variable name="propertyElement"
select="saxon:eval(saxon:expression($contextElementXPathExpression, ./*))"/>
<items>
<xsl:if test="$propertyElement/@name = 'color'">
<item value='red'/>
<item value='blue'/>
</xsl:if>
<xsl:if test="$propertyElement/@name = 'shape'">
<item value='rectangle'/>
<item value='square'/>
</xsl:if>
</items>
</xsl:template>
</xsl:stylesheet>
All element and attribute names contain either zero or one colon.
No entity names, processing instruction targets, or notation names contain any colons.
The prefix xml is by definition bound to the namespace name http://www.w3.org/XML/1998/namespace. It MAY,
but need not, be declared, and MUST NOT be undeclared or bound to any other namespace name. Other prefixes
MUST NOT be bound to this namespace name.
The prefix xmlns is used only to declare namespace bindings and is by definition bound to the namespace name
http://www.w3.org/2000/xmlns/. It MUST NOT be declared or undeclared. Other prefixes MUST NOT be bound to
this namespace name.
All other prefixes beginning with the three-letter sequence x, m, l, in any case combination, are reserved. This means
that users SHOULD NOT use them except as defined by later specifications and processors MUST NOT treat them
as fatal errors.
The namespace prefix, unless it is xml or xmlns, MUST have been declared in a namespace declaration attribute in
either the start-tag of the element where the prefix is used or in an ancestor element (for example, an element in
whose content the prefixed markup occurs). Furthermore, the attribute value in the innermost such declaration MUST
NOT be an empty string.
To resolve the error, click in the result list record which will locate and highlight the errors approximate
position. Identify which start tag is missing an end tag and insert </tag>.
Top area that contains a success validation indicator that will turn green if the validation succeeded, or red otherwise.
A more detailed report of the errors is displayed in the tooltip of the validation indicator. If there are multiple errors,
only the first three of them will be presented in the tooltip.
Bottom area containing two navigation arrows that will go to the next or to the previous error and a button for clearing
all the error markers from the ruler. The same actions can be triggered from menu Document > Automatic
validation > Next Error Ctrl Period (Meta Period on OS X) and Document > Automatic validation > Previous
Error Ctrl Comma (Meta Comma on OS X).
The validation status area is the line at the bottom of the editor panel that presents the message of the current validation
error selected on the right side ruler. Clicking the
Document checking options button opens the document checking
page in Oxygen XML Editor user preferences.
Status messages from every validation action are logged into the Information view.
If you want to see all the validation error messages grouped in a view you should use the
Validate action from the
Document > Validate menu or from the
Validation toolbar drop-down menu. This action collects all error messages
in the Errors view.
Presenting Validation Errors in Author Mode
Automatic validation and validate on request operations are available while editing documents in the Author mode. A
detailed description of the document validation process and its configuration is described in the Validating Documents
section.
The top area - A success indicator square will turn green if the validation is successful, red if validation errors are
found, or yellow if validation warnings are found.More details about the errors or warnings are displayed in a tool
tip when you hover over indicator square. If there are numerous errors, only the first three are presented in the tool
tip.
The middle area - Errors are depicted with red markers, and warnings with yellow markers. If you want to limit the
number of markers that are displayed, open the Preferences dialog box and go to Editor > Document checking >
Maximum number of validation highlights.
Clicking a marker will highlight the corresponding text area in the editor. The error or warning message is also
displayed both in a tool tip (when hovering over the marker) and in the message area on the bottom of the editor
panel.
The validation status area at the bottom of the editor panel presents the message of the current validation error.
Clicking the
Document checking options button opens the Document checking user preferences page
The bottom area - Two navigation arrows ( ) allow you to skip to the next or previous error. The same actions can
be triggered from Document > Automatic validation > Next error (Ctrl Period (Meta Period on OS X)) and
Document > Automatic validation > Previous error (Ctrl Comma (Meta Comma on OS X)). Also, the
button can be used to clear all the error markers.
Status messages from every validation action are logged in the Information view.
Customizing Assert Error Messages
To customize the error messages that the Xerces or Saxon validation engines display for the assert and assertion
elements, set the message attribute on these elements. For Xerces, the message attribute has to belong to the
http://xerces.apache.org namespace. For Saxon, the message attribute has to belong to the
http://saxon.sourceforge.net/ namespace. The value of the message attribute is the error message
displayed if the assertion fails.
Validation Example - A DocBook Validation Error
In the following DocBook 4 document the content of the listitem element does not match the rules of the DocBook
4 schema, that is docbookx.dtd.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<article>
<title>Article Title</title>
<sect1>
<title>Section1 Title</title>
<itemizedlist>
<listitem>
<link>a link here</link>
</listitem>
</itemizedlist>
</sect1>
</article>
This error message is a little more difficult to understand, so understanding of the syntax or processing rules for the
DocBook XML DTD's listitem element is recommended. However, the error message does give us a clue as to the
source of the problem, indicating that The content of element type must match.
Luckily most standards based DTDs, XML Schemas, and Relax NG schemas are supplied with reference documentation.
This enables us to lookup the element and read about it. In this case you should learn about the child elements of
listitem and their nesting rules. Once you have correctly inserted the required child element and nested it in accordance
with the XML rules, the document will become valid on the next validation test.
Automatic Validation
Oxygen XML Editor can be configured to mark validation errors in the document as you are editing. If you enable the
Automatic validation option, all validation errors and warnings will be highlighted automatically in the editor panel.
The automatic validation starts parsing the document and marking the errors after a configurable delay from the last
key typed. Errors are highlighted with underline markers in the main editor panel and small rectangles on the right side
ruler of the editor panel, in the same way as for manual validation invoked by the user. Hovering over a validation error
presents a tooltip message with more details about the error.
LIBXML - Included in Oxygen XML Editor (Windows edition only). It is associated to XML Editor. It is able to
validate the edited document against XML Schema, Relax NG schema full syntax, internal DTD (included in the
XML document) or a custom schema type. XML catalogs support (the --catalogs parameter) and XInclude processing
(--xinclude) are enabled by default in the preconfigured LIBXML validator. The --postvalid parameter is also set by
default which allows LIBXML to validate correctly the main document even if the XInclude fragments contain
IDREFS to ID's located in other fragments.
For validation against an external DTD specified by URI in the XML document, add the --dtdvalid ${ds} parameter
manually to the DTD validation command line. ${ds} represents the detected DTD declaration in the XML document.
Caution: File paths containing spaces are not handled correctly in the LIBXML processor. For example
the built-in XML catalog files of the predefined document types (DocBook, TEI, DITA, etc) are not handled
by LIBXML if Oxygen XML Editor is installed in the default location on Windows (C:\Program Files)
because the built-in XML catalog files are stored in the frameworks subfolder of the installation folder
which in this case contains at least one space character in the file path.
Attention: On OS X if the full path to the LIBXML executable file is not specified in the Executable path
text field, some errors may occur during validation against a W3C XML Schema, such as:
Unimplemented block at ... xmlschema.c
To avoid these errors, specify the full path to the LIBXML executable file.
Saxon-EE - Included in Oxygen XML Editor. It is associated to XML Editor and XSD Editor. It is able to validate
XML Schema schemas and XML documents against XML Schema schemas. The validation is done according to
the W3C XML Schema 1.0 or 1.1. This can be configured in Preferences.
MSXML 4.0 - Included in Oxygen XML Editor (Windows edition only). It is associated to XML Editor, XSD Editor
and XSL Editor. It is able to validate the edited document against XML Schema, internal DTD (included in the XML
document), external DTD or a custom schema type.
A custom validator cannot be applied on files loaded through an Oxygen XML Editor custom protocol plugin developed
independently and added to Oxygen XML Editor after installation.
Linked Output Messages of an External Engine
Validation engines display messages in an output view at the bottom of the Oxygen XML Editor window. If such an
output message (warning, error, fatal error, etc) spans between three to six lines of text and has the following format,
then the message is linked to a location in the validated document. Clicking the message in the output view highlights
the location of the message in an editor panel containing the file referenced in the message. This behavior is similar to
the linked messages generated by the default built-in validator.
Linked messages have the following format:
Type:[F|E|W] (the string Type: followed by a letter for the type of the message: fatal error, error, warning) - this
property is optional in a linked message
SystemID: a system ID of a file (the string SystemID: followed by the system ID of the file that will be opened
for highlighting when the message is clicked in the output message - usually the validated file, the schema file or an
included file)
Line: a line number (the string Line: followed by the number of the line that will be highlighted)
Column: a column number (the string Column: followed by the number of the column where the highlight will start
on the highlighted line) - this property is optional in a linked message
EndLine: a line number (the string EndLine: followed by the number of the line where the highlight ends) - this
property is optional in a linked message
EndColumn: a column number (the string EndColumn: followed by the number of the column where the highlight
ends on the end line) - this property is optional in a linked message
Note: The Line/Column pair works in conjunction with the EndLine/EndColumn pair. Thus, if both pairs
are specified, then the highlight starts at Line/Column and ends at EndLine/EndColumn. If the
EndLine/EndColumn pair is missing, the highlight starts from the beginning of the line identified by the Line
parameter and ends at the column identified by the Column parameter.
AdditionalInfoURL: the URL string pointing to a remote location where additional information about the error can
be found - this line is optional in a linked message.
Description: message content (the string Description: followed by the content of the message that will be displayed
in the output view).
Example of how a custom validation engine can report an error using the format specified above:
Type: E
SystemID: file:///c:/path/to/validatedFile.xml
Line: 10
Column: 20
EndLine: 10
EndColumn: 35
Validation Scenario
A complex XML document is split in smaller interrelated modules. These modules do not make much sense individually
and cannot be validated in isolation due to interdependencies with other modules. Oxygen XML Editor validates the
main module of the document when an imported module is checked for errors.
A typical example is the chunking DocBook XSL stylesheet which has chunk.xsl as the main module and param.xsl,
chunk-common.xsl, and chunk-code.xsl as imported modules. param.xsl only defines XSLT parameters.
The module chunk-common.xsl defines an XSLT template with the name chunk. Chunk-code.xsl calls this
template. The parameters defined in param.xsl are used in the other modules without being redefined.
Validating chunk-code.xsl as an individual XSLT stylesheet, generates misleading errors in regards to parameters
and templates that are used but undefined. These errors are only caused by ignoring the context in which this module is
used in real XSLT transformations and in which it is validated. To validate such a module, define a validation scenario
to set the main module of the stylesheet and the validation engine used to find the errors. Usually this engine applies
the transformation during the validation process to detect the errors that the transformation generates.
You can validate a stylesheet with several engines to make sure that you can use it in different environments and have
the same results. For example an XSLT stylesheet is applied with Saxon 6.5, Xalan, and MSXML 4.0 in different
production systems.
Other examples of documents which can benefit of a validation scenario are:
A complex XQuery with a main module which imports modules developed independently but validated in the context
of the main module of the query. In an XQuery validation scenario the default validator of Oxygen XML Editor
(Saxon 9) or any connection to a database that supports validation (Berkeley DB XML Database, eXist XML Database,
Documentum xDb (X-Hive/DB) 10 XML Database, MarkLogic version 5 or newer) can be set as a validation engine.
An XML document in which the master file includes smaller fragment files using XML entity references.
Note: When you validate a document for which a master file is defined, Oxygen XML Editor uses the scenarios
defined in the Master Files directory.
To watch our video demonstration about how to use a validation scenario in Oxygen XML Editor, go to
http://oxygenxml.com/demo/Validation_Scenario.html.
How to Create a Validation Scenario
To create a validation scenario, follow these steps:
1. Select the
Configure Validation Scenario(s) from the Document > Validate menu, or the
Validation
toolbar drop-down menu, or from the Validate submenu when invoking the contextual menu on a file in the Project
view .
The Configure Validation Scenario(s) dialog box is displayed. It contains the following types of scenarios:
Predefined scenarios are organized in categories depending on the type of file they apply to. You can identify
Predefined scenarios by a yellow key icon that marks them as read-only. If the predefined scenario is the default
scenario of the framework, its name is written in bold font. You can use the options in the
menu to filter which scenarios are shown.
Settings drop-down
User defined scenarios are organized under a single category, but you can use the options in the
drop-down menu to filter them.
Settings
Note: If the current file has no associated scenarios, the preview area displays a message to let you know
that you can apply the default validation.
4. If you want to add a new validation unit, press the Add button.
5. To edit the URL of the main validation module, double-click its cell in the URL of the file to validate column.
Specify the URL of the main module by doing one of the following:
Enter the URL in the text field or select it from the drop-down list.
Use the
Use the
Selecting Global Options stores the scenario in the global options that are stored in the user home directory.
Selecting Project Options stores the scenario in the project file and can be shared with other users that have access to
the project. If your project is saved on a source versioning/sharing system (CVS, SVN, Source Safe, etc.) then your team
Select the
Validate (Ctrl Shift V (Meta Shift V on OS X)) action from the Document > Validate menu, from
the
Validation toolbar drop-down menu, or from the Validate submenu when invoking the contextual menu
in the Project view . An error list is presented in the message panel. Markup of current document is checked to
conform with the specified DTD, XML Schema, or Relax NG schema rules. This action also re-parses the XML
catalogs and resets the schema used for content completion.
Select the
Validate (cached) action from the Document > Validate menu or from the
Validation toolbar
drop-down menu. This action caches the schema, allowing it to be reused for the next validation. Markup of the
current document is checked to conform with the specified DTD, XML Schema, or Relax NG schema rules.
Note: Automatic validation also caches the associated schema.
Select the Validate with action from the Document > Validate menu, from the
Validation toolbar drop-down
menu, or from the Validate submenu when invoking the contextual menu in the Project view . You can use this
action to validate the current document using a schema of your choice (XML Schema, DTD, Relax NG, NVDL,
Schematron schema), other than the associated one. An error list is presented in the message panel. Markup of current
document is checked to conform with the specified schema rules.
Note: The Validate with action does not work for files loaded through an Oxygen XML Editor custom
protocol plugin developed independently and added to Oxygen XML Editor after installation.
Select Validate with Schema from the Validate submenu when invoking contextual menu in the Project view to
choose a schema and validate all selected files with it.
To open the schema used for validating the current document, select the
Document > Schema menu.
The
Validation options button, available in the Document > Validate menu, allows you to quickly access to the
validation options for the built-in validator in the Oxygen XML Editor preferences page.
Tip: If a large number of validation errors are detected and the validation process takes too long, you can limit
the maximum number of reported errors in the Preferences page.
References to XML Schema Specification
If validation is done against XML Schema Oxygen XML Editor indicates a specification reference relevant for each
validation error. The error messages contain an Info field that when clicked will open the browser on the XML Schema
Part 1:Structures specification at exactly the point where the error is described. This allows you to understand the reason
for that error.
An XML catalog can be used also to map a W3C XML Schema specified with an URN in the xsi:schemaLocation
attribute of an XML document to a local copy of the schema. For example, if the XML document specifies the schema
with:
<topic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="urn:oasis:names:tc:dita:xsd:topic.xsd:1.1">
the URN can be resolved to a local schema file with a catalog entry like:
<uri name="urn:oasis:names:tc:dita:xsd:topic.xsd:1.1"
uri="topic.xsd"/>
Document Navigation
This section explains various methods for navigating the edited XML document.
Quick Document Navigation Using Bookmarks
By using bookmarks, you can mark positions in an edited document so that you can return to it later. This is especially
helpful for navigating through large documents or while editing multiple documents. You can place up to nine distinct
bookmarks in any document. Shortcut keys are available to place the bookmarks or to return to any of the marked
positions. To configure these shortcut keys, go to Options > Menu Shortcut Keys.
Create Bookmark (F9) action from the Edit > Bookmarks menu.
A bookmark can be removed by right-clicking its icon on the vertical strip and select Remove or Remove all (Ctrl+F7)
(you can also find the Remove all (Ctrl+F7) action in the Edit > Bookmarks menu).
You can navigate the bookmarks by using one of the actions available on the Edit > Bookmarks > Go to menu or by
using the shortcut keys.
Folding of the XML Elements
An XML document is organized as a tree of elements. When working on a large document you can collapse some
elements, leaving only the ones you need to edit in the focus. Expanding and collapsing works on individual elements.
Expanding an element leaves the child elements unchanged.
Settings menu in the top-right corner that presents a variety of options to help you filter the view
Document errors (such as an element inserted in an invalid position, or a wrong attribute name, or a missing required
attribute value) are highlighted in the Outline tree:
Modification Follow-up
When you edit a document, the Outline view dynamically follows the changes that you make, displaying the node that
you modify in the middle of the view. This functionality gives you great insight on the location of your modifications
in the document that you edit.
Drag and Drop Actions in Outline View
Entire XML elements can be moved or copied in the edited document using only the mouse in the Outline view with
drag-and-drop operations. Several drag and drop actions are possible:
The drag and drop action in the Outline view can be disabled and enabled from a Preferences page.
Tip: You can select and drag multiple nodes in the Outline view when editing in Author mode.
Document Tag Selection
The Outline view can also be used to search for a specific tag location and contents in the edited document. Intuitively,
by selecting with the left mouse button the desired tag in the Outline view, the document is scrolled to the position of
the selected tag. Moreover, the tag contents are selected in the document, making it easy to notice the part of the document
contained by that specific tag and furthermore to easily copy and paste the tag's contents in other parts of the document
or in other documents.
You can double click the tag in the Outline tree to move the focus in the editor.
You can also use the filter text field search to look for a particular tag name in the Outline tree.
Navigation Buttons
These buttons are available in the main toolbar and the Find menu:
Last Modification - Moves the cursor to the last modification in any opened document.
Back - Moves the cursor to the previous position.
Forward - Moves the cursor to the next position. Enabled after at least one press of the Back button.
Document > Font size > Increase editor font (Ctrl NumPad+[plus sign] (Command NumPad+[plus sign] on
OS X)) - increases the font size with one point for each execution of the action.
Document > Font size > Decrease editor font (Ctrl NumPad-[minus sign] (Command NumPad-[minus sign]
on OS X) ) - decreases the font size with one point for each execution of the action.
Document > Font size > Normal editor font (Ctrl 0 (Command 0 on OS X)) - resets the font size to the value of
the editor font set in Preferences.
Printing a File
Printing is supported in Text, Author, and Grid modes. The Print(Ctrl P (Meta P on OS X)) action that is available
from File menu displays the Page Setup dialog box, used for defining the page size and orientation properties for
printing.
A Print Preview action is also available in the File menu. It allows you to manage the format of the printed document.
Note: If you are printing in the Author visual editing mode to change the styling of the document in the printed
output, you can use the CSS print media type.
Preview area - Displays the formatted document page as it will appear on printed paper.
Left stripe - The left-side stripe that displays a list of thumbnail pages. Clicking any of them displays the page
content in the main preview area.
Toolbar - The toolbar area at the top that contains controls for printing, page settings, page navigation, print scaling,
and zoom.
Note: If your document is open in Author mode and contains Track Changes, you can print (or print preview)
a copy of the document as if all changes have been accepted by switching the Track Changes Visualization
Modes to View Final.
You can use the Find/Replace dialog box to perform the following operations:
Replace occurrences of target defined in the Find area with a new fragment of text defined in Replace with area.
Find all the occurrences of a word or string of characters (that can span over multiple lines) in the document you are
editing. This operation also takes into account all the white spaces contained in the fragment you are searching for.
Note: The Find/Replace dialog box counts the number of occurrences of the text you are searching for and
displays it at the bottom of the dialog box, above the Close button. This number is also displayed in the Results
view.
The find operation works on multiple lines, meaning that a find match can cover characters on more than one line of
text. To input multiple-line text in the Find and Replace with areas, do one of the following:
You can use Perl-like regular expressions syntax to define patterns. A content completion assistant window is available
in the Find and Replace with areas to help you edit regular expressions. It is activated every time you type \(backslash
key) or on-demand if you press Ctrl Space (Command Space on OS X) on your keyboard.
The replace operation can bind regular expression capturing groups ($1, $2, etc.) from the find pattern.
To replace the tag-name start tag and its attributes with the new-tag-name tag use as Find the
expression <tag-name(\s+)(.*)> and as Replace with the expression <new-tag-name$1$2>.
The dialog box contains the following options:
Find - The target character string to search for. You can search for Unicode characters specified in the \uNNNN
format. Also, hexadecimal notation (\xNNNN) and octal notation (\0NNNN) can be used. In this case you have to
select the Regular expression option. For example, to search for a space character you can use the \u0020 code.
Replace with - The character string with which to replace the target. The string for replace can be on a line or on
multiple lines. It can contain Perl notation capturing groups, only if the search expression is a regular expression and
the Regular expression option is selected.
Note: Some regular expressions can block indefinitely the application. If the execution of the regular
expression does not end in about 5 seconds, the application displays a dialog box that allows you to interrupt
the operation.
Note: Special characters like newline and tab can be inserted in the Find and Replace with text boxes using
dedicated actions in the contextual menu (Insert newline and Insert tab).
Unicode characters in the \uNNNN format can also be used in the Replace with area.
The
History button - Contain lists of the last find and replace expressions. Use the
Clear history action from
the bottom of the lists to remove these expressions.
XPath - The XPath 2.0 expression you input in this combo is used for restricting the search scope.
Note: The Content Completion Assistant helps you input XPath expressions, valid in the current context.
Direction - Specifies if the search direction is from current position to end of file (Forward) or to start of file
(Backward).
Scope - Specifies whether the Find/Replace operation is executed over the entire content of the edited document
(All option), or over the selected lines of text (Only selected lines option). If the selection spans across multiple
lines, when you open the Find/Replace dialog box, the scope is set to Only selected lines.
Dot matches all - A dot used in a regular expression also matches end of line characters.
Canonical equivalence - If enabled, two characters will be considered a match if, and only if, their full canonical
decompositions match. For example, the symbol can be inserted as a single character or as two characters (the
a character, followed by the tilde character). This option is disabled by default.
Wrap around - When the end of the document is reached, the search operation is continued from the start of the
document, until its entire content is covered.
Enable XML search options - This option is only available when editing in Text mode. It provides access to a set
of options that allow you to search specific XML component types:
Element names - Only the element names are included in the search operation which ignores XML-tag notations
('<', '/', '>'), attributes or white-spaces.
Element contents - Search in the text content of XML elements.
Attribute names - Only the attribute names are included in the search operation, without the leading or trailing
white-spaces.
Attribute values - Only the attribute values are included in the search operation, without single quotes(') or
double quotes(").
Comments - Only the content of comments is included in the search operation, excluding the XML comment
delimiters ('<!--', '-->').
PIs (Processing Instructions) - Only the content are searched, skipping '<?', '?>'. e. g.: <?processing instruction?>
CDATA - Searches inside content of CDATA sections.
DOCTYPE - Searches inside content of DOCTYPE sections.
Entities - Only the entity names are searched.
The two buttons Select All and Deselect All allow a simple activation and deactivation of all types of XML
components.
Note: Even if you enable all options of the Enable XML search options section, the search is still
XML-aware. If you want to perform the search over the entire file content, disable Enable XML search
options.
Find All Elements - Available when editing in Author mode, you can use this link to extend the search scope to
XML-specific markup (names and values of both attributes and elements).
Find - Executes a find operation for the next occurrence of the target. It stops after highlighting the find match in
the editor panel.
Replace - Executes a replace operation for the target followed by a find operation for the next occurrence.
Find All - Executes a find operation and displays all results in the Results view. The results are displayed in the
Results view.
Replace All - Executes a replace operation in the entire scope of the document.
Replace to End - Executes a replace operation starting from current target until the end of the document, in the
direction specified by the current selection of the Direction switch (Forward or Backward).
You can combine all of these search criteria to filter your results.
The following fields are available in the dialog box:
Element name - The qualified name of the target element to search for. You can use the drop-down menu to find
an element or enter it manually. It is populated with valid element names collected from the associated schema. To
specify any element name, leave the field empty.
Note: Use the qualified name of the element (<namespace prefix>:<element name>) when the
document uses this element notation.
Element text - The target element text to search for. The drop-down menu beside this field allows you to specify
whether you are looking for an exact or partial match of the element text. For any element text, select contains from
the drop-down menu and leave the field empty. If you leave the field empty but select equals from the drop-down
menu, only elements with no text will be found. Select not contains to find all elements that do not include the
specified text.
Attribute name - The name of the attribute that must be present in the element. You can use the drop-down menu
to select an attribute or enter it manually. It is populated with valid attribute names collected from the associated
schema. For any or no attribute name, leave the field empty.
Note: Use the qualified name of the attribute (<namespace prefix>:<attribute name>) when
the document uses this attribute notation.
Attribute value - The drop-down menu beside this field allows you to specify that you are looking for an exact or
partial match of the attribute value. For any or no attribute value, select contains from the drop-down menu and
leave the field empty. If you leave the field empty but select equals from the drop-down menu, only elements that
have at least an attribute with an empty value will be found. Select not contains to find all elements that have
attributes without a specified value.
Case sensitive - When this option is checked, operations are case-sensitive
When you press Find All, Oxygen XML Editor tries to find the items that match all the search parameters. The results
of the operation are presented as a list in the message panel.
The Quick Find Toolbar
A reduced version of the Find / Replace dialog box is available as a dockable toolbar. To display it press the Alt Shift
F (Meta Alt F on OS X) key combination or invoke the Find >
A search input box where you insert the text you want to search for. The input box keeps a history of the last used
search text. The background color of the input box turns red when no match is found.
Next and Previous buttons. They allow you to advance to the next or previous match.
All button. Highlights in the current document all matches of the search string.
Incremental check box. The search operation is started every time you type or delete a character in the search input
box.
Case sensitive check box. When selected, the search operation follows the exact letter case of the search text.
Shortcuts to the
Find/Replace and
There are some other notable differences that may cause unexpected results, including the following:
In Perl, \1 through \9 are always interpreted as back references; a backslash-escaped number greater than 9 is
treated as a back reference if at least that many sub-expressions exist, otherwise it is interpreted, if possible, as an
octal escape. In this class octal escapes must always begin with a zero. In Java, \1 through \9 are always interpreted
as back references, and a larger number is accepted as a back reference if at least that many sub-expressions exist at
that point in the regular expression, otherwise the parser will drop digits until the number is smaller or equal to the
existing number of groups or it is one digit.
Perl uses the g flag to request a match that resumes where the last match left off.
In Perl, embedded flags at the top level of an expression affect the whole expression. In Java, embedded flags always
take effect at the point at which they appear, whether they are at the top level or within a group; in the latter case,
flags are restored at the end of the group just as in Perl.
Perl is forgiving about malformed matching constructs, as in the expression *a, as well as dangling brackets, as in
the expression abc], and treats them as literals. This class also accepts dangling brackets but is strict about dangling
meta-characters like +, ? and *.
The operation works on both local and remote files from an (S)FTP, WebDAV or CMS server.
It enables you to define Search for or Search for and Replace operations across a number of files. You can use Perl-like
regular expression syntax to match patterns in text content. The replace operation can bind regular expression capturing
groups ($1, $2, etc.) from the find pattern.
To replace the tag-name start tag and its attributes with the new-tag-name tag use as Text to
find the expression <tag-name(\s+)(.*)> and as Replace with the expression <new-tag-name$1$2>.
The encoding used to read and write the files is detected from the XML header or from the BOM. If a file does not have
an XML header or BOM Oxygen XML Editor uses by default the UTF-8 encoding for files of type XML, that is for
files with one of the extensions: .xml, .xsl, .fo, .xsd, .rng, .nvdl, .sch, .wsdl or an extension associated
with the XML editor type. For the other files it uses the encoding configured for non-XML files.
You can cancel a long operation at any time by pressing the Cancel button of the progress dialog box displayed when
the operation is executed.
Since the content of read-only files cannot be modified, the Replace operation is not processing those files. For every
such file, a warning message is displayed in the message panel.
Text to find - The target character string to search for. You can search for Unicode characters specified in the
\uNNNN format. Also, hexadecimal notation (\xNNNN) and octal notation (\0NNNN) can be used. In this case you
have to select the Regular expression option. For example, to search for a space character you can use the \u0020
code.
Case sensitive - When checked, the search operation follows the exact letter case of the value entered in the Text
to find field.
Whole words only - Only entire occurrences of a word are included in the search operation.
Ignore extra whitespaces - If enabled, the application normalizes the content (collapses any sequence of whitespace
characters into a single space) and trims its leading and trailing whitespaces when performing the search operation.
Regular expression - When this option is enabled, you can use regular expressions in Perl-like regular expressions
syntax to look for specific pieces of text.
Dot matches all - A dot used in a regular expression also matches end of line characters.
Canonical equivalence - If enabled, two characters will be considered a match if, and only if, their full canonical
decompositions match. For example, the symbol can be inserted as a single character or as two characters (the
a character, followed by the tilde character). This option is disabled by default.
XPath - The XPath 2.0 expression you input in this combo is used for restricting the search scope.
Note: The Content Completion Assistant helps you input XPath expressions, valid in the current context.
Enable XML search options - This option is only available when editing in Text mode. It provides access to a set
of options that allow you to search specific XML component types:
Element names - Only the element names are included in the search operation which ignores XML-tag notations
('<', '/', '>'), attributes or white-spaces.
Element contents - Search in the text content of XML elements.
Attribute names - Only the attribute names are included in the search operation, without the leading or trailing
white-spaces.
Attribute values - Only the attribute values are included in the search operation, without single quotes(') or
double quotes(").
Comments - Only the content of comments is included in the search operation, excluding the XML comment
delimiters ('<!--', '-->').
PIs (Processing Instructions) - Only the content are searched, skipping '<?', '?>'. e. g.: <?processing instruction?>
CDATA - Searches inside content of CDATA sections.
DOCTYPE - Searches inside content of DOCTYPE sections.
Entities - Only the entity names are searched.
The two buttons Select All and Deselect All allow a simple activation and deactivation of all types of XML
components.
Note: Even if you enable all options of the Enable XML search options section, the search is still
XML-aware. If you want to perform the search over the entire file content, disable Enable XML search
options.
Replace with - The character string with which to replace the target. It may contain regular expression group markers
if the search expression is a regular expression and the Regular expression checkbox is checked.
Make backup files with extension - In the replace process Oxygen XML Editor makes backup files of the modified
files. The default extension is .bak, but you can change the extension as you prefer.
Selected project resources - Searches only in the selected files of the currently opened project. This option is not
displayed when this dialog box is opened from the contextual menu of the DITA Maps Manager view and Archive
Browser view.
Project files - Searches in all files from the current project. This option is not displayed when this dialog box is
opened from the contextual menu of the DITA Maps Manager view and Archive Browser view.
When you replace a fragment of text, Oxygen XML Editor provides a preview of the changes you make. The Preview
dialog box is divided in two sections. The first section presents a list of all the documents containing the fragment of
text you want to modify. The second section offers a view of the original file and a view of the final result. It also allows
you to highlight all changes using the vertical bar from the right side of the view. The Next change and Previous change
buttons allow you to navigate through the changes displayed in the Preview dialog box.
Caution: Use this option with caution. Global search and replace across all project files does not open the files
containing the targets, nor does it prompt on a per occurrence basis, to confirm that a replace operation must be
performed. As the operation simply matches the string defined in the find field, this may result in replacement
of matching strings that were not originally intended to be replaced.
The master document should declare the DTD to be used, while the external entities should declare the XML sections
to be referenced.
The document containing the section must not define again the DTD.
Note:
The indicated DTD and the element names (section, chapter) are used here only for illustrating the inclusion
mechanism. You can use any DTD and element names you need.
At a certain point in the master document there can be inserted the section testing.xml entity:
... &testing; ...
When splitting a large document and including the separate parts in the master file using external entities, only the master
file will contain the Document Type Definition (the DTD) or other type of schema. The included sections can not define
the schema again because the main document will not be valid. If you want to validate the parts separately you have to
use XInclude for assembling the parts together with the master file.
Including Document Parts with XInclude
XInclude is a standard for assembling XML instances into another XML document through inclusion. It enables larger
documents to be dynamically created from smaller XML documents without having to physically duplicate the content
of the smaller files in the main file. XInclude is targeted as the replacement for External Entities. The advantage of using
XInclude is that, unlike the entities method, each of the assembled documents is permitted to contain a Document Type
Declaration (DOCTYPE). This means that each file is a valid XML instance and can be independently validated. It also
means that the main document to which smaller instances are included can be validated without having to remove or
comment out the DOCTYPE. as is the case with External Entities. This makes XInclude a more convenient and effective
method for managing XML instances that need to be stand-alone documents and part of a much larger project.
The main application for XInclude is in the document-oriented content frameworks such as manuals and Web pages.
Employing XInclude enables authors and content managers to manage content in a modular fashion that is akin to Object
Oriented methods used in languages such as Java, C++ or C#.
The advantages of modular documentation include: reusable content units, smaller file units that are easier to be edited,
better version control and distributed authoring.
Include a chapter in an article using XInclude
Create a chapter file and an article file in the samples folder of the Oxygen XML Editor install
folder.
Chapter file (introduction.xml) looks like this:
<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<chapter>
<title>Getting started</title>
<section>
<title>Section title</title>
<para>Para text</para>
</section>
</chapter>
The DOCTYPE declaration defines an entity that references a file containing the information to add the xi namespace
to certain elements defined by the DocBook DTD.
The href attribute of the xi:include element specifies that the introduction.xml file will replace the xi:include
element when the document is parsed.
If the introduction.xml file cannot be found, the parser will use the value of the xi:fallback element - a FIXME
message.
If you want to include only a fragment of a file in the master file, the fragment must be contained in a tag having an
xml:id attribute and you must use an XPointer expression pointing to the xml:id value. For example if the master file
is:
<?xml version="1.0" encoding="UTF-8"?>
<?xml-model href="test.rng" type="application/xml" schematypens="http://relaxng.org/ns/structure/1.0"?>
<test>
<xi:include href="a.xml" xpointer="a1"
xmlns:xi="http://www.w3.org/2001/XInclude"/>
</test>
The XInclude support in Oxygen XML Editor is enabled by default. To configure it, open the Preferences dialog box
and go to XML > XML Parser > Enable XInclude processing. When enabled, Oxygen XML Editor will be able to
validate and transform documents comprised of parts added using XInclude.
Mappings
XML
system or public
DTD
The Prefer option controls which one of the mappings should be used.
XML Schema
The following strategy is used (if one step fails to provide a resource, the next is applied):
Relax NG
Schematron
NVDL
This happens only if the Resolve schema locations also through system mappings
option is enabled (it is by default).
3. resolve the root namespace using URI catalog mappings.
XSL
XSL/ANY
URI
CSS
CSS
URI
XML
XML Schema
Schema
Relax
NG
Relax NG
The following strategy is used (if one step fails to provide a resource, the next is applied):
1. resolve schema reference using URI catalog mappings.
2. resolve schema reference using system catalog mappings.
This happens only if the Resolve schema locations also through system mappings
option is enabled (it is by default).
3. resolve schema namespace using uri catalog mappings.
This happens only if the Process namespaces through URI mappings for XML Schema
option is enabled (it is not by default).
An XML Catalog file can be created quickly in Oxygen XML Editor starting from the two XML Catalog document
templates called OASIS XML Catalog 1.0 and OASIS XML Catalog 1.1 and available when creating new document
templates.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE catalog
PUBLIC "-//OASIS//DTD XML Catalogs V1.1//EN"
"http://www.oasis-open.org/committees/entity/release/1.1/catalog.dtd">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<!-- Use "system" and "public" mappings when resolving DTDs -->
<system
systemId="http://www.docbook.org/xml/4.4/docbookx.dtd"
uri="frameworks/docbook/4.4/dtd/docbookx.dtd"/>
<!-- The "systemSuffix" matches any system ID ending in a specified string -->
<systemSuffix
systemIdSuffix="docbookx.dtd"
uri="frameworks/docbook/dtd/docbookx.dtd"/>
<!-- Use "uri" for resolving XML Schema and XSLT stylesheets -->
<uri
name="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng"
uri="frameworks/docbook/5.0/rng/docbookxi.rng"/>
Oxygen XML Editor comes with a built-in catalog set as default, but you can also create your own one. Oxygen XML
Editor looks for a catalog in the following order:
The URN can be resolved to a local schema file with a catalog entry like:
<uri name="urn:oasis:names:tc:dita:xsd:topic.xsd:1.1"
uri="topic.xsd"/>
First, it attempts to resolve the schema location as a URI (uri, uriSuffix, rerwriteURI mappings from the
XML catalog). If this succeeds, the process end here.
If the Resolve schema locations also through system mappings option is selected, it attempts to resolve the schema
location as a systemID (system, systemSuffix, rewriteSuffix, rerwriteSystem from the XML catalog).
If this succeeds, the process ends here.
If the Process namespace through URI mappings for XML Schema option is selected, it attempts to resolve the
location by processing the schema namespace as a URI (uri, uriSuffix, rewriteURI from the XML catalog).
The namespace is taken into account only when the schema specified in the schemaLocation attribute was not resolved
successfully. If this succeeds, the process ends here.
If none of these succeeds, the actual schema location is used.
To open this view, go to Window > Show View > Resource Hierarchy/Dependencies . As an alternative, right click
the current document and either select Resource Hierarchy or Resource Dependencies.
Figure 127: Resource Hierarchy/Dependencies View - Hierarchy for Syncro phone v1.xml
The build process for the dependencies view is started with the Resource Dependencies action available on the contextual
menu.
New name - Presents the current name of the edited resource and allows you to modify it.
Update references - Enable this option to update the references to the resource you are renaming.
When you select the Move action from the contextual menu of the Resource/Hierarchy Dependencies view, the Move
resource dialog box is displayed. The following fields are available:
If the Update references of the moved resource(s) option is enabled, a Preview option (which opens the Preview
dialog box) is available for both actions. The Preview dialog box presents a list with the resources that are updated.
xmlns - Specifies the default namespace, that is the namespace used for unqualified element names.
xmlns - Each row specifies the prefix used for a namespace in the input schema.
Output panel:
disable-abstract-elements - Disables the use of abstract elements and substitution groups in the generated XML
Schema. This can also be controlled using an annotation attribute.
any-process-contents - One of the values: strict, lax, skip. Specifies the value for the processContents attribute
of any elements. The default is skip (corresponding to RELAX NG semantics) unless the input format is DTD, in
which case the default is strict (corresponding to DTD semantics).
any-attribute-process-contents - Specifies the value for the processContents attribute of anyAttribute
elements. The default is skip (corresponding to RELAX NG semantics).
To watch our video demonstration about editing modular XML files in the master files context, go to
http://oxygenxml.com/demo/Working_With_XML_Modules.html.
Image Preview
Images and SVG files from the Project view can be previewed in a separate panel.
To preview an image, either double click the image name or click the Preview action from the Project view's contextual
menu. Supported image types are GIF, JPEG/JPG, PNG, BMP. Once the image is displayed in the Preview panel using
the actions from the contextual menu, you can scale the image to its original size (1:1 action) or scale it down to fit in
the view's available area (Scale to fit action).
To preview an SVG file, click the Preview action from the Project view's contextual menu. Once the SVG is displayed
in the Preview panel, the following actions are available on the contextual menu: Zoom in, Zoom out, Rotate and
Refresh.
Note: You can drag an image from the Image Preview view and drop it in a DITA, DocBook, or TEI document.
document validation
checking the form of documents
XSLT or FO transformation
find all occurrences of a string in a file
find all occurrences of a string in multiple files
applying an XPath expression to the current document
To make a persistent copy of the Results panel, use one of these actions:
You can set the default lock state for all opened editors using the Lock the XML tags option in the Text preferences
page.
Editor Highlights
An editor highlight is a text fragment emphasized by a colored background.
Highlights are generated in both Text and Author mode when the following actions generate results:
Find/Replace in Files
Open/Find Resource
Find All
Find All Elements
XPath in Files
Search References
Search Declarations
By default, Oxygen XML Editor uses a different color for each type of highlight (XPath in Files, Find/Replace, Search
References, Search Declarations, etc.) You can customize these colors and the maximum number of highlights displayed
in a document on the Editor preferences page. The default maximum number of highlights is 10000.
You are able to navigate the highlights in the current document by using the following methods:
Clicking the markers from the range ruler, located at the right side of the document.
Clicking the
Next and Previous buttons from the bottom of the range ruler.
Note: When there are multiple types of highlights in the document, the
navigate through highlights of the same type.
Clicking the messages displayed in the Results view at the bottom of the editor.
Click the Remove all button from bottom of the range ruler.
Close the results tab at the bottom of the editor that contains the output of the action that generated the highlights.
Click the
Remove all button from the results panel at the bottom of the editor.
Highlight all results in editor button to either display all the highlights or hide them.
When hovering over the error or warning, the proposals are presented in a tooltip popup window and the available
quick fixes include a link that can be used to perform the fix.
When hovering over the error or warning in Author mode, a small quick fix drop-down menu is presented. You can
use the drop-down menu to display a list of available quick fixes to select from for the particular error or warning.
If you place the cursor in the highlighted area where a validation error or warning occurs, a quick fix icon ( ) is
displayed in the stripe on the left side of the editor. If you click this icon, Oxygen XML Editor displays the list of
available fixes.
Icon
With the cursor placed in the highlighted area of the error or warning, you can also invoke the quick fix menu by
pressing Alt 1 (Meta Alt 1 on OS X) on your keyboard.
Whenever you make a modification in the XML document or you apply a fix, the list of quick fixes is recomputed to
ensure that you always have valid proposals.
Note: A quick fix that adds an element inserts it along with required and optional elements, and required and
fixed attributes, depending on how the Content Completion Assistant options are configured.
Quick Fixes for XSD and Relax NG Errors
Oxygen XML Editor offers quick fixes for common errors that appear in XML documents that are validated against
XSD or Relax NG schemas.
Note: For XML documents validated against XSD schemas, the quick fixes are only available if you use the
default Xerces validation engine.
Quick fixes are available in Text mode and Author mode.
Oxygen XML Editor provides quick fixes for numerous types of problems, including the following:
References to an invalid ID
Include files - Allows you to filter the selected resources by using a file pattern. For example, to restrict the
operation to only analyze build files you could use build*.xml for the file pattern.
Restrict only to known XML file types - When enabled, only resources with a known XML file type will be
affected by the operation.
Look inside archives - When enabled, the resources inside archives will also be affected.
Note: It is recommended that you use the Preview button to review all the changes that will be made by the
refactoring operation before applying the changes.
The parent Element of the attribute to be changed, in the form of a local name from any namespace, a local
name with a namespace prefix, or an XPath expression.
The Local name, Namespace, and Value of the affected attribute.
One of the following choices for the Operation mode in the Options section:
Delete attribute
Use this operation to remove one or more attributes. To perform this operation, specify the following parameters:
The parent Element of the attribute to be deleted, in the form of a local name from any namespace, a local name
with a namespace prefix, or an XPath expression.
The name of the Attribute to be deleted.
Tip: Use the link provided in the lower part of the wizard to open the XML / XSLT-FO-XQuery / XPath
preferences page where you can configure XPath options and declare namespace prefixes.
Rename attribute
Use this operation to rename an attribute. Specify the following parameters in the Rename attribute dialog box:
The parent Element of the attribute to be renamed, in the form of a local name from any namespace, a local
name with a namespace prefix, or an XPath expression.
The name of the Attribute to be renamed.
New local name of the attribute.
Tip: Use the link provided in the lower part of the wizard to open the XML / XSLT-FO-XQuery / XPath
preferences page where you can configure XPath options and declare namespace prefixes.
The target Element to be deleted, in the form of a local name from any namespace, a local name with a namespace
prefix, or an XPath expression.
Tip: Use the link provided in the lower part of the wizard to open the XML / XSLT-FO-XQuery / XPath
preferences page where you can configure XPath options and declare namespace prefixes.
The target Element in which its content is to be deleted, in the form of a local name from any namespace, a
local name with a namespace prefix, or an XPath expression.
Tip: Use the link provided in the lower part of the wizard to open the XML / XSLT-FO-XQuery / XPath
preferences page where you can configure XPath options and declare namespace prefixes.
Insert element
Use this operation to insert new elements. To perform this operation, specify the following parameters:
Rename element
Use this operation to rename elements. To perform this operation, specify the following parameters:
The Target elements (XPath) to be renamed, in the form of a local name from any namespace, a local name
with a namespace prefix, or other XPath expressions.
The New local name of the element.
Tip: Use the link provided in the lower part of the wizard to open the XML / XSLT-FO-XQuery / XPath
preferences page where you can configure XPath options and declare namespace prefixes.
Unwrap element
Use this operation to remove the surrounding tags of elements, while keeping the content unchanged. To perform
this operation, specify the following parameters:
The Target elements (XPath) for which its surrounding tags will be removed, in the form of a local name from
any namespace, a local name with a namespace prefix, or other XPath expressions.
The Target elements (XPath) to be surrounded with tags, in the form of a local name from any namespace, a
local name with a namespace prefix, or other XPath expressions.
The Local name of the Wrapper element.
The Namespace of the Wrapper element.
Tip: Use the link provided in the lower part of the wizard to open the XML / XSLT-FO-XQuery / XPath
preferences page where you can configure XPath options and declare namespace prefixes.
The Target elements (XPath) to surround its content with tags, in the form of a local name from any namespace,
a local name with a namespace prefix, or other XPath expressions.
The Local name of the Wrapper element in which its content will be wrapped.
The Namespace of the Wrapper element in which its content will be wrapped.
Tip: Use the link provided in the lower part of the wizard to open the XML / XSLT-FO-XQuery / XPath
preferences page where you can configure XPath options and declare namespace prefixes.
The Target elements (XPath) for which its content will be replaced, in the form of a local name from any
namespace, a local name with a namespace prefix, or other XPath expressions.
The XML Fragment with which to replace the content of the target element.
Tip: Use the link provided in the lower part of the wizard to open the XML / XSLT-FO-XQuery / XPath
preferences page where you can configure XPath options and declare namespace prefixes.
The Target elements (XPath) to be replaced, in the form of a local name from any namespace, a local name
with a namespace prefix, or other XPath expressions.
Additional Notes
Note: There are some operations that allows <ANY> for the local name and namespace parameters. This value
can be used to select an element or attribute regardless of its local name or namespace. Also, the
<NO_NAMESPACE> value can be used to select nodes that do not belong to a namespace.
Note: Some operations have parameters that accept XPath expressions to match elements or attributes. In these
XPath expressions you can only use the prefixes declared in the Options > Preferences > XML >
XSLT-FO-XQUERY > XPath page. This preferences page can be easily opened by clicking the link in the note
(Each prefix used in an XPath expression must be declared in the Default prefix-namespace mappings
section) at the bottom of the Configure Operation Parameters wizard page.
Custom Refactoring Operations
If none of the predefined operations will help you accomplish a particular refactoring task, you can create a custom
operation that is specific to your needs. For example, if you want to convert an attribute to an element and insert the
element as the first child of the parent element, a custom refactoring operation needs to be created.
Note: The custom refactoring operations are only available in the Enterprise edition.
An XML Refactoring operation is defined as a pair of resources:
An XQuery Update script or XSLT stylesheet that Oxygen XML Editor will run in order to refactor the XML files.
An XML Operation Descriptor file that contains information about the operation, such as the name, description, and
parameters.
The XInclude mechanism is disabled. This means that the resources included by using XInclude will not be
visible in the transformation.
The DTD entities will be processed without being expanded.
The associated DTD will be not loaded, so the default attributes declared in the DTD will not be visible in the
transformation.
label - This value is displayed in the user interface for the parameter.
name - The parameter name used in the XQuery Update script or XSLT stylesheet and it should be the same as the
one declared in the script.
type - Defines the type of the parameter and how it will be rendered. There are several types available:
description - The description of the parameter. It is used by the application to display a tooltip when you hover
over the parameter.
possibleValues - Contains the list with possible values for the parameter and you can specify the default value,
as in the following example:
<possibleValues onlyPossibleValuesAllowed="true">
<value name="before">Before</value>
<value name="after"default="true">After</value>
<value name="firstChild">First child</value>
<value name="lastChild">Last child</value>
</possibleValues>
attributeLocation
This parameter is used to match attributes. For this type of parameter, the application displays two text fields where
you can enter the parent element name and the attribute name (both text fields accept XPath expressions for a finer
match). The text from the label attributes is displayed in the application as the label of the associated text fields.
The name attribute is used to specify the name of the parameter from the XQuery Update script or XSLT stylesheet.
The value of this parameter is an XPath expression that is computed by using the values of the expression from the
element and attribute text fields. For example, if section is entered for the element and a title is entered
for the attribute, the XPath expression would be computed as //section/@title. If the value of the
useCurrentContext attribute is set to true, the element and attribute name from the cursor position is used
as proposed values for the operation parameters.
Example of an attributeLocation:
<attributeLocation name="attr_xpath" useCurrentContext="true">
<element label="Element path">
<description>Element path description.</description>
</element>
<attribute label="Attribute" >
<description>Attribute path description.</description>
</attribute>
</ AttributeLocation>
attributeParameter
This parameter is used to specify attributes by local name and namespace. For this type of parameter, the application
displays two combo boxes with attributes and their namespaces collected from the associated schema of the currently
edited file. The text from the label attribute is displayed in the application as the label of the associated combo
box. You can also use the useCurrentContext attribute and if its value is set to true, the attribute name and
namespace from the cursor position is used as proposed values for the operation parameters.
Note: An attributeParameter is dependant upon an elementParameter. The list of attributes
and namespaces are computed based on the selection in the elementParameter combo boxes.
Example of an attributeParameter:
<attributeParameter dependsOn="elemID">
<localName label="Name" name="attribute_localName" useCurrentContext="true">
<description>The name of the attribute to be converted.</description>
</localName>
<namespace label="Namespace" name="attribute_namespace" allowsAny="true">
<description>The namespace of the attribute to be converted.</description>
</namespace>
</attributeParameter>
Note: All predefined operations are loaded from the [OXYGEN_DIR]/refactoring folder.
Example of an XML Refactoring Operation
To demonstrate creating a custom operation, consider that we have a task where we need to convert an attribute into an
element and insert it inside another element. A specific example would be if you have a project with a variety of image
elements where a deprecated alt attribute was used for the description and you want to convert all instances of that
attribute into an element with the same name and insert it as the first child of the image element.
Thus, our task is to convert this attribute into an element with the same name and insert it as the first child of the image
element.
Example of an XQuery Update Script for Creating a Custom Operation to Convert an Attribute to an
Element
The XQuery Update script does the following:
Iterates over all elements from the document that have the specified local name and namespace.
Finds the attribute that will be converted to an element.
Computes the QName of the new element to be inserted and inserts it as the first child of the parent element.
(:
XQuery document used to implement 'Convert attribute to element' operation from XML Refactoring tool.
:)
declare namespace output = "http://www.w3.org/2010/xslt-xquery-serialization";
declare option output:method
"xml";
declare option output:indent
"no";
(: Local name of the attribute's parent element. :)
declare variable $element_localName as xs:string external;
(: Namespace of the attribute's parent element. :)
declare variable $element_namespace as xs:string external;
(: The local name of the attribute to be converted :)
declare variable $attribute_localName as xs:string external;
(: The namespace of the attribute to be converted :)
declare variable $attribute_namespace as xs:string external;
(: Local name of the new element. :)
declare variable $new_element_localName as xs:string external;
(: Namespace of the new element. :)
declare variable $new_element_namespace as xs:string external;
(: Convert attribute to element:)
for $node in //*
(: Find the attribute to convert :)
let $attribute :=
$node/@*[local-name() = $attribute_localName and
($attribute_namespace = '<ANY>' or $attribute_namespace = namespace-uri())]
(: Compute the prefix for the new element to insert :)
let $prefix :=
for $p in in-scope-prefixes($node)
where $new_element_namespace = namespace-uri-for-prefix($p, $node)
return $p
Example of an XSLT Script for Creating a Custom Operation to Convert an Attribute to an Element
The XSLT stylesheet does the following:
Iterates over all elements from the document that have the specified local name and namespace.
Finds the attribute that will be converted to an element.
Adds the new element as the first child of the parent element.
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
exclude-result-prefixes="xs"
xmlns:xr="http://www.oxygenxml.com/ns/xmlRefactoring"
version="2.0">
<xsl:import href="http://www.oxygenxml.com/ns/xmlRefactoring/resources/commons.xsl"/>
<xsl:param
<xsl:param
<xsl:param
<xsl:param
<xsl:param
<xsl:param
Note: If you are using an XSLT file, the line with the script element would look like this:
<script type="XSLT" href="convert-attribute-to-element.xsl"/>
Results
After you have created these files, copy them into a folder scanned by Oxygen XML Editor when it loads the custom
operation. When the XML Refactoring tool is started again, you will see the created operation.
Since various parameters can be specified, this custom operation can also be used for other similar tasks. The following
image shows the parameters that can be specified in our example of the custom operation to convert an attribute to an
element:
A refactoring folder, created inside a directory that is associated to a framework you are customizing.
Any folder. In this case, you need to open the Preferences dialog box, go to XML > XML Refactoring, and specify
the same folder in the Load additional refactoring operations from text box.
Note: If you share a project with your team, you can also share the custom operation by saving them in a
folder that is part of your project. Then switch the XML Refactoring option page at project level (open the
Preferences dialog box, go to XML > XML Refactoring, and select Project Options at the bottom of the
dialog box), and in the Load additional refactoring operations from text box, use the ${pd} editor variable
so that the folder path is declared relative to the project.
By default, there are two validators that are configured for XSLT stylesheets:
MSXML 4.0 - included in Oxygen XML Editor (Windows edition). It is associated to the XSL Editor type in
Preferences page.
MSXML.NET - included in Oxygen XML Editor (Windows edition). It is associated to the XSL Editor type in
Preferences page.
To watch our video demonstration about editing XSLT stylesheets in the master files context, go to
http://oxygenxml.com/demo/MasterFilesSupport.html.
Syntax Highlight
The XSL editor renders the CSS and JS scripts, and XPath expressions with dedicated coloring schemes. To customize
the coloring schemes, open the Preferences dialog box and go to Editor > Syntax Highlight.
The edited file has a transformation scenario that uses as transformation engine Saxon 6.5.5 (for XSLT version 1.0),
Saxon 9.6.0.7 PE or Saxon 9.6.0.7 EE (for XSLT version 2.0 / 3.0).
The edited file has a validation scenario that uses as validation engine Saxon 6.5.5 (for version 1.0), Saxon 9.6.0.7
PE or Saxon 9.6.0.7 EE (for version 2.0 / 3.0).
The validation engine specified in Options page is Saxon 6.5.5 (for version 1.0), Saxon 9.6.0.7 PE or Saxon 9.6.0.7
EE (for version 2.0 / 3.0).
Additionally. the Saxon-CE-specific extension functions and instructions are presented in the Content Completion
Assistant's proposals list only if the http://saxonica.com/ns/interactiveXSLT namespace is declared.
Namespace prefixes in the scope of the current context are presented at the top of the content completion window to
speed up the insertion into the document of prefixed elements.
On XPath operators detected in one of the match, select and test attributes of XSLT elements: ", ', /, //, (, [,
|, :, ::, $
For attribute value templates of non-XSLT elements, that is the { character when detected as the first character of
the attribute value.
On request, if the combination Ctrl Space (Command Space on OS X) is pressed inside an edited XPath expression.
The items presented in the content completion window are dependent on:
For example, if the document associated with the edited stylesheet is:
<personnel>
<person id="Big.Boss">
<name>
<family>Boss</family>
<given>Big</given>
</name>
<email>[email protected]</email>
<link subordinates="one.worker"/>
</person>
<person id="one.worker">
<name>
<family>Worker</family>
<given>One</given>
</name>
<email>[email protected]</email>
<link manager="Big.Boss"/>
</person>
</personnel>
If you enter an xsl:template element using the content completion assistant, the following actions are triggered:
The set of XPath functions depends on the XSLT version declared in the root element xsl:stylesheet: 1.0, 2.0 or
3.0.
When moving the cursor before the first abs function, Oxygen XML Editor identifies it as the first
argument of the concat function. The tooltip shows in bold font the following information about
the first argument:
The function takes also other arguments, having the same type, and returns a xs:string.
Figure 147: XPath Tooltip Helper - Identify the concat Function's First Argument
Moving the cursor on the first variable $v1, the editor identifies the abs as context function and
shows its signature:
Figure 148: XPath Tooltip Helper - Identify the abs Function's Argument
Further, clicking the second abs function name, the editor detects that it represents the second argument
of the concat function. The tooltip is repainted to display the second argument in bold font.
Figure 149: XPath Tooltip Helper - Identify the concat Function's Second Argument
The tooltip helper is available also in the XPath toolbar and the XPath Builder view.
if you drag the given element and drop it inside the xsl:for-each element, the following pop-up
menu is displayed:
Show XML structure option is selected, the following actions are available:
Show components
Switches the Outline view to the components display mode.
Settings menu:
Edit Attributes
Opens a small in-place editor that allow you to edit the attributes of the selected node.
Cut
Cuts the currently selected node.
Copy
Copies the currently selected node.
Delete
Deletes the currently selected node.
Search References Ctrl Shift R (Meta Shift R on OS X)
Searches all references of the item found at current cursor position in the defined scope, if any. See Finding XSLT
References and Declarations for more details.
Search References in
Searches all references of the item found at current cursor position in the specified scope. See Finding XSLT
References and Declarations for more details.
Component Dependencies
Allows you to see the dependencies for the current selected component. See Component Dependencies View for
more details.
Resource Hierarchy
Displays the hierarchy for the currently selected resource.
Resource Dependencies
Displays the dependencies of the currently selected resource.
Rename Component in
Renames the selected component. See XSLT Refactoring Actions for more details.
The following contextual menu actions are available in the Outline view when the
is selected in the
Settings menu:
To switch from tree structure to the filter text field, you can use Tab and Shift-Tab.
Tip: The search filter is case insensitive. The following wildcards are accepted:
* - any string
? - any character
, - patterns separator
For location, the names of the files are sorted alphabetically. The main file is the one you are editing and it is located
at the top of the list.
For type, the order is: parameters, variables, templates, functions, set attributes, character-map.
Note: When no grouping is available and the table is not sorted, Oxygen XML Editor sorts the components
depending on their order in the document. Oxygen XML Editor also takes into account the name of the file
that the components are part of.
Add component documentation - Adds documentation blocks for the component at cursor position.
Paragraph - Inserts a new documentation paragraph.
Bold - Makes the selected documentation text bold.
Italic - Makes the selected documentation text italic.
List - Inserts a new list.
List Item - Inserts a list item.
Reference - Inserts a documentation reference.
If the cursor is positioned inside the xsl:stylesheet element context, documentation blocks are generated for all
XSLT elements. If the cursor is positioned inside a specific XSLT element (like a template or a function), a documentation
block is generated for that element only.
Example of a documentation block using Oxygen XML Editor built-in schema
<xd:doc>
<xd:desc>
<xd:p>Search inside parameter <xd:i>string</xd:i> for the last occurrence of parameter
<xd:i>searched</xd:i>. The substring starting from the 0 position to the identified last
occurrence will be returned. <xd:ref name="f:substring-after-last" type="function"
xmlns:f="http://www.oxygenxml.com/doc/xsl/functions">See also</xd:ref></xd:p>
</xd:desc>
<xd:param name="string">
Output file - You can specify the path of the output file by entering it in the text field, or by using the
Insert
Editor Variables button or the options in the
Browse drop-down menu.
Split output into multiple files - Instructs the application to split the output into multiple files. For large XSLT
stylesheets being documented, choosing a different split criterion may generate smaller output files providing a faster
documentation browsing. You can choose to split them by namespace, location, or component name.
Open in Browser/System Application - Opens the result in the system application associated with the output file
type.
Note: To set the browser or system application that will be used, open the Preferences dialog box, then go
to Global and set it in the Default Internet browser field. This will take precedence over the default system
application settings.
Figure 155: The Settings Tab of the XSLT Stylesheet Documentation Dialog Box
The Settings tab allows you to choose whether or not to include the following components: Templates, Functions,
Global parameters, Global variables, Attribute sets, Character maps, Keys, Decimal formats, Output formats,
Referenced stylesheets.
You can choose whether or not to include the following other details:
Documentation - Shows the documentation for each XSLT element. For HTML format, the user-defined data
elements that are recognized and transformed in documentation blocks of the XSLT elements they precede, are the
ones from the following schemas:
Use comments - Controls whether or not the comments that precede an XSLT element is treated as documentation
for the element they precede. Comments that precede or succeed the xsl:stylesheet element, are treated as
documentation for the whole stylesheet. Note that comments that precede an import or include directive are not
collected as documentation for the imported/included module. Also, comments from within the body of the XSLT
elements are not collected at all.
Namespace - Shows the namespace for named XSLT elements.
Location - Shows the stylesheet location for each XSLT element.
Parameters - Shows parameters of templates and functions.
References - Shows the named XSLT elements that are referenced from within an element.
Used by - Shows the list of all the XSLT elements that reference the current named element.
Supersedes - Shows the list of all the XSLT elements that are superseded the current element.
Overriding - Shows the list of all the XSLT elements that override the current element.
Return type - Shows the return type of the function.
Source - Shows the text stylesheet source for each XSLT element.
Import precedence - Shows the computed import precedence as declared in the XSL transformation specifications.
Generate index - Creates an index with all the XSLT elements included in the documentation.
Export settings - Save the current settings in a settings file for further use (for example, with the exported settings file
you can generate the same documentation from the command-line interface.)
Load settings - Reloads the settings from the exported file.
Generate - Use this button to generate the XSLT documentation.
Generate XSLT Documentation in HTML Format
The XSLT documentation generated in HTML format is presented in a visual diagram style with various sections,
hyperlinks, and options.
Table of Contents - You can group the contents by namespace, location, or component type. The XSLT elements
from each group are sorted alphabetically (named templates are presented first and the match ones second).
Information about main, imported, and included stylesheets. This information consists of:
Search References - Searches all references of the item found at current cursor position in the defined scope,
if any. If a scope is defined but the currently edited resource is not part of the range of determined resources, a
warning dialog box is displayed that allows you to define another search scope.
Search References in - Searches all references of the item found at current cursor position in the file or files that
you specify when a scope is defined.
Search Declarations - Searches all declarations of the item found at current cursor position in the defined scope,
if any. If a scope is defined but the current edited resource is not part of the range of resources determined by this
scope, a warning dialog box is displayed that allows you to define another search scope.
Search Declarations in - Searches all declarations of the item found at current cursor position in the file or files
that you specify when a scope is defined.
Search Occurrences in File - Searches all occurrences of the item at the cursor position in the currently edited file.
The following action is available from the contextual menu and the Document > Schema menu:
Show Definition - Moves the cursor to the location of the definition of the current item.
Note: You can also use the Ctrl Single-Click (Command Single-Click on OS X) shortcut on a reference
to display its definition.
Extract template - Extracts the selected XSLT instructions sequence into a new template. Opens a dialog box
that allows you to specify the name of the new template to be created. The possible changes to perform on the
document can be previewed before altering the document. After pressing OK, the template is created and the selection
is replaced with a <xsl:call-template> instruction referencing the newly created template.
Note: This action is available only when the selection contains well-formed elements.
Note: The newly created template is indented and its name is highlighted in the <xsl:call-template>
element.
Move to another stylesheet - Allows you to move one or more XSLT global components (templates, functions,
or parameters) to another stylesheet. Active only when these entire components are selected. Follow these steps:
1. Choose whether you want to move the selected components to a new stylesheet or an existing one.
Include - The current stylesheet will use an xsl:include instruction to reference the destination stylesheet.
Import - The current stylesheet will use an xsl:import instruction to reference the destination stylesheet.
None - There will be created no relation between the current and destination stylesheets.
3. Press the Move button to move the components to the destination stylesheet. The moved components are
highlighted in the destination stylesheet.
Convert attributes to xsl:attributes - Converts the attributes from the selected element and represents each of them
with an <xsl:attribute> instruction. For example, from the following element:
<person id="Big{test}Boss"/>
you obtain:
<person>
<xsl:attribute name="id">
<xsl:text>Big</xsl:text>
<xsl:value-of select="test"/>
<xsl:text>Boss</xsl:text>
</xsl:attribute>
</person>
Convert xsl:if into xsl:choose/xsl:when - Converts an xsl:if block to an xsl:when block surrounded by an
xsl:choose element. For example, the following block:
<xsl:if test="a">
<!-- XSLT code -->
</xsl:if>
is converted to:
<xsl:choose>
<xsl:when test="a">
<!-- XSLT code -->
</xsl:when>
<xsl:otherwise>
|
</xsl:otherwise>
</xsl:choose>
Extract local variable - Allows you to create a new local variable by extracting the selected XPath expression. After
creating the new local variable before the current element, Oxygen XML Editor allows you to edit in-place the
variable's name.
Note: The action is active on a selection made inside an attribute that contains an XPath expression.
Extract global variable - Allows you to create a new global variable by extracting the selected XPath expression.
After creating the new global variable, Oxygen XML Editor allows you to edit in-place the variable's name.
Note: The action is active on a selection made inside an attribute that contains an XPath expression.
Note: Oxygen XML Editor checks if the selected expression depends on local variables or parameters that
are not available in the global context where the new variable is created.
Extract template parameter - Allows you to create a new template parameter by extracting the selected XPath
expression. After creating the new parameter, Oxygen XML Editor allows you to edit in-place its name.
Note: The action is active on a selection made inside an attribute that contains an XPath expression.
Rename Component - Allows you to rename the current component in-place. The component and all its references
in the document are highlighted with a thin border and the changes you make to the component at the cursor position
are updated in real time to all occurrences of the component. To exit in-place editing, press the Esc or Enter key on
your keyboard.
Rename Component in - Opens the Rename component_type dialog box that allows you to rename the selected
component by specifying the new component name and the files to be affected by the modification. If you click the
Preview button, you can view the files affected by the Rename Component action.
New name - Presents the current name of the edited resource and allows you to modify it.
Update references - Enable this option to update the references to the resource you are renaming.
Destination - Presents the path to the current location of the resource you want to move and gives you the option to
introduce a new location.
New name - Presents the current name of the moved resource and gives you the option to change it.
Update references of the moved resource(s) - Enable this option to update the references to the resource you are
moving, in accordance with the new location and name.
If the Update references of the moved resource(s) option is enabled, a Preview option (which opens the Preview
dialog box) is available for both actions. The Preview dialog box presents a list with the resources that are updated.
Actions available on a selection made inside an attribute that contains an XPath expression:
Extract template - Extracts the selected XSLT instructions sequence into a new template.
Move to another stylesheet - Allows you to move one or more XSLT global components (templates, functions,
or parameters) to another stylesheet.
Extract local variable - Allows you to create a new local variable by extracting the selected XPath expression.
Extract global variable - Allows you to create a new global variable by extracting the selected XPath expression.
Extract template parameter - Allows you to create a new template parameter by extracting the selected XPath
expression.
Extract global parameter - Allows you to create a new global parameter by extracting the selected XPath
expression.
actions available when the cursor is positioned over the name of a component:
Rename Component in
Renames the component and all its dependencies.
Search Declarations
Searches the declaration of the component in a predefined scope. It is available only when the context represents a
component name reference.
When hovering over the error or warning, the proposals are presented in a tooltip popup window.
If you place the cursor in the highlighted area where a validation error or warning occurs, a quick fix icon ( ) is
displayed in the stripe on the left side of the editor. If you click this icon, Oxygen XML Editor displays the list of
available fixes.
With the cursor placed in the highlighted area of the error or warning, you can also invoke the quick fix menu by
pressing Alt 1 (Meta Alt 1 on OS X) on your keyboard.
Note: The quick fixes are available only when validating an XSLT file with Saxon HE/PE/EE.
Template does not exist, when the template name referenced in a call-template element does not exist. The
following fixes are available:
Variable/Parameter not declared, when a parameter or variable reference cannot be found. The following fixes
are available:
Create parameter "paramName" in the template "templateName" - creates a new parameter with the
specified name in the referenced template.
Change "paramName" parameter reference to "newParamName" - changes the parameter reference from
the call-template element to a parameter that is declared in the called template.
Remove parameter "paramName" from call-template - removes the parameter with the specified name from
the call-template element.
No value supplied for required parameter, when a required parameter from a template is not referenced in a
call-template element. The following quick-fix is available::
Create global variable "varName" - creates a global variable with the specified name in the current stylesheet.
The new variable is added at the beginning of the stylesheet after the last global variable or parameter declaration.
Create global parameter "paramName" - creates a global parameter with the specified name in the current
stylesheet. The new parameter is added at the beginning of the stylesheet after the last global parameter or variable
declaration.
Create local variable "varName" - creates a local variable with the specified name before the current element.
Create template parameter "paramName" - creates a new parameter with the specified name in the current
template. This fix is available if the error is located inside a template.
Create function parameter "paramName" - creates a new parameter with the specified name in the current
function. This fix is available if the error is located inside a function.
Change reference to "varName" - changes the name of the referenced variable/parameter to an existing local
or global variable/parameter, that has a similar name with the current one.
Parameter from a called template is not declared, when a parameter referenced from a call-template element
is not declared. The following fixes are available:
Create template "templateName" - creates a template and generates its corresponding parameters. The template
name and parameter names and types are collected from the call-template element.
Change reference to "newTemplateName" - changes the name of the missing template referenced in the
call-template element. The proposed new names are the existing templates with names similar with the
missing one.
Add parameter "paramName" in call-template - creates a new parameter with the specified name in
call-template element.
Function "prefix:functionName()" has not been defined, when a function declaration is not found. The following
quick fixes are available:
Attribute-set "attrSetName" does not exist, when the referenced attribute set does not exist. The following quick
fixes are available:
Create attribute-set "attrSetName" - creates a new attribute set with the specified name, after the current top
level element from stylesheet.
Change reference to "attrSetName" - changes the referenced attribute set to an already defined one.
Character-map "chacterMap" has not been defined, when the referenced character map declaration is not found.
The following quick fixes are available:
Create character-map "characterMapName" - creates a new character map with the specified name, after the
current top level element from stylesheet.
Change reference to "characterMapName" - changes the referenced character map to an already defined one.
Based on an external file, or on a part of an external file extracted with an XPath expression.
<x:scenario label="when processing a para element">
<x:context href="source/test.xml" select="/doc/body/p[1]" />
...
</x:scenario>
Test a function.
<x:scenario label="when capitalising a string">
<x:call function="eg:capital-case">
<x:param select="'an example string'" />
<x:param select="true()" />
</x:call>
...
</x:scenario>
You are able to reference test files between each other, which allows you to define a suite of tests. For further details
about test scenarios, go to https://github.com/expath/xspec/wiki/Writing-Scenarios.
Tip: To make a custom task available in the Ant validation engine, add a JAR file that contains the task
implementation to the library directory of the built-in Ant distribution that comes bundled with Oxygen XML
Editor (for example, [OXYGEN INSTALLATION DIRECTORY]/tools/ant/lib folder).
Create a Validation Scenario for Ant Build Files
If you want to customize the validation process for Ant build files, you can create a new validation scenario (or configure
an existing one). For example, if you want to validate interrelated modules that define a complex Ant build file, you can
specify the main Ant file by configuring a validation scenario. To create or configure a validation scenario, select
Configure Validation Scenario(s) from the
menu.
Syntax Highlight
To change the syntax highlighting colors for Ant build files, open the Preferences dialog box and go to Editor > Syntax
Highlight.
Element names
Attribute names
Property names
Note: In addition to the user-defined properties, the Content Completion Assistant offers the following
values:
Target names
Task and type reference IDs
Tip: To make a custom task available in the Content Completion Assistant, add a JAR file that contains
the task implementation to the library directory of the built-in Ant distribution that comes bundled with
Oxygen XML Editor (for example, [OXYGEN INSTALLATION DIRECTORY]/tools/ant/lib
folder).
Note: For Ant resources, the proposals are collected starting from the master files. The master files can be
defined in the project or in the associated validation scenario. For further details about the Master Files support
go to Defining Master Files at Project Level.
Show XML structure option is selected, the following actions are available:
Show components
Switches the Outline view to the components display mode.
Flat presentation mode of the filtered results
When active, the application flattens the filtered result elements to a single level.
Show comments and processing instructions
Show/hide comments and processing instructions in the Outline view.
Show element name
Show/hide element name.
Settings menu:
Append Child
Displays a list of elements that can be inserted as children of the current element.
Insert Before
Displays a list of elements that can be inserted as siblings of the current element, before the current element.
Insert After
Displays a list of elements that can be inserted as siblings of the current element, after the current element.
Edit Attributes
Displays an in-place attribute editing window.
Toggle Comment
Comments/uncomments the currently selected element.
Search References Ctrl Shift R (Meta Shift R on OS X)
Searches all references of the item found at current cursor position in the defined scope. See Find References and
Declarations of Ant Components for more details.
Search References in
Searches all references of the item found at current cursor position in the specified scope. See Find References and
Declarations of Ant Components for more details.
Component Dependencies
Allows you to see the dependencies for the current selected component. See Ant Component Dependencies View
for more details.
Rename Component in
Renames the selected component. See Ant Refactoring Actions for more details.
Cut,
Copy,
Delete
Executes the typical editing actions on the currently selected component.
Expand More
Expands recursively all sub-components of the selected component.
Collapse All
Collapses recursively all sub-components of the selected component.
You can search a component in the Outline view by typing its name in the filter text field at the top of the view or
directly on the tree structure. When you type the component name in the text field, you can switch to the tree structure
using the following:
* - any string
? - any character
, - patterns separator
If no wildcards are specified, the string to search is used as a partial match (such as *textToFind*).
The content of the Outline view and the editing area are synchronized. When you select a component in the Outline
view, its definition is highlighted in the editing area.
Oxygen XML Editor has a predefined order for the groups in the Outline view:
For location, the names of the files are sorted alphabetically. The main file is the one you are editing and it is located
at the top of the list.
For type, the order is: properties, targets, references.
Note: When no grouping is available Oxygen XML Editor sorts the components depending on their order
in the document. Oxygen XML Editor also takes into account the name of the file that the components are
part of.
Search References - Searches all references of the item found at current cursor position in the defined scope.
Search References in - Searches all references of the item found at current cursor position in the file or files that
you specify after selecting a scope for the search operation.
Search Declarations - Searches all declarations of the item found at current cursor position in the defined scope.
Search Declarations in - Searches all declarations of the item found at current cursor position in the file or files
that you specify when defining a new scope.
Search Occurrences in File - Searches all occurrences of the item at the cursor position in the currently edited file.
The following action is available from the contextual menu and the Document > Schema menu:
Show Definition - Moves the cursor to the location of the definition of the current item.
Note: You can also use the Ctrl Single-Click (Command Single-Click on OS X) shortcut on a reference
to display its definition.
Rename Component - Allows you to rename the current component in-place. The component and all its references
in the document are highlighted with a thin border and the changes you make to the component at the cursor position
are updated in real time to all occurrences of the component. To exit in-place editing, press the Esc or Enter key on
your keyboard.
Rename Component in - Opens the Rename component_type dialog box that allows you to rename the selected
component by specifying the new component name and the files to be affected by the modification. If you click the
Preview button, you can view the files affected by the Rename Component action.
When hovering over the error or warning, the proposals are presented in a tooltip popup window.
If you place the cursor in the highlighted area where a validation error or warning occurs, a quick fix icon ( ) is
displayed in the stripe on the left side of the editor. If you click this icon, Oxygen XML Editor displays the list of
available fixes.
With the cursor placed in the highlighted area of the error or warning, you can also invoke the quick fix menu by
pressing Alt 1 (Meta Alt 1 on OS X) on your keyboard.
Oxygen XML Editor provides the following types of quick fixes for Ant build files:
Create new target - Creates a new target with the specified name.
Change reference to "targetName" - Corrects the reference to point to an already defined target.
Remove target reference - Removes the erroneous reference.
Visual clues about the operation type are indicated by the mouse pointer shape:
Remove button.
Annotations are rendered by default under the graphical representation of the component. When you have a reference
to a component with annotations, these annotations are presented in the diagram also below the reference component.
The Edit Annotations action invoked from the contextual menu edit the annotations for the reference. If the reference
component does not have annotations, you can edit the annotations of the referenced component by double-clicking
the annotations area. Otherwise you can edit the referenced component annotations only if you go to the definition
of the component.
Note: For imported/included components which do not belong to the currently edited schema, the Edit
Annotations dialog box presents the annotation as read-only. To edit its annotation, open the schema where
the component is defined.
Extract Global Element
Action that is available for local elements. A local element is made global and is replaced with a reference to the
global element. The local element properties that are also valid for the global element declaration are kept.
Rename Component in
Rename the selected component.
Cut Ctrl X (Meta X on OS X)
Cut the selected component(s).
Copy Ctrl C (Meta C on OS X)
Copy the selected component(s).
Copy XPath
This action copies an XPath expression that identifies the selected element or attribute in an instance XML document
of the edited schema and places it in the clipboard.
Paste Ctrl V (Meta V on OS X)
Paste the component(s) from the clipboard as children of the selected component.
Paste as Reference
Create references to the copied component(s). If not possible a warning message is displayed.
Remove (Delete)
Remove the selected component(s).
Override component
Copies the overridden component in the current XML Schema. This option is available for xs:override components.
Redefine component
The referenced component is added in the current XML Schema. This option is available for xs:redefine components.
Optional
Can be performed on element/attribute/group references, local attributes, elements, compositors, and element
wildcards. The minOccurs property is set to 0 and the use property for attributes is set to optional.
Unbounded
Can be performed on element/attribute/group references, local attributes, elements, compositors, and element
wildcards. The maxOccurs property is set to unbounded and the use property for attributes is set to required.
Search
Can be performed on local elements or attributes. This action makes a reference to a global element or attribute.
Search References
Searches all references of the item found at current cursor position in the defined scope if any.
A thick line to identify a connection with a required component (in the following image, family is a required
element).
A thin line to identify a connection with an optional component (in the following image, email is an optional
element).
The following topics explain in detail all available components and their symbols as they appear in an XML schema
diagram.
Defines the root element of a schema. A schema document contains representations for a collection of schema components,
such as type definitions and element declarations, that have a common target namespace. See more info at
http://www.w3.org/TR/xmlschema11-1/#element-schema.
By default, it displays the targetNamespace property when rendered.
xs:schema properties
Property Name
Description
Possible Values
Target Namespace
Any URI
Block Default
Final Default
Default Attributes
Version
Schema version
Any token.
ID
The schema id
Any ID.
Component
SystemID
xs:element
Defines an element. An element declaration is an association of a name with a type definition, either simple or complex,
an (optional) default value and a (possibly empty) set of identity-constraint definitions. See more info at
http://www.w3.org/TR/xmlschema11-1/#element-element.
An element by default displays the following properties when rendered in the diagram: default, fixed, abstract and type.
When referenced or declared locally, the element graphical representation also contains the value for the minOccurs
and maxOccurs properties (for 0..1 and 1..1 occurs the values are implied by the connector style) and the connectors to
the element are drawn using dotted lines if the element is optional.
Description
Possible Values
Mentions
Name
The element name. Always Any NCName for global or If missing, will be displayed
required.
local elements, any QName as '[element]' in diagram.
for element references.
Is Reference
Type
Base Type
The extended/restricted base All declared or built-in types For elements with complex
type.
type, with simple or complex
content.
Mixed
Content
Content Mixed
Default
Fixed
Min Occurs
Minimum number of
A numeric positive value.
occurrences of the element. Default value is 1
Max Occurs
Maximum number of
A numeric positive value.
occurrences of the element. Default value is 1
Description
Possible Values
Substitution Group
Abstract
Form
Nillable
Target Namespace
Block
unqualified/qualified
#all, restriction,
extension,substitution,
extension restriction,
extension substitution,
restriction substitution,
restriction extension
substitution
Mentions
Description
Possible Values
Final
ID
Component
Namespace
System ID
Any id
Mentions
xs:attribute
Description
Possible Value
Mentions
Name
Is Reference
Type
Default
Any string
Description
Possible Value
fixed attributes are mutually
exclusive.
Mentions
Fixed
Use
Form
Inheritable
true/false
Target Namespace
ID
Component
Namespace
System ID
Any id
xs:attributeGroup
Defines an attribute group to be used in complex type definitions. See more info at
http://www.w3.org/TR/xmlschema11-1/#element-attributeGroup.
Description
Possible Values
Mentions
Name
ID
Any id
Component
Namespace
System ID
xs:complexType
Defines a top level complex type. Complex Type Definitions provide for: See more data at
http://www.w3.org/TR/xmlschema11-1/#element-complexType.
Constraining element information items by providing Attribute Declarations governing the appearance and content
of attributes.
Constraining element information item children to be empty, or to conform to a specified element-only or mixed
content model, or else constraining the character information item children to conform to a specified simple type
definition.
Using the mechanisms of Type Definition Hierarchy to derive a complex type from another simple or complex type.
Specifying post-schema-validation infoset contributions for elements.
Limiting the ability to derive additional types from a given complex type.
Controlling the permission to substitute, in an instance, elements of a derived type for elements declared in a content
model to be of a given complex type.
Tip: A complex type which is a base type to another type will be rendered with yellow background.
xs:complexType properties
Property Name
Description
Possible Values
Mentions
Name
Any NCName
Derivation Method
restriction/ extension
Content
Content Mixed
Mixed
Description
Possible Values
Abstract
true/false
When set to true, this
complex type cannot be used
directly in the instance
documents and needs to be
substituted using an
xsi:type attribute.
Block
Controls whether a
all, extension, restriction,
substitution (either through extension restriction,
a xsi:type or substitution [Empty]
groups) can be performed for
a complex type, which is an
extension or a restriction of
the current complex type.
This attribute can only block
such substitutions (it cannot
"unblock" them), which can
also be blocked in the
element definition. The
default value is defined by
the blockDefault
attribute of xs:schema.
Final
ID
Component
Namespace
System ID
Any id
Mentions
xs:simpleType
Defines a simple type. A simple type definition is a set of constraints on strings and information about the values they
encode, applicable to the normalized value of an attribute information item or of an element information item with no
Description
Possible Values
Scope
Name
Any NCName.
Derivation
restriction,list or union
Base Type
Item Type
Member Types
Member
Description
Possible Values
Scope
datatype local definitions in
the xs:union element. Both
styles can be mixed.
Final
ID
Any id.
Component
Namespace
System ID
xs:alternative
The type alternatives mechanism allows you to specify type substitutions on an element declaration.
Note: xs:alternative is available for XML Schema 1.1.
xs:alternative properties
Name
Description
Possible Values
Type
Test
ID
Any ID.
Component
Description
Possible Values
System ID
xs:group
Defines a group of elements to be used in complex type definitions. See more info at
http://www.w3.org/TR/xmlschema11-1/#element-group.
When referenced, the graphical representation also contains the value for the minOccurs and maxOccurs properties (for
0..1 and 1..1 occurs the values are implied by the connector style) and the connectors to the group are drawn using dotted
lines if the group is optional.
xs:group properties
Property Name
Description
Possible Values
Mentions
Name
Min Occurs
Minimum number of
occurrences of the group.
Max Occurs
Maximum number of
occurrences of the group.
ID
Any id
Component
Namespace
System ID
xs:include
Adds multiple schemas with the same target namespace to a document. See more info at
http://www.w3.org/TR/xmlschema11-1/#element-include.
xs:include properties
Property Name
Description
Possible Values
Schema Location
Any URI
ID
Include ID.
Any ID
Component
xs:import
Adds multiple schemas with different target namespace to a document. See more info at
http://www.w3.org/TR/xmlschema11-1/#element-import.
xs:import properties
Description
Possible Values
Schema Location
Any URI
Namespace
Any URI
ID
Import ID
Any ID
Component
xs:redefine
Redefines simple and complex types, groups, and attribute groups from an external schema. See more info at
http://www.w3.org/TR/xmlschema11-1/#element-redefine.
xs:redefine properties
Property Name
Description
Possible Values
Schema Location
Any URI
ID
Redefine ID
Any ID
Component
xs:override
The override construct allows replacements of old components with new ones without any constraint. See more info at
http://www.w3.org/TR/xmlschema11-1/#element-override.
xs:override properties
Property Name
Description
Possible Values
Schema Location
Any URI
ID
Redefine ID
Any ID
xs:notation
Describes the format of non-XML data within an XML document. See more info at
http://www.w3.org/TR/xmlschema11-1/#element-notation.
xs:notation properties
Property Name
Description
Possible values
Mentions
Name
System Identifier
Any URI
Public Identifier
A Public ID value
ID
Any ID
Component
Description
Possible values
Namespace
System ID
Mentions
Description
Possible Values
Mentions
Compositor
Compositor type.
Min Occurs
Minimum occurrences of
compositor.
Max Occurs
Maximum occurrences of
compositor.
ID
Any ID
Component
System ID
xs:any
Enables the author to extend the XML document with elements not specified by the schema. See more info at
http://www.w3.org/TR/xmlschema11-1/#element-any.
Description
Possible Values
Namespace
notNamespace
notQName
##defined
Process Contents
Min Occurs
Max Occurs
ID
Any ID.
Component
System ID
xs:anyAttribute
Enables the author to extend the XML document with attributes not specified by the schema. See more info at
http://www.w3.org/TR/xmlschema11-1/#element-anyAttribute.
xs:anyAttribute properties
Property Name
Description
Possible Value
Namespace
Process Contents
ID
Any ID.
Description
Possible Value
Component
System ID
xs:unique
Defines that an element or an attribute value must be unique within the scope. See more info at
http://www.w3.org/TR/xmlschema11-1/#element-unique.
xs:unique properties
Property Name
Description
Possible Values
Name
Any NCName.
ID
Any ID.
Component
Namespace
System ID
xs:key
Specifies an attribute or element value as a key (unique, non-nullable and always present) within the containing element
in an instance document. See more info at http://www.w3.org/TR/xmlschema11-1/#element-key.
xs:key properties
Property Name
Description
Possible Value
Name
Any NCName.
ID
Any ID.
Component
Namespace
System ID
Specifies that an attribute or element value corresponds to that of the specified key or unique element. See more info at
http://www.w3.org/TR/xmlschema11-1/#element-keyref.
A keyref by default displays the Referenced Key property when rendered.
xs:keyRef properties
Property Name
Description
Possible Values
Name
Any NCName.
Referenced Key
ID
Any ID.
Component
Namespace
System ID
xs:selector
Specifies an XPath expression that selects a set of elements for an identity constraint. See more info at
http://www.w3.org/TR/xmlschema11-1/#element-selector.
xs:selector properties
Property Name
Description
Possible Values
XPath
ID
Any ID.
Component
System ID
xs:field
Specifies an XPath expression that specifies the value used to define an identity constraint. See more info at
http://www.w3.org/TR/xmlschema11-1/#element-field.
xs:field properties
Property Name
Description
Possible Values
XPath
Description
Possible Values
ID
Any ID.
Component
System ID
xs:assert
Assertions provide a flexible way to control the occurrence and values of elements and attributes available in an XML
Schema.
Note: xs:assert is available for XML Schema 1.1.
xs:assert properties
Property Name
Description
Possible Values
Test
ID
Any ID.
Component
System ID
xs:openContent
The openContent element enables instance documents to contain extension elements interleaved among the elements
declared by the schema. You can declare open content for your elements at one place - within the complexType definition,
or at the schema level.
For further details about the openContent component, go to
http://www.w3.org/TR/xmlschema11-1/#element-openContent.
xs:openContent properties
Property Name
Description
Possible Value
Mode
Specifies where the extension elements The value can be: "interleave", "suffix"
can be inserted.
or "none". The default value is
"interleave".
ID
Any ID.
Component
Description
Possible Value
System ID
Note: This component is available for XML Schema 1.1 only. To change the version of the XML Schema,
open the Preferences dialog box and go to XML > XML Parser > XML Schema.
Constructs Used to Group Schema Components
This section explains the components that can be used for grouping other schema components:
Attributes
Constraints
Substitutions
Attributes
Description
Possible Values
Component
System ID
Constraints
Description
Possible Values
Component
System ID
Description
Possible Values
Component
System ID
Schema Validation
Validation for the Design mode is seamlessly integrated in the Oxygen XML Editor XML documents validation capability.
Prefixes - The dialog box displays a table with namespaces and the mapped prefixes. You can add a new prefix
mapping or remove an already existing one.
Automatically, after a configurable delay from the last key press of the < character. You can adjust the delay from
the Content Completion preferences page.
On demand, by pressing Ctrl Space (Command Space on OS X) on a partial element or attribute name.
Note: If the Content Completion list contains only one valid proposal, when you press the Ctrl Space
(Command Space on OS X) shortcut key, the proposal is automatically inserted.
Note: You can also start the Content Completion Assistant from Document > Content Completion >
Start Content Completion.
Press Enter or Tab key on your keyboard to insert both the start and end tags. The cursor is positioned inside the
start tag, in a position suitable for inserting attributes.
Press Ctrl Enter (Meta Enter on OS X) on your keyboard. Oxygen XML Editor inserts both the start and end tags
and positions the cursor between the tags, so you can start typing content.
Depending on the selected schema version, Oxygen XML Editor populates the proposals list with information taken
either from XML Schema 1.0 or 1.1.
Oxygen XML Editor helps you to easily reference a component by providing the list of proposals (complex types, simple
types, elements, attributes, groups, attribute groups, or notations) valid in the current context. The components are
collected from the current file or from the imported/included schemas.
When editing xs:annotation/xs:appinfo elements of an XML Schema, the Content Completion Assistant
proposes elements and attributes from a custom schema (by default ISO Schematron). This feature can be configured
from the XSD Content Completion preferences page.
References to XML Schema Specification
The same as in editing XML documents, the message of an error obtained by validation of an XML Schema document
includes a reference to the W3C specification for XML Schema. An error message contains an Info field that will open
the browser on the "XML Schema Part 1:Structures" specification at exactly the point where the error is described thus
allowing you to understand the reason for that error.
Search References - Searches all references of the item found at current cursor position in the defined scope,
if any. If a scope is defined, but the current edited resource is not part of the range of resources determined by this,
a warning dialog box is displayed and you have the possibility to define another search scope.
Search References in - Searches all references of the item found at current cursor position in the file or files that
you specify when define a scope in the Search References dialog box.
Search Declarations - Searches all declarations of the item found at current cursor position in the defined scope
if any. If a scope is defined, but the current edited resource is not part of the range of resources determined by this,
a warning dialog box will be displayed and you have the possibility to define another search scope.
Search Declarations in - Searches all declarations of the item found at current cursor position in the file or files
that you specify when you define a scope for the search operation.
Search Occurrences in File - Searches all occurrences of the item at the cursor position in the currently edited
file.
The following action is available from the contextual menu and the Document > Schema menu:
Show Definition - Moves the cursor to the definition of the referenced XML Schema item.
Refactoring Actions
The following refactoring actions can be applied on attribute, attributeGroup, element, group, key,
unique, keyref, notation, simple, or complex types and are available from the Refactoring submenu in the
contextual menu of the current editor or from the Document > Refactoring menu:
Rename Component - Allows you to rename the current component in-place. The component and all its references
in the document are highlighted with a thin border and the changes you make to the component at the cursor position
are updated in real time to all occurrences of the component. To exit in-place editing, press the Esc or Enter key on
your keyboard.
Rename Component in - Opens the Rename component_type dialog box that allows you to rename the selected
component by specifying the new component name and the files to be affected by the modification. If you click the
Preview button, you can view the files affected by the Rename Component action.
* - any string
? - any character
, - patterns separator
If no wildcards are specified, the string to search will be searched as a partial match (like *textToFind*).
The content of the Outline view and the editing area are synchronized. When you select a component in the Outline
view, its definition is highlighted in the editing area.
The action is available for all named components (for example elements or attributes).
When you select the Move action from the contextual menu of the Resource/Hierarchy Dependencies view, the Move
resource dialog box is displayed. The following fields are available:
Destination - Presents the path to the current location of the resource you want to move and gives you the option to
introduce a new location.
New name - Presents the current name of the moved resource and gives you the option to change it.
Update references of the moved resource(s) - Enable this option to update the references to the resource you are
moving, in accordance with the new location and name.
If the Update references of the moved resource(s) option is enabled, a Preview option (which opens the Preview
dialog box) is available for both actions. The Preview dialog box presents a list with the resources that are updated.
Schema
Options
Advanced
URL - Schema location as an URL. A history of the last used URLs is available in the drop-down box.
Namespace - Displays the namespace of the selected schema.
Document root - After the schema is selected, this drop-down box is populated with all root candidates gathered
from the schema. Choose the root of the output XML documents.
Output folder - Path to the folder where the generated XML instances will be saved.
Filename prefix and Extension - Generated file names have the following format: prefixN.extension, where
N represents an incremental number from 0 up to Number of instances - 1.
Number of instances - The number of XML files to be generated.
Open first instance in editor - When checked, the first generated XML file is opened in editor.
Namespaces - Here you can specify the default namespace as well as the proxies (prefixes) for namespaces.
Load settings / Export settings - The current settings can be saved for further usage with the Export settings button,
and reloaded when necessary with the Load settings button.
Namespace / Element table - Allows you to set a namespace for each element name that appears in an XML
document instance. The following prefix-to-namespace associations are available:
All elements from all namespaces (<ANY> - <ANY>). This is the default setting and can be customized from
the XML Instances Generator preferences page.
All elements from a specific namespace.
A specific element from a specific namespace.
Settings
Generate optional elements - When checked, all elements are generated, including the optional ones (having
the minOccurs attribute set to 0 in the schema).
Preferred number of repetitions - Allows you to set the preferred number of repeating elements related with
minOccurs and maxOccurs facets defined in XML Schema.
Maximum recursion level - If a recursion is found, this option controls the maximum allowed depth of the same
element.
Choice strategy - Option used for xs:choice or substitutionGroup elements. The possible strategies
are:
If the value set here is between minOccurs and maxOccurs, then that value is used.
If the value set here is less than minOccurs, then the minOccurs value is used.
If the value set here is greater than maxOccurs, then maxOccurs is used.
First - The first branch of xs:choice or the head element of substitutionGroup is always used.
Random - A random branch of xs:choice or a substitute element or the head element of a
substitutionGroup is used.
Generate the other options as comments - Option to generate the other possible choices or substitutions (for
xs:choice and substitutionGroup). These alternatives are generated inside comments groups so you
can uncomment and use them later. Use this option with care (for example on a restricted namespace and element)
as it may generate large result files.
Load settings / Export settings - The current settings can be saved for further usage with the Export settings
button, and reloaded when necessary with the Load settings button.
Element values - The Element values tab allows you to add values that are used to generate the elements content.
If there are more than one value, then the values are used in a random order.
Attribute values - The Attribute values tab allows you to add values that are used to generate the attributes content.
If there are more than one value, then the values are used in a random order.
Use incremental attribute / element names as default - If checked, the value of an element or attribute starts with
the name of that element or attribute. For example, for an a element the generated values are: a1, a2, a3, and so
on. If not checked, the value is the name of the type of that element / attribute (for example: string, decimal,
etc.)
Maximum length - The maximum length of string values generated for elements and attributes.
Discard optional elements after nested level - The optional elements that exceed the specified nested level are
discarded. This option is useful for limiting deeply nested element definitions that can quickly result in very large
XML documents.
Running the Generate Sample XML Files Action from Command Line
The Generate Sample XML Files tool can be also used from command line by running the script called
xmlGenerator.bat (on Windows) / xmlGenerator.sh (on Mac OS X / Unix / Linux) located in the Oxygen
XML Editor installation folder. The parameters can be set once in the dialog box, exported to an XML file on disk with
the button Export settings and reused from command line. With the exported settings file you can generate the same
XML instances from the command line as from the dialog box:
xmlGenerator.bat path_of_CFG_file
The script can be integrated in an external batch process launched from the command line. The command line parameter
of the script is the relative path to the exported XML settings file. The files specified with relative paths in the exported
XML settings will be made absolute relative to the folder where the script is run.
The following example shows such an XML configuration file:
XML Configuration File
<settings>
<schemaSystemId>http://www.w3.org/2001/XMLSchema.xsd</schemaSystemId>
<documentRoot>schema</documentRoot>
<outputFolder>D:\projects\output</outputFolder>
<filenamePrefix>instance</filenamePrefix>
<filenameExtension>xml</filenameExtension>
<noOfInstances>1</noOfInstances>
<openFirstInstance>true</openFirstInstance>
<defaultNamespace><NO_NAMESPACE></defaultNamespace>
<element namespace="<ANY>" name="<ANY>">
<generateOptionalElements>false</generateOptionalElements>
<generateOptionalAttributes>false</generateOptionalAttributes>
<valuesForContentType>DEFAULT</valuesForContentType>
<preferredNumberOfRepetitions>2</preferredNumberOfRepetitions>
<maximumRecursivityLevel>1</maximumRecursivityLevel>
<choicesAndSubstitutions strategy="RANDOM"
generateOthersAsComments="false"/>
<attribute namespace="<ANY>"
name="<ANY>">
<attributeValue>attrValue1</attributeValue>
<attributeValue>attrValue2</attributeValue>
</attribute>
</element>
<element namespace="<NO_NAMESPACE>"
name="<ANY>">
<generateOptionalElements>true</generateOptionalElements>
<generateOptionalAttributes>true</generateOptionalAttributes>
<valuesForContentType>DEFAULT</valuesForContentType>
Output file - You can specify the path of the output file by entering it in the text field, or by using the
Insert
Editor Variables button or the options in the
Browse drop-down menu.
Split output into multiple files - Instructs the application to split the output into multiple files. You can choose to
split them by namespace, location, or component name.
Open in Browser/System Application - Opens the result in the system application associated with the output file
type.
Note: To set the browser or system application that will be used, open the Preferences dialog box, then go
to Global and set it in the Default Internet browser field. This will take precedence over the default system
application settings.
Keep only the annotations with xml:lang set to - The generated output will contain only the annotations with the
xml:lang attribute set to the selected language. If you choose a primary language code (for example, en for
English), this includes all its possible variations (en-us, en-uk, etc.).
Figure 192: The Settings Tab of the XML Schema Documentation Dialog Box
The Settings tab allows you to choose whether or not to include the following components: Global elements, Global
attributes, Local elements, Local attributes, Simple Types, Complex Types, Groups, Attribute Groups, Redefines,
Referenced schemas, Include notations.
You can choose whether or not to include the following other details:
Diagram - Displays the diagram for each component. You can choose the image format (JPEG, PNG, GIF, SVG)
to use for the diagram section. The generated diagrams are dependent on the options from the Schema Design
Properties page.
Diagram annotations - This option controls whether the annotations of the components presented in the diagram
sections are included.
Include local elements and attributes - If checked, local elements and attributes are included in the documentation
index.
Include resource hierarchy - Specifies whether the resource hierarchy for an XML Schema documentation is
generated.
Export settings - Save the current settings in a settings file for further use (for example, with the exported settings file
you can generate the same documentation from the command line interface.)
Load settings - Reloads the settings from the exported file.
Generate - Use this button to generate the XML Schema documentation.
Output Formats for Generating XML Schema Documentation
XML Schema documentation can be generated in HTML, PDF, DocBook, or a custom format. You can choose the
format from the Schema Documentation dialog box. For the PDF and DocBook formats, the option to split the output
in multiple files is not available.
HTML Output Format
The XML Schema documentation generated in HTML format contains images corresponding to the same schema
definitions as the ones displayed by the schema diagram editor. These images are divided in clickable areas that are
linked to the definitions of the names of types or elements. The documentation of a definition includes a Used By section
with links to the other definitions that reference it. If the Escape XML Content option is unchecked, the HTML or
XHTML tags used inside the xs:documentation elements of the input XML Schema for formatting the documentation
text (for example <b>, <i>, <u>, <ul>, <li>, etc.) are rendered in the generated HTML documentation.
The generated images format is PNG. The image of an XML Schema component contains the graphical representation
of that component as it is rendered in the Schema Diagram panel of the Oxygen XML Editor XSD editor panel.
Note: The content that you insert here has to be wrapped in DocBook markup. For details about working
with DocBook see the following video demonstration:
http://www.oxygenxml.com/demo/DocBook_Editing_in_Author.html.
schemaDocumentation.bat on Windows.
schemaDocumentation.sh on OS X / Unix / Linux.
The script is located in the Oxygen XML Editor installation folder. The script can be integrated in an external batch
process launched from the command-line interface. The script accepts a variety command line arguments that allow you
to configure the documentation.
The accepted syntax and arguments are as follows:
schemaDocumentation schemaFile [ [-cfg:configFile] | [ [-out:outputFile]
[-format:<value>] [-xsl:<xslFile>] [-split:<value>] [-openInBrowser:<value>] ] |
--help | -help | --h | -h ]
schemaFile
The XML Schema file.
-xsl:<xslFile>
The XSL file to be applied on the intermediate XML format. If there is no XSL file provided, the result will be in
the HTML format.
-split:<value>
The split method used when generating the documentation. Splitting is recommended for large schemas. Possible
values are as follows:
-openInBrowser:<value>
Opens the result of the transformation in a browser or system application. Possible values are true or false
(default value).
--help | -help | --h | -h
Displays the available options.
Example of the script in a Windows command line:
schemaDocumentation example.xsd -out:schemaDocumentation.html -format:custom -xsl:example.xsl
-split:namespace
Flat schema - A flat structure that resembles a tree-like view of the database without references to elements.
Hierarchical schema - Display the table dependencies visually, in a type of tree view where dependent tables
are shown as indented child elements in the content model. Select this option if you want to configure the database
columns of the tables to be converted.
Open the flattened XML Schema file in editor - opens the main flattened schema in the editing area after the
operation completes
Use the XML Catalogs when collecting the referenced XML Schemas - enables resolving the imported and
included schemas through the available XML Catalogs;
Note: Changing this option triggers the recalculation of the dependencies graph for the main schema.
Process the imported XML Schemas resolved through the XML Catalogs - specifies whether the imported
schemas that were resolved through an XML Catalog are flattened
Flatten the imported XML Schema(s) - specifies whether the imported schemas are flattened.
Note: For the schemas skipped by the flatten operation, no files are created in the output folder and the
corresponding import statements remain unchanged.
To flatten a schema from the command line, use the following command:
flattenSchema.bat on Windows
sh flattenSchemaMac.sh on OS X
sh flattenSchema.sh on Unix/Linux
-verbose - provides information about the current flatten XML Schema operation
--help | -help | --h | -h - prints the available parameters for the operation
Command Line Example for Windows
flattenSchema.bat -in:http://www.w3.org/MarkUp/SCHEMA/xhtml11.xsd
-outDir:mySchemas/flattened/xhtml -flattenImports:true -useCatalogs:true
-flattenCatalogResolvedImports:true -verbose
Regular expressions editor - allows you to edit the regular expression to be tested and used. Content completion
is available and presents a list with all the predefined expressions. It is triggered by pressing Ctrl Space (Command
Space on OS X).
Error display area - if the edited regular expression is incorrect, an error message will be displayed here. The
message contains the description and the exact location of the error. Also, clicking the quick navigation button ( )
highlights the error inside the regular expression.
Category combo box - here you can choose from several categories of predefined expressions. The selected category
influences the displayed expressions in the Available expressions table.
Evaluate expression on each line - the edited expression will be applied on each line in the Test area.
Evaluate expression on all text - the edited expression will be applied on the whole text.
Test area - a text editor which allows you to enter a text sample on which the regular expression will be applied. All
matches of the edited regular expression will be highlighted.
After editing and testing your regular expression you can insert it in the current editor. The Insert button will become
active when an editor is opened in the background and there is an expression in the Regular expressions editor.
The regular expression builder cannot be used to insert regular expressions in the grid version or the schema version of
a document editor. Accordingly, the Insert button of the dialog box will be disabled if the current document is edited
in grid mode.
Note: Some regular expressions may block indefinitely the Java Regular Expressions engine. If the execution
of the regular expression does not end in about five seconds, the application displays a dialog box that allows
you to interrupt the operation.
XML Documents Validation and Content Completion Based on XML Schema 1.1.
XML Schema 1.1 Validation and Content Completion.
Editing XML Schema 1.1 files in the Schema Design mode.
The Flatten Schema action.
Resource Hierarchy/Dependencies and Refactoring Actions.
Master Files.
Generating Documentation for XML Schema 1.1.
Support for generating XML instances based on XML Schema.
Support for validating XML documents with an NVDL schema that contains an XML Schema 1.1 validation step.
Note: To enable XML Schema 1.1 validation in NVDL, you need to pass the following option to the
validation engine to specify the schema version:
http://www.thaiopensource.com/validate/xsd-version (the possible values are 1.0 or
1.1.
Note: To enable the full XPath expression in assertions and type alternatives, you need to set the
http://www.thaiopensource.com/validate/full-xpath option.
XML Schema 1.1 is a superset of XML Schema 1.0, that offers lots of new powerful capabilities.
Assertions - support to define assertions against the document content using XPath 2.0 expressions (an idea borrowed
from Schematron).
Conditional type assignment - the ability to select the type against which an element is validated based on the
values of the attribute of the element.
Open content - content models are able to use the openContent element to specify content models with open
content. These content models allow elements not explicitly mentioned in the content model to appear in the document
instance. It is as if wildcards were automatically inserted at appropriate points within the content model. A schema
document wide default may be set, which causes all content models to be open unless specified otherwise.
To see the complete list with changes since version 1.0, go to http://www.w3.org/TR/xmlschema11-1/#ch_specs.
XML Schema 1.1 is intended to be mostly compatible with XML Schema 1.0 and to have approximately the same scope.
It also addresses bug fixes and brings improvements that are consistent with the constraints on scope and compatibility.
Note: An XML document conforming to a 1.0 schema can be validated using a 1.1 validator, but an XML
document conforming to a 1.1 schema may not validate using a 1.0 validator.
If you are constrained to use XML Schema 1.0 (for example if you develop schemas for a server that uses an XML
Schema 1.0 validator which cannot be updated), change the default XML Schema version to 1.0. If you keep the default
XML Schema version set to 1.1, the content completion window presents XML Schema 1.1 elements that you can insert
accidentally in an 1.0 XML Schema. So even if you make a document invalid conforming with XML Schema 1.0, the
validation process does not signal any issues.
To change the default XML Schema version, open the Preferences dialog box and go to XML > XML Parser > XML
Schema.
To watch our video demonstration about the XML Schema 1.1 support, go to
http://oxygenxml.com/demo/XML_Schema_11.html.
1.0
minVersion = "1.1"
1.1
minVersion = "1.0" maxVerion = greater than "1.1" the XML Schema version defined in the XML Schema
preferences page.
Not set in the XML Schema document.
To change the XML Schema version of the current document, use the Change XML Schema version action from the
contextual menu. This is available both in the Text mode, and in the Design mode and opens the Change XML Schema
version dialog box. The following options are available:
XML Schema 1.0 - Inserts the minVersion and maxVersion attributes on the schema element and gives them
the values "1.0" and "1.1" respectively. Also, the namespace declaration
(xmlns:vc=http://www.w3.org/2007/XMLSchema-versioning) is inserted automatically if it does not exist.
XML Schema 1.1 - Inserts the minVersion attribute on the schema element and gives it the value "1.1". Also,
removes the maxVersion attribute if it exists and adds the versioning namespace
(xmlns:vc=http://www.w3.org/2007/XMLSchema-versioning) if it is not declared.
Default XML Schema version - Removes the minVersion and maxVersion attributes from the schema
element. The default schema version, defined in the XML Schema preferences page, is used.
Note: The Change XML Schema version action is also available in the informative panel presented at the top
of the edited XML Schema. If you close this panel, it will no longer appear until you restore Oxygen XML
Editor to its default options.
Oxygen XML Editor automatically uses the version set through the versioning attributes, or the default version if the
versioning attributes are not declared, when proposing content completion elements and validating an XML Schema.
Also, the XML instance validation against an XML Schema is aware of the versioning attributes defined in the XML
Schema.
When you generate sample XML files from an XML Schema, Oxygen XML Editor takes into account the minVersion
and maxVersion attributes defined in the XML Schema.
* - any string
? - any character
, - patterns separator
If no wildcards are specified, the string to search is used as a partial match (like *textToFind*).
Format and Indent action that is available in the Document > Source menu
Format and Indent action achieves this by performing the following steps:
Input - The full path to the XQuery file must be specified in one of the two fields in this section:
URLFile - The URL of the file in which you want to generate the documentation.
Folder - The directory that contains the files for which you want to generate the documentation. You can also
specify the XQuery file extensions to be searched for in the specified directory.
Default function namespace - Optional URI for the default namespace for the submitted XQuery.
Predefined function namespaces - Optional, engine-dependent, predefined namespaces that the submitted XQuery
refers to. They allow the conversion to generate annotation information to support the presentation component
hypertext linking (only if the predefined modules have been loaded into the local xqDoc XML repository).
Open in Browser/System Application - Select this option if you want the result to be opened in the system application
associated with that file type.
Note: To set the browser or system application that will be used, open the Preferences dialog box, then go
to Global and set it in the Default Internet browser field. This will take precedence over the default system
application settings.
Output - Allows you to specify where the generated documentation is saved on disk.
Show
Settings menu on the Outline view toolbar. The following actions are available:
Show XML structure option is selected, the following actions are available:
Show components
Switches the Outline view to the components display mode.
Flat presentation mode of the filtered results
When active, the application flattens the filtered result elements to a single level.
Show comments and processing instructions
Show/hide comments and processing instructions in the Outline view.
Show element name
Show/hide element name.
Show text
Show/hide additional text content for the displayed elements.
Show attributes
Show/hide attribute values for the displayed elements. The displayed attribute values can be changed from the
Outline preferences panel.
Configure displayed attributes
Displays the XML Structured Outline preferences page.
The following contextual menu actions are available in the Outline view when the
Settings menu:
Append Child
Displays a list of elements that you can insert as children of the current element.
Insert Before
Displays a list of elements that you can insert as siblings of the current element, before the current element.
Insert After
Displays a list of elements that you can insert as siblings of the current element, after the current element.
Edit Attributes
Opens a dialog box that allows you to edit the attributes of the currently selected component.
Toggle Comment
Comments/uncomments the currently selected element.
Search references
Searches for the references of the currently selected component.
Search references in
Searches for the references of the currently selected component in the context of a scope that you define.
Component dependencies
Displays the dependencies of the currently selected component.
Rename Component in
Renames the currently selected component in the context of a scope that you define.
Cut
Cuts the currently selected component.
Copy
Copies the currently selected component.
Delete
Deletes the currently selected component.
Expand More
Expands the structure of a component in the Outline view.
Collapse All
Collapses the structure of all the component in the Outline view.
To switch from the tree structure to the text filter, use Tab and Shift-Tab.
Tip: The search filter is case insensitive. The following wildcards are accepted:
* - any string
? - any character
, - patterns separator
If no wildcards are specified, the string to search is used as a partial match (like *textToFind*).
The content of the Outline view and the editing area are synchronized. When you select a component in the Outline
view, its definition is highlighted in the editing area.
To watch our video demonstration about editing WSDL documents in the master files context, go to
http://oxygenxml.com/demo/WSDL_Working_Modules.html.
Search References - Searches all references of the item found at current cursor position in the defined scope,
if any. If a scope is defined, but the current edited resource is not part of the range of resources determined by this,
a warning dialog box is displayed and you have the possibility to define another search scope.
Search References in - Searches all references of the item found at current cursor position in the file or files that
you specify when define a scope in the Search References dialog box.
Search Declarations - Searches all declarations of the item found at current cursor position in the defined scope
if any. If a scope is defined, but the current edited resource is not part of the range of resources determined by this,
a warning dialog box will be displayed and you have the possibility to define another search scope.
Search Declarations in - Searches all declarations of the item found at current cursor position in the file or files
that you specify when you define a scope for the search operation.
Search Occurrences in File - Searches all occurrences of the item at the cursor position in the currently edited
file.
The following action is available from the Document > Schema menu:
Show Definition - Takes you to the location of the definition of the current item.
Note: You can also use the Ctrl Single-Click (Command Single-Click on OS X) shortcut on a reference
to display its definition.
Refactoring Actions
The following refactoring actions are available from the Refactoring submenu from the Document > Refactoring menu
or in the contextual menu of the current editor:
Rename Component - Allows you to rename the current component in-place. The component and all its references
in the document are highlighted with a thin border and the changes you make to the component at the cursor position
are updated in real time to all occurrences of the component. To exit in-place editing, press the Esc or Enter key on
your keyboard.
Rename Component in - Opens the Rename component_type dialog box that allows you to rename the selected
component by specifying the new component name and the files to be affected by the modification. If you click the
Preview button, you can view the files affected by the Rename Component action.
When you select the Move action from the contextual menu of the Resource/Hierarchy Dependencies view, the Move
resource dialog box is displayed. The following fields are available:
Destination - Presents the path to the current location of the resource you want to move and gives you the option to
introduce a new location.
New name - Presents the current name of the moved resource and gives you the option to change it.
Update references of the moved resource(s) - Enable this option to update the references to the resource you are
moving, in accordance with the new location and name.
If the Update references of the moved resource(s) option is enabled, a Preview option (which opens the Preview
dialog box) is available for both actions. The Preview dialog box presents a list with the resources that are updated.
Output file - You can specify the path of the output file by entering it in the text field, or by using the
Insert
Editor Variables button or the options in the
Browse drop-down menu.
Split output into multiple files - Instructs the application to split the output into multiple files. For large WSDL
documents, choosing a different split criterion may generate smaller output files providing a faster documentation
browsing. You can choose to split them by namespace, location, or component name.
Open in Browser/System Application - Opens the result in the system application associated with the output file
type.
Note: To set the browser or system application that will be used, open the Preferences dialog box, then go
to Global and set it in the Default Internet browser field. This will take precedence over the default system
application settings.
Keep only the annotations with xml:lang set to - The generated output will contain only the annotations with the
xml:lang attribute set to the selected language. If you choose a primary language code (for example, en for
English), this includes all its possible variations (en-us, en-uk, etc.).
Figure 214: The Settings Tab of the WSDL Documentation Dialog Box
The Settings tab allows you to choose whether or not to include the following:
Components
Services - Specifies whether the generated documentation includes the WSDL services.
Bindings - Specifies whether the generated documentation includes the WSDL bindings.
Port Types - Specifies whether the generated documentation includes the WSDL port types.
Messages - Specifies whether the generated documentation includes the WSDL messages.
Only global elements and types - Specifies whether the generated documentation includes only global
elements and types.
Component Details
Namespace - Presents the namespace information for WSDL or XML Schema components.
Location - Presents the location information for each WSDL or XML Schema component.
Used by - Presents the list of components that reference the current one.
Documentation - Presents the component documentation. If you choose Escape XML Content, the XML tags
are presented in the documentation.
Source - Presents the XML fragment that defines the current component.
Instance - Generates a sample XML instance for the current component.
Note: This option applies to the XML Schema components only.
XML Schema Diagram - Displays the diagram for each XML Schema component. You can choose the image
format (JPEG, PNG, GIF, SVG) to use for the diagram section.
Diagram annotations - Specifies whether the annotations of the components presented in the diagram sections
are included.
Generate index - Displays an index with the components included in the documentation.
Include local elements and attributes - If checked, local elements and attributes are included in the documentation
index.
Include resource hierarchy - Specifies whether the resource hierarchy for an XML Schema documentation is
generated.
Export settings - Save the current settings in a settings file for further use (for example, with the exported settings file
you can generate the same documentation from the command-line interface.)
Load settings - Reloads the settings from the exported file.
Generate - Use this button to generate the WSDL documentation.
Generating WSDL Documentation in HTML Format
The WSDL documentation generated in HTML format is presented in a visual diagram style with various sections,
hyperlinks, and options.
wsdlDocumentation.bat on Windows.
wsdlDocumentation.sh on Unix / Linux.
wsdlDocumentationMac.sh on Mac OS X.
The scripts are located in the installation folder of Oxygen XML Editor. You can integrate the scripts in an external
batch process launched from the command-line interface.
Click the
Use the
The testing of a WSDL file is straight-forward: click the WSDL analysis button, then select the service, the port, and
the operation. The editor generates the skeleton for the SOAP request. You can edit the request, eventually attach files
to it and send it to the server. Watch the server response in the response area. You can find more details in the Testing
Remote WSDL Files section.
Note: SOAP requests and responses are automatically validated in the WSDL SOAP Analyzer using the XML
Schemas specified in the WSDL file.
Once defined, a request derived from a Web Service descriptor can be saved with the Save button to a Web Service
SOAP Call (WSSC) file for later reuse. In this way, you save time in configuring the URLs and parameters.
You can open the result of a Web Service call in an editor panel using the Open button.
Testing Remote WSDL Files
To open and test a remote WSDL file the steps are the following:
1. Go to Tools >
WSDL SOAP Analyzer .
2. On the WSDL File tab enter the URL of the remote WSDL file.
You enter the URL:
by typing
by browsing the local file system
by browsing a remote file system
by browsing a UDDI Registry
URL - Type the URL of an UDDI registry or choose one from the default list.
Keywords - Enter the string you want to be used when searching the selected UDDI registry for available Web
services.
Rows to fetch - The maximum number of rows to be displayed in the result list.
Search by - You can choose to search either by company or by provided service.
Case sensitive - When checked, the search takes into account the keyword case.
Search - The WSDL files that matched the search criteria are added in the result list.
When you select a WSDL from the list and click the OK button, the UDDI Registry Browser dialog box is closed and
you are returned to the WSDL File Opener dialog box.
The CSS properties accepted by the validator are those included in the current CSS profile that is selected in the CSS
validation preferences. The CSS 3 with Oxygen extensions profile includes all the CSS 3 standard properties plus the
CSS extensions specific for Oxygen that can be used in Author mode. That means all Oxygen specific extensions are
accepted in a CSS stylesheet by the built-in CSS validator when this profile is selected.
After pressing OK, Oxygen XML Editor performs the following actions:
All spaces are normalized (all leading and trailing spaces are removed, while sequences of white spaces are replaced
with single space characters).
The resulting CSS stylesheet gains a lot in terms of execution performance, but loses in terms of readability. The source
CSS document is left unaffected.
Note: To restore the readability of a minified CSS, invoke the Format and Indent action from the Document >
Source menu, the Source submenu from the contextual menu, or Source toolbar. However, this action will not
recover any of the deleted comments.
Open LESS files - the LESS extension is recognized and thus can be opened by the editor
Validation - presents errors in LESS files
Content completion - offers properties and the values available for each property
Compile to CSS - options are available to compile LESS files to CSS
Note: Oxygen XML Editor also support syntax highlighting in LESS files, although there may be some
limitations in supporting all the LESS constructs.
Automatic validation as you type - marks validation errors in the document as you are editing.
The changes you make in the Editor are immediately visible in the Diagram (no background parsing).
Changing the selected element in the diagram selects the underlying code in the source editor.
- define pattern with the name attribute set to the value shown inside the rectangle (in this example
name).
- define pattern with the combine attribute set to interleave and the name attribute
set to the value shown inside the rectangle (in this example attlist.person).
- define pattern with the combine attribute set to choice and the name attribute set to
the value shown inside the rectangle (in this example attlist.person).
- element pattern with the name attribute set to the value shown inside the rectangle (in this example
name).
- attribute pattern with the name attribute set to the value shown inside de rectangle (in this case
note).
- ref pattern with the name attribute set to the value shown inside the rectangle (in this case family).
- oneOrMore pattern.
- zeroOrMore pattern.
- optional pattern.
- choice pattern.
- group pattern.
- text pattern.
- empty pattern.
Logical Model View
The Logical Model View presents the compiled schema which is a single pattern. The patterns that form the element
content are defined as top level patterns with generated names. These names are generated depending of the elements
name class.
Show XML
Settings menu:
Append Child
Displays a list of elements that you can insert as children of the current element.
Insert Before
Displays a list of elements that you can insert as siblings of the current element, before the current element.
Insert After
Displays a list of elements that you can insert as siblings of the current element, after the current element.
Edit Attributes
Opens a dialog box that allows you to edit the attributes of the currently selected component.
Toggle Comment
Comments/uncomments the currently selected element.
Search references
Searches for the references of the currently selected component.
Search references in
Searches for the references of the currently selected component in the context of a scope that you define.
Component dependencies
Displays the dependencies of the currently selected component.
Search References - Searches all references of the item found at current cursor position in the defined scope,
if any. If a scope is defined, but the current edited resource is not part of the range of resources determined by this,
a warning dialog box is displayed and you have the possibility to define another search scope.
Search References in - Searches all references of the item found at current cursor position in the file or files that
you specify when define a scope in the Search References dialog box.
Search Declarations - Searches all declarations of the item found at current cursor position in the defined scope
if any. If a scope is defined, but the current edited resource is not part of the range of resources determined by this,
a warning dialog box will be displayed and you have the possibility to define another search scope.
Search Declarations in - Searches all declarations of the item found at current cursor position in the file or files
that you specify when you define a scope for the search operation.
Search Occurrences in File - Searches all occurrences of the item at the cursor position in the currently edited
file.
The following action is available from the contextual menu and the Document > Schema menu:
Show Definition - Moves the cursor to the definition of the current element in the Relax NG (full syntax) schema.
Note: You can also use the Ctrl Single-Click (Command Single-Click on OS X) shortcut on a reference
to display its definition.
Refactoring Actions
The following refactoring actions can be applied on named defines and are available from the Refactoring submenu in
the contextual menu of the current editor or from the Document > Refactoring menu:
Rename Component - Allows you to rename the current component in-place. The component and all its references
in the document are highlighted with a thin border and the changes you make to the component at the cursor position
Rename Component in - Opens the Rename component_type dialog box that allows you to rename the selected
component by specifying the new component name and the files to be affected by the modification. If you click the
Preview button, you can view the files affected by the Rename Component action.
New name - Presents the current name of the edited resource and allows you to modify it.
Update references - Enable this option to update the references to the resource you are renaming.
Destination - Presents the path to the current location of the resource you want to move and gives you the option to
introduce a new location.
New name - Presents the current name of the moved resource and gives you the option to change it.
Update references of the moved resource(s) - Enable this option to update the references to the resource you are
moving, in accordance with the new location and name.
If the Update references of the moved resource(s) option is enabled, a Preview option (which opens the Preview
dialog box) is available for both actions. The Preview dialog box presents a list with the resources that are updated.
Note: Updating the references of a resource that is resolved through a catalog is not supported. Also, the update
references operation is not supported if the path to the renamed or moved resource contains entities.
The changes you make in the Editor are immediately visible in the Diagram (no background parsing).
Changing the selected element in the diagram, selects the underlying code in the source editor.
Search References - Searches all references of the item found at current cursor position in the defined scope,
if any. If a scope is defined, but the current edited resource is not part of the range of resources determined by this,
a warning dialog box is displayed and you have the possibility to define another search scope.
Search References in - Searches all references of the item found at current cursor position in the file or files that
you specify when define a scope in the Search References dialog box.
Search Declarations - Searches all declarations of the item found at current cursor position in the defined scope
if any. If a scope is defined, but the current edited resource is not part of the range of resources determined by this,
a warning dialog box will be displayed and you have the possibility to define another search scope.
Search Declarations in - Searches all declarations of the item found at current cursor position in the file or files
that you specify when you define a scope for the search operation.
Search Occurrences in File - Searches all occurrences of the item at the cursor position in the currently edited
file.
The following action is available from the contextual menu and the Document > Schema menu:
Show Definition - Moves the cursor to its definition in the schema used by NVDL in order to validate it.
Note: You can also use the Ctrl Single-Click (Command Single-Click on OS X) shortcut on a reference
to display its definition.
Refactoring Actions
The following refactoring actions can be applied on name, useMode, and startMode attributes and are available
from the Refactoring submenu in the contextual menu of the current editor or from the Document > Refactoring menu:
Rename Component - Allows you to rename the current component in-place. The component and all its references
in the document are highlighted with a thin border and the changes you make to the component at the cursor position
are updated in real time to all occurrences of the component. To exit in-place editing, press the Esc or Enter key on
your keyboard.
Rename Component in - Opens the Rename component_type dialog box that allows you to rename the selected
component by specifying the new component name and the files to be affected by the modification. If you click the
Preview button, you can view the files affected by the Rename Component action.
Cut
Copy
Paste
Delete
The Settings menu on the JSON Outline view toolbar allows you to enable
Selection update on cursor move.
This option controls the synchronization between the Outline view and source the document. Oxygen XML Editor
synchronizes the selection in the Outline view with the cursor moves or the changes you make in the JSON editor.
Selecting one of the components from the Outline view also selects the corresponding item in the source document.
2.
3.
4.
5.
The operation result will be a document containing the JSON conversion of the input XML URL.
Support for validating XLIFF 2.0 documents using modules. The default modules are stored in
[OXYGEN_DIR]/frameworks/xliff/xsd/2.0/modules.
Open File at Cursor - select this action to open the source of the file located at the cursor position
Open File at Cursor in System Application - select this action to open the source of the file located at the
cursor position with the application that the system associates with the file
Compare
Select this option to open the Diff Files dialog box and compare the file you are editing with a file you choose in
the dialog box.
Folding
When you invoke the contextual menu from the folding stripe on the left side of the editor, the following actions
are available:
Collapse Other Folds (Ctrl NumPad / (Meta NumPad / on OS X))
Folds all the elements except the current element.
Collapse Child Folds (Ctrl NumPad . (Meta NumPad . on OS X))
Folds the elements indented with one level inside the current element.
Expand Child Folds
Unfolds all child elements of the currently selected element.
Expand All (Ctrl NumPad * (Meta NumPad * on OS X))
Unfolds all elements in the current document.
- function
- object
- property
- method
- variable
Note: These icons decorate both the elements from the content completion list of proposals and from the Outline
view.
Method names from the current file and from the library files.
Functions and variables defined in the current file.
If you edit the content of a function, the content completion list of proposals contains all the local variables defined in
the current function, or in the functions that contain the current one.
- function
- object
- property
- method
- variable
The contextual menu of the JavaScript Outline view contains the usual
Cut,
Copy,
Paste, and
Delete
actions. From the settings menu, you can enable the Update selection on cursor move option to synchronize the Outline
view with the editing area.
If the value of the port attribute is stylesheet and the xslt element is the parent of the input elements, the
Content Completion Assistant offers XSLT elements.
The XProc editor assists you in writing XPath expressions by offering a Content Completion Assistant and dedicated
coloring schemes. To customize the coloring schemes, open the Preferences dialog box and go to Editor > Syntax
Highlight.
For embedded ISO schematron, open the Preferences dialog box, go to XML > XML Parser > Schematron, and
select it in the Embedded rules query language binding option.
For standalone ISO Schematron, specify the version by setting the query language to be used in a queryBinding
attribute on the schema root element. For more information see the Query Language Binding section of the Schematron
specifications.
The Schematron editor renders the XPath expressions with dedicated coloring schemes . To customize the coloring
schemes, open the Preferences dialog box and go to Editor > Syntax Highlight.
To watch our video demonstration about the Schematron support in Oxygen XML Editor, go to
http://www.oxygenxml.com/demo/Schematron_Validation.html, and to
http://www.oxygenxml.com/demo/Editing_Schematron_Schemas/Editing_Schematron_Schemas.html.
Note: When you create a Schematron document, Oxygen XML Editor provides a built-in transformation
scenario. You are able to use this scenario to obtain the XSLT style-sheet corresponding to the Schematron
schema. You can apply this XSLT stylesheet to XML documents to obtain the Schematron validation results.
The possible errors that might occur during the validation process are presented in the Errors panel at the bottom area
of the Oxygen XML Editor window. Each error is flagged with a severity level that can be one of warning, error, fatal
or info.
To set a severity level, Oxygen XML Editor looks for the following information:
The role attribute, which can have one of the following values:
The start of the message, after trimming leading white-spaces. Oxygen XML Editor looks to match the following
exact string of characters (case sensitive):
If none of the previous rules match, Oxygen XML Editor sets the severity level to error.
The second association validates your document with Schematron rules extracted from the RELAX NG Schema.
Similarly, you can specify an XML Schema having the embedded Schematron rules.
<?xml-model href="percent.xsd" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>
Note: When you work with XML Schema or Relax NG documents that have embedded Schematron rules
Oxygen XML Editor provides two built-in validation scenarios: Validate XML Schema with embedded
Schematron for XML schema , and Validate Relax NG with embedded Schematron for Relax NG. You can
use one of these scenarios to validate the embedded Schematron rules.
When you select the Move action from the contextual menu of the Resource/Hierarchy Dependencies view, the Move
resource dialog box is displayed. The following fields are available:
Destination - Presents the path to the current location of the resource you want to move and gives you the option to
introduce a new location.
New name - Presents the current name of the moved resource and gives you the option to change it.
Update references of the moved resource(s) - Enable this option to update the references to the resource you are
moving, in accordance with the new location and name.
If the Update references of the moved resource(s) option is enabled, a Preview option (which opens the Preview
dialog box) is available for both actions. The Preview dialog box presents a list with the resources that are updated.
Search References - Searches all references of the item found at current cursor position in the defined scope,
if any. If a scope is defined, but the current edited resource is not part of the range of resources determined by this,
a warning dialog box is displayed and you have the possibility to define another search scope.
Search References in - Searches all references of the item found at current cursor position in the file or files that
you specify when define a scope in the Search References dialog box.
Search Declarations - Searches all declarations of the item found at current cursor position in the defined scope
if any. If a scope is defined, but the current edited resource is not part of the range of resources determined by this,
a warning dialog box will be displayed and you have the possibility to define another search scope.
Search Declarations in - Searches all declarations of the item found at current cursor position in the file or files
that you specify when you define a scope for the search operation.
Search Occurrences in File - Searches all occurrences of the item at the cursor position in the currently edited
file.
Refactoring Actions
The following refactoring actions can be applied on pattern, phase, or diagnostic types and are available from
the Refactoring submenu in the contextual menu of the current editor or from the Document > Refactoring menu:
Rename Component - Allows you to rename the current component in-place. The component and all its references
in the document are highlighted with a thin border and the changes you make to the component at the cursor position
are updated in real time to all occurrences of the component. To exit in-place editing, press the Esc or Enter key on
your keyboard.
Rename Component in - Opens the Rename component_type dialog box that allows you to rename the selected
component by specifying the new component name and the files to be affected by the modification. If you click the
Preview button, you can view the files affected by the Rename Component action.
ID - Defined by the id attribute from the fix element and must be unique in the current context. It is used to refer
the quick fix from a report or assert element.
Name - The name of the quick fix is defined by the title element.
Description - Defined by the text in the paragraphs (p) of the description element.
Operations - The following types of operations are supported:
Insert Element - To insert an element, use the <sqf:add> element, set the value of the node-type to
"element", and specify the element QName with the target attribute. If the element has a prefix, it must be
defined in the Schematron using a namespace declaration (<ns uri="namespace" prefix="prefix"/>).
Insert Attribute - To insert an attribute, use the <sqf:add> element, set the value of the node-type to
"attribute", and specify the attribute QName with the target attribute. If the attribute has a prefix, it must be
defined in the Schematron using a namespace declaration (<ns uri="namespace" prefix="prefix"/>).
Insert Fragment - If the node-type is not specified, the <sqf:add> element will insert an XML fragment.
The XML fragment must be well formed. You can specify the fragment in the add element or by using the
select attribute.
Insert Comment - To insert a comment, use the <sqf:add> element and set the value of the node-type
to "comment".
Insert Processing Instruction - To insert a processing instruction, use the <sqf:add> element, set the value
of the node-type to "pi" or "processing-instruction", and specify the name of the processing instruction in
the target attribute.
Delete
The <sqf:delete> element allows you to remove any type of node (such as elements, attributes, text, comments,
or processing instructions). To specify nodes for deletion the <sqf:delete> element can include a match
attribute that is an XPath expression (the default value is .). If the match attribute is not included, it deletes the
context node of the Schematron rule.
Replace
The <sqf:replace> element allows you to replace nodes. Similar to the <sqf:delete> element, it can include
a match attribute. Otherwise, it replaces the context node of the rule. The <sqf:replace> element has three
tasks. It identifies the nodes to be replaced, defines the replacing nodes, and defines their content.
An Example of the <sqf:replace> Element:
<schema xmlns="http://purl.oclc.org/dsdl/schematron"
xmlns:sqf="http://www.schematron-quickfix.com/validator/process" queryBinding="xslt2">
<pattern>
<rule context="title">
<report test="exists(ph)" sqf:fix="resolvePh" role="warn">
ph element is not allowed in title.</report>
<sqf:fix id="resolvePh">
<sqf:description>
<sqf:title>Change the ph element into text</sqf:title>
</sqf:description>
<sqf:replace match="ph">
<value-of select="."/>
</sqf:replace>
</sqf:fix>
</rule>
</pattern>
</schema>
node-type - Determines the type of the replacing node. The permitted values include:
target - By using a QName it gives the replacing node a name. This is necessary when the value of the
node-type attribute is anything other than "comment".
select - Allows you to choose the content of the replacing nodes. You can use XPath expressions with the
select attribute. If the select attribute is not specified then the content of the <sqf:replace> element
is used instead.
String Replace
The <sqf:stringReplace> element is different from the others. It can be used to find a sub-string of text
content and replace it with nodes or other strings.
Attributes for the String Replace Operation:
match - Allows you to select text nodes that contain the sub-strings you want to replace.
select - Allows you to select the replacing fragment, in case you do not want to set it in the content of the
stringReplace element.
regex - Matches the sub-strings using a regular expression.
xsl:text - You can use an xsl:text element to format the inserted content and keep the automatic indentation,
as in the following example:
<sqf:add position="last-child">
<row><xsl:text>
</xsl:text>
<entry>First column</entry><xsl:text>
</xsl:text>
<entry>Second column</entry><xsl:text>
</xsl:text>
</row><xsl:text>
</xsl:text>
</sqf:add>
xml:space - Use the xml:space attribute and set its value to preserve to format the content and specify the
spacing between elements, as in the following example:
<sqf:add node-type="element" target="codeblock" xml:space="preserve">
/* a long sample program */
Do forever
Say "Hello, World"
End</sqf:add>
Search References - Searches all references of the item found at current cursor position in the defined scope,
if any. If a scope is defined, but the current edited resource is not part of the range of resources determined by this,
a warning dialog box is displayed and you have the possibility to define another search scope.
Search References in - Searches all references of the item found at current cursor position in the file or files that
you specify when define a scope in the Search References dialog box.
Search Declarations - Searches all declarations of the item found at current cursor position in the defined scope
if any. If a scope is defined, but the current edited resource is not part of the range of resources determined by this,
a warning dialog box will be displayed and you have the possibility to define another search scope.
Search Declarations in - Searches all declarations of the item found at current cursor position in the file or files
that you specify when you define a scope for the search operation.
Search Occurrences in File - Searches all occurrences of the item at the cursor position in the currently edited
file.
Refactoring Actions
The following refactoring actions can be applied on quick fix ids and are available from the Refactoring submenu in
the contextual menu of the current editor or from the Document > Refactoring menu:
Rename Component - Allows you to rename the current component in-place. The component and all its references
in the document are highlighted with a thin border and the changes you make to the component at the cursor position
are updated in real time to all occurrences of the component. To exit in-place editing, press the Esc or Enter key on
your keyboard.
Rename Component in - Opens the Rename component_type dialog box that allows you to rename the selected
component by specifying the new component name and the files to be affected by the modification. If you click the
Preview button, you can view the files affected by the Rename Component action.
Zoom out
To zoom in on an image, use any of the following methods:
Rotate
To rotate an image, use either of the following methods:
Refresh
To refresh (or reset) an image, use either of the following methods:
Move
To move an image, use either of the following methods:
Pan
To pan an image, click and drag the image with your mouse.
Start with a static SVG image, written directly in Oxygen XML Editor or exported from a external graphics tool.
Extract the parts that are dependent on the data from the XML document.
Create XSL templates to be applied on the XML document.
Create an XML transformation with XSLT scenario.
While configuring the transformation scenario, select Show in results view as > SVG in the Output tab of the
configuration dialog box.
6. Run the transformation.
The SVG image is rendered in an integrated SVG viewer in the results panel at the bottom of the editor.
Spell Checking
Oxygen XML Editor includes an automatic (as-you-type) spell checking feature, as well as a manual spell checking
action to opens a Spelling dialog box that offers a variety of options. To open this dialog box, use the
action on the toolbar or from the Edit menu.
Check Spelling
Unrecognized word - Contains the word that cannot be found in the selected dictionary. The word is also highlighted
in the XML document.
Replace with - The character string which is suggested to replace the unrecognized word.
Guess - Displays a list of words suggested to replace the unknown word. Double click a word to automatically insert
it in the document and resume the spell checking process.
Default language - Allows you to select the default dictionary used by the spelling engine.
Paragraph language - In an XML document you can mix content written in different languages. To tell the spell
checker engine what language was used to write a specific section, you need to set the language code in thelang
or xml:lang attribute to that section. Oxygen XML Editor automatically detects such sections and instructs the
spell checker engine to apply the appropriate dictionary.
Replace - Replaces the currently highlighted word in the XML document, with the selected word in theReplace
with field.
Replace All - Replaces all occurrences of the currently highlighted word in the XML document, with the selected
word in theReplace with field.
Ignore - Ignores the first occurrence of the unrecognized word and allows you to continue checking the
document.Oxygen XML Editor skips the content of the XML elements marked as ignorable.
Ignore All - Ignores all instances of the unknown word in the current document.
Learn - Includes the unrecognized word in the list of valid words.
Options - Sets the configuration options of the spell checker.
Begin at cursor position - Instructs the spell checker to begin checking the document starting from the current
cursor position.
English (US)
English (UK)
French
German
Spanish.
Each language-country variant combination has its specific dictionary. If you cannot find a Hunspell dictionary that is
already built for your language, you can build the dictionary you need. To build a dictionary from this list follow these
instructions.
Add Dictionaries and Term Lists for the Hunspell Checker
To add new spelling dictionaries to Oxygen XML Editor, or to replace an existing one, follow these steps:
1. Download the files you need for your language dictionary.
2. The downloaded .oxt file is a zip archive. If you are creating a new dictionary, copy the .aff and .dic files
from this archive in the spell subfolder of the Oxygen XML Editor preferences folder.
The Oxygen XML Editor preferences folder is [APPLICATION-DATA-FOLDER]/com.oxygenxml>, where
[APPLICATION-DATA-FOLDER] is:
3. If you are updating an existing dictionary, copy the .aff and .dic files into the folder
[OXYGEN_DIR]/dicts/spell.
4. Restart the application after copying the dictionary files.
Note: You can specify that Oxygen XML Editor includes dictionaries and term lists from a custom location
by selecting the Include dictionaries and term list from option and specifying its path in the Dictionaries
preferences page.
Dictionaries for the Java Checker
A Java spell checker dictionary has the form of a .dar file located in the directory [OXYGEN_DIR]/dicts. Oxygen
XML Editor comes with the following built-in dictionaries for the Java checker:
English (US)
English (UK)
English (Canada)
French (France)
French (Belgium)
French (Canada)
French (Switzerland)
A pre-built dictionary can be added by copying the corresponding .dar file to the folder [OXYGEN_DIR]/dicts
and restarting Oxygen XML Editor. There is one dictionary for each language-country variant combination.
Learned Words
Spell checker engines rely on dictionary to decide that a word is correctly spelled. To tell the spell checker engine that
an unknown word is actually correctly spelled, you need to add that word to its dictionary. There are two ways to do
this:
Learned words are stored into a persistent dictionary file. Its name is composed of the currently checked language code
and the .tdi extension, for example en_US.tdi. It is located in the:
The spelling corrections are displayed in the Results view, that allows you to group the reported errors as a tree with
two levels.
All opened files - The spell check is performed in all opened files.
Directory of the current file - All the files in the folder of the current edited file.
Project files - All files from the current project.
Selected project files - The selected files from the current project.
Specified path - Checks the spelling in the files located at a path that you specify.
File filter - Allow you to filter the files from the selected scope.
Recurse subdirectories - When enabled, the spell check is performed recursively for the specified scope. The one
exception is that this option is ignored if the scope is set to All opened files.
Include hidden files - When enabled, the spell check is also performed in the hidden files.
Spell Check Options - The spell check processor uses the options available in the Spell Check preferences panel .
When you invoke the Check Spelling in Files action in the DITA Maps Manager view, a different dialog box is
displayed:
Figure 253: Check Spelling in Files Dialog Box (Invoked from the DITA Maps Manager View)
The following scopes are available:
Current DITA Map hierarchy - All the files referenced in the currently selected DITA map, opened in the DITA
Maps Manager view
Specified path - checks the spelling in the files located at a path that you specify
AutoCorrect is enabled by default. To configure this feature, open the Preferences dialog box and go to Editor > Edit
Modes > Author > AutoCorrect.
The actual operation of replacing a word is triggered by a space, dash, or punctuation mark (, . ; : ? !). After a
correction, the affected string is highlighted. The highlight is removed upon the next editing action (text insertion or
deletion). If you hover over the highlight, a small widget appears below the word. If you hover over the widget, it expands
and you can click it to present a drop-down list that includes the following options:
Change back to "..." - Reverts the correction back to its original form.
Stop Automatically Correcting "..." - This option is presented if the correction is performed based on the AutoCorrect
Replacements Table and selecting it will delete the corresponding entry from the Replacements Table.
Learn Word "..." - This option is presented if the Use additional suggestions from the spell checker option is
enabled in the AutoCorrect preferences page and the correction is performed based on the Spell Checker. Selecting
this option will add the item to the list of learned words.
AutoCorrect options - Opens the AutoCorrect Preferences on page 1176 page that allows you to configure the feature.
Words with all lower-case characters will be replaced with lower-case substitutions (for example, "abotu" is replaced
with "about").
Words with irregular-case characters will be replaced with lower-case substitutions ("ABotU" is replaced with
"about").
Words with all upper-case characters will be replaced with upper-case substitutions ("ABOTU" is replaced with
"ABOUT").
Words starting with an upper-case character will be replaced with substitutions having the same pattern ("Abotu" is
replaced with "About").
The AutoCorrect feature also uses the list of ignored elements from the Spell Check preferences page. All elements
(along with their descendant elements) included in this list will be ignored by the AutoCorrect engine.
3. If you are updating an existing dictionary, copy the .dat file to the folder
[OXYGEN_DIR]/dicts/autocorrect.
4. Restart the application after copying the dictionary files.
Note: You can setup Oxygen XML Editor to use dictionaries from a custom location configured in the
Dictionaries preferences page.
A file larger than the value of the above option is edited only in Text mode.
The automatic validation is not available when editing a very large file.
The XPath filter is disabled in the Find/Replace dialog box.
The bidirectional Unicode support (right-to-left writing) is disabled.
The option Format and indent the document on open is disabled for non-XML documents. For XML documents,
it is done optimizing the memory usage but without respecting the options set in the Format preferences page.
For XML files, only the UTF-8, UTF-16, and ASCII encodings are handled; for all non-XML files, the content is
considered to be UTF-8.
Files can be edited in Text edit mode only.
The automatic validation is disabled.
The XPath filter is disabled in the Find/Replace dialog box.
The bidirectional Unicode support (right-to-left writing) is disabled.
The Format and indent the document on open option is disabled for non-XML documents. For XML documents,
the format and indent operation it is done optimizing the memory usage, but it ignores the options set in the Format
preferences page.
The undo operation is not available if you go to other pages and come back to the modified page. the Undo operation
loses its previous states if the back and forth between
Scratch Buffer
A handy addition to the document editing is the Scratch Buffer view used for storing fragments of arbitrary text during
the editing process. It can be used to drop bits of paragraphs (including arbitrary XML markup fragments) while
rearranging and editing the document and also to drag and drop fragments of text from the scratch buffer to the editor
panel. The Scratch Buffer is basically a text area offering XML syntax highlight. The view contextual menu contains
basic edit actions like Cut, Copy, and Paste.
The last two restrictions are valid only for XML documents.
In Finder, right click a file and from the contextual menu select Get Info.
In the Open With subsection, select Other from the application combo and browse to Oxygen XML Editor.
With Oxygen XML Editor selected, click Change All.
Chapter
7
DITA Authoring
Topics:
This chapter is designed to be a guide to help content authors who use DITA.
It also presents the Oxygen XML Editor features that are specific to working
with DITA documents and concepts.
To open a sub-map in its own tab in the DITA Maps Manager, simply double click it (or right-click it and select
Open).
To open a map in the XML editor from the DITA Maps Manager, right-click it and select Open Map in Editor.
If you open a file with the .ditamap or .bookmap extension (from the Project view or a system browser), a
dialog box is opened that offers you the choice of opening it in the XML editor or in the DITA Maps Manager.
Note: If you select the Do not show the dialog again option, it will always be opened in the method that
you choose and you will not be asked in the future. However, you can reset this by selecting Always ask for
the When opening a map option in the DITA preferences page.
To open a map in the DITA Maps Manager, you can right click a map file in the Project view and select Open
with > DITA Maps Manager.
If you have a DITA map file open in the XML editor, you can open it in the DITA Maps Manager by right-clicking
the title tab and selecting Open in DITA Maps Manager View.
To open a sub-map in its own tab, simply double click it (or right-click it and select Open).
If you open a file with the .ditamap or .bookmap extension (from the Project view or a system browser), a
dialog box is opened that offers you the choice of opening it in the DITA Maps Manager or the XML editor.
Note: If you select the Do not show the dialog again option, it will always be opened in the method that
you choose and you will not be asked in the future. However, you can reset this by selecting Always ask for
the When opening a map option in the DITA preferences page.
Right click a map file in the Project view and select Open with > DITA Maps Manager.
If you have a DITA map file open in the XML editor, you can right-click the title tab and select Open in DITA Maps
Manager View.
If your map references other DITA maps, they will be shown, expanded, in the DITA Maps Manager view and you
will be able to navigate their content. To edit the sub-maps and their content, you need to open each referenced map
separately.
Note: You can choose to not expand referenced maps in the DITA Maps Manager view by disabling the
Display referenced content option in the Author preferences page.
Drag and Drop in the DITA Maps Manager
You can move topics or nodes in the same map, or between different maps, by dragging and dropping them into the
desired position. You can arrange the nodes by dragging and dropping one or more nodes at a time. You can arrange
multiple topics by dragging them while pressing the Ctrl or Shift key. Drop operations can be performed before, after,
or as child of the targeted node.
List of recently viewed DITA maps that can be selected to reopen them.
Clear history - Clears the history list of the recently viewed DITA maps.
Open URL - Displays the Open URL dialog box that allows you to access any resource identified through
a URL (defined by a protocol, host, resource path, and an optional port). The following actions are available in
this drop-down menu:
Open - Allows you to open the map in the DITA Maps Manager view. You can also open a map by
dragging it from the file system explorer and dropping it into the DITA Maps Manager view.
Browse for local file - Opens a local file browser dialog box, allowing you to select a local DITA map.
Browse for remote file - Displays the Open URL dialog box that allows you to open a remotely stored
DITA map.
Browse for archived file - Displays the Archive Browser dialog box that allows you to browse the
content of an archive and choose a DITA map.
Browse Data Source Explorer - Opens the Data Source Explorer that allows you to browse the data
sources defined in the Data Sources preferences page.
Tip: You can open the Data Sources preferences page by using the Configure Database Sources
shortcut from the Open URL dialog box.
Search for file - Displays the Open/Find Resource dialog box that allows you to search for a DITA
map.
Show Profiling Colors and Styles - Enable this option to turn on conditional styling. To configure the colors
and styles open the Preferences dialog box and go to Editor > Edit modes > Author > Profiling/Conditional
Text > Colors and Styles.
Show Profiling Attributes - Enable this options to display the values of the profiling attributes at the end of
the titles of topic references. When enabled, the values of the profiling attributes are displayed in both the DITA
Maps Manager view and in the Author view.
Show Excluded Content - Controls if the content filtered out by a particular condition set is hidden or greyed-out
in the editor area and in the Outline and DITA Maps Manager views. When this option is enabled, the content
filtered by the currently applied condition set is greyed-out. To show only the content that matches the currently
applied condition set, disable this option.
Profiling Settings - Opens the preferences page for adding and editing the profiling conditions that you can
apply in the DITA Maps Manager view and the Author view. When a profiling condition set is applied, the
keys that are defined in the DITA map are gathered by filtering out the excluded content.
Browse for local file - Opens a local file browser dialog box, allowing you to select a local root map.
Browse for remote file - Displays the Open URL dialog box that allows you to select a remotely stored
root map.
Browse for archived file - Displays the Archive Browser dialog box that allows you to browse the content
of an archive and choose a root map.
Browse Data Source Explorer - Opens the Data Source Explorer that allows you to browse the data
sources defined in the Data Sources preferences page.
Tip: You can open the Data Sources preferences page by using the Configure Database Sources
shortcut from the Open URL dialog box.
Search for file - Displays the Find Resource dialog box to search for a root map.
The following additional actions are displayed in the toolbar when the Show extended toolbar option is selected in the
Settings menu:
Insert Topic Reference
Opens the Insert Reference dialog box that allows you to insert references to targets such as anchors, topics, maps,
topic sets, or key definitions.
Edit Properties
Opens the Edit Properties dialog box that allows you to configure the properties of a selected node. You can find
more details about this dialog box in the Edit Properties in DITA Maps on page 489 topic.
Edit Attributes
Opens a small in-place editor that allows you to edit the attributes of a selected node. You can find more details
about this action in the Attributes View in Author Mode on page 112 topic.
Delete
Deletes the selected node.
Move Up
Moves the selected node up within the DITA map tree.
Move Down
Moves the selected node down within the DITA map tree.
Promote(Alt Left Arrow)
Moves the selected node up one level to the level of its parent node.
Demote(Alt Right Arrow)
Moves the selected node down one level to the level of its child nodes.
Contextual Menu of the DITA Maps Manager
The following actions can be invoked from the contextual menu on the root map of an opened DITA map:
Open Map in Editor
For complex operations that cannot be performed in the simplified DITA Maps Manager view (for instance, editing
a relationship table) you can open the map in the main editing area.
Open Map in Editor with Resolved Topics
Opens the DITA map in the main editor area with content from all topic references, expanded in-place. Content
from the referenced topics is presented as read-only and you have to use the contextual menu action Edit Reference
to open the topic for editing.
Export DITA Map
Allows you to choose a destination for exporting the DITA map.
New - Opens a dialog box that allows you to configure some options for inserting a new topic.
Reference - Inserts a reference to a topic file. You can find more details about this action in the Inserting
References topic.
Reference to the currently edited file - Inserts a reference to the currently edited file. You can find more details
about this action in the Inserting References topic.
Key Reference - Opens an Insert Key Definition dialog box that allows you to insert a key reference.
Key Reference with Keyword - Opens a simplified Insert Key Definition dialog box that allows you to define
a key and a value inside a keyword.
A set of actions that open the Insert Reference dialog box that allow you to insert various reference specializations
(such as Anchor Reference, Glossary Reference, Map Reference, Navigation Reference, Topic Group,
Topic Head, Topic Reference, Topic Set, Topic Set Reference).
Search References
Searches all references to the current topic in the entire DITA map.
Refactoring submenu
The following actions are available from this submenu:
Rename resource
Allows you to change the name of a resource linked in the edited DITA map.
Move resource
Allows you to change the location on disk of a resource linked in the edited DITA map.
XML Refactoring
Opens the XML Refactoring tool wizard that presents refactoring operations to assist you with managing the
structure of your XML documents.
Find/Replace in Files
Allows you to find and replace content across multiple files.
Check Spelling in Files
Allows you to spell check multiple files.
Paste
Allows you to paste content from the clipboard into the DITA map.
Paste Before
Pastes the content of the clipboard (only if it is a part of the DITA map) before the currently selected DITA map
node.
Paste After
Pastes the content of the clipboard (only if it is a part of the DITA map) after the currently selected DITA map node.
Expand All
Allows you to expand the entire DITA map structure.
Collapse All
Allows you to collapse the entire DITA map structure.
New - Opens a dialog box that allows you to configure some options for inserting a new topic.
Reference - Inserts a reference to a topic file. You can find more details about this action in the Inserting
References topic.
Reference to the currently edited file - Inserts a reference to the currently edited file. You can find more details
about this action in the Inserting References topic.
Key Reference - Opens an Insert Key Definition dialog box that allows you to insert a key reference.
Key Reference with Keyword - Opens a simplified Insert Key Definition dialog box that allows you to define
a key and a value inside a keyword.
A set of actions that open the Insert Reference dialog box that allow you to insert various reference specializations
(such as Anchor Reference, Glossary Reference, Map Reference, Navigation Reference, Topic Group,
Topic Head, Topic Reference, Topic Set, Topic Set Reference).
New - Opens a dialog box that allows you to configure some options for inserting a new topic.
Reference - Inserts a reference to a topic file. You can find more details about this action in the Inserting
References topic.
Reference to the currently edited file - Inserts a reference to the currently edited file. You can find more details
about this action in the Inserting References topic.
Key Reference - Opens an Insert Key Definition dialog box that allows you to insert a key reference.
Key Reference with Keyword - Opens a simplified Insert Key Definition dialog box that allows you to define
a key and a value inside a keyword.
A set of actions that open the Insert Reference dialog box that allow you to insert various reference specializations
(such as Anchor Reference, Glossary Reference, Map Reference, Navigation Reference, Topic Group,
Topic Head, Topic Reference, Topic Set, Topic Set Reference).
Search References
Searches all references to the current topic in the entire DITA map.
Refactoring submenu
The following actions are available from this submenu:
Rename resource
Allows you to change the name of a resource linked in the edited DITA map.
Move resource
Allows you to change the location on disk of a resource linked in the edited DITA map.
XML Refactoring
Opens the XML Refactoring tool wizard that presents refactoring operations to assist you with managing the
structure of your XML documents.
Find/Replace in Files
Allows you to find and replace content across multiple files.
Check Spelling in Files
Allows you to spell check multiple files.
Move Up - Moves the selected node up within the DITA map tree.
Move Down - Moves the selected node down within the DITA map tree.
Promote(Alt Left Arrow) - Moves the selected node up one level to the level of its parent node.
Demote(Alt Right Arrow) - Moves the selected node down one level to the level of its child nodes.
Expand All
Allows you to expand the entire DITA map structure.
Collapse All
Allows you to collapse the entire DITA map structure.
To watch our video demonstration about the DITA Maps Manager view, go to
http://oxygenxml.com/demo/DITA_Maps_Manager.html.
Creating a Map
To create a DITA map, Subject scheme, bookmap, or other types of DITA maps, follow these steps:
1. Go to File > New.
A New document dialog box is opened that allows you to select a document type from various folders.
2. Select one of the DITA Map templates from the Framework templates folder.
3. Click the Create button.
4. Select whether you want to open the map in the DITA Maps Manager or the Editor.
5. Save the map using the
Save button on the toolbar of the DITA Maps Manager view.
Selecting a Root Map
Oxygen XML Editor allows you to select a DITA map as a key space, or root map, for all the other DITA maps and
topics in the project. Specifying the correct root map helps to prevent validation problems when you work with keyrefs
and also acts as the foundation for content completion. All the keys that are defined in a root map are available in the
maps that the root map contains.
There are several ways to select or change the root map:
To watch our video demonstration about the DITA Root Map support, go to
http://oxygenxml.com/demo/DITA_Root_Map.html.
Creating DITA Sub-Maps
You can break up a large DITA map into more manageable pieces by creating sub-maps. A sub-map is simply a DITA
map that is included by another DITA map. There is no separate markup for a sub-map.
For example, if you are creating a book, you might use one sub-map for each chapter of the book. If you are reusing a
set of topics in multiple publications, you might collect them into a map and reuse the map as a sub-map in multiple
other maps, rather than referencing the topics individually from the new maps.
You add a sub-map to a map the same way that you would add a new topic or insert an exiting topic into a map, except
you choose a map rather than a topic to create or add. When adding a sub-map, to a map, make sure that you use a
mapref element or a topicref element with the format attribute set to ditamap. In most cases, Oxygen XML
Editor takes care of this for you.
You can move sub-maps around in a map just as you would move a topic.
Creating a Book Map in DITA
If you want to create a traditional book in DITA, you can use a book map to organize your topics into a book. A DITA
book map is a specialized type of map, intended for creating output that is structured like a book. A book map allows
you to add book-specific elements such as frontmatter, part, chapter, appendix, and backmatter to the
map. How these book-specific elements are processed for publication is up to the processing script for each media. See
the DITA documentation for details.
You can find additional support for creating books in DITA in the DITA for Publishers plugin, which is included with
.
To create a book in DITA using a book map:
1. Create a new book map. File > New > Framework templates > DITA Map > map > Bookmap.
2. Create the structure of your book by adding the appropriate book sections and defining containers for chapters and
any appendices. To add sections to a book map, or children to a section, right-click the book map or section icon
and choose Append child. The selections offered in the Append child and Insert After menus will adjust depending
on the element they are applied to. Consult the DITA documentation to fully understand the structure of a DITA
book map and where to create each element.
3. Create special elements like an index and a table of contents. The index and table of contents will be generated by
the build process, based on the content of the map and the topics it points to.
4. Add topics to your chapters to add content to your book. You may find it easier to manage if you use sub-maps to
create the content of your chapters. This keeps your book map from becoming long and difficult to manage.
Right-click an item in the current map where you want to add the reference, select Append child or Insert After
and select the type of reference to enter.
If the topic you want to add is currently open in the editor, you can right-click an item in the current map where
you want to add the reference and select Reference to the currently edited file.
Select
Adding topics this way will not open the Insert Reference dialog box, but you can adjust all the same properties
by invoking the contextual menu from the topic and selecting Edit Properties.
Adding a New Topic to a Map
To add a new topic to a map:
1. Right-click the place in the current map where you want to add the new topic.
2. To insert the topic as a child of the selected node, select Append Child > New. To insert the topic as a sibling to
the current node, select Insert After > New.
This opens a New file template dialog box that allows you to select the type of document and assists you with naming
it.
Adding Multiple References to the Same Topic in a Map
Oxygen XML Editor allows you to add multiple references to the same topic in a DITA map. Whenever multiple
references to the same topic are detected, an indicator will appear in the top-right corner of the Author mode editor that
shows the number of times the topic is referenced in the DITA map. It also includes navigation arrows that allow you
to jump to the next or previous reference.
New name - Presents the current name and allows you to change it.
Update references - Enable this checkbox to update all references of the file in the edited DITA map and in the
files referenced from the DITA map, preserving the completeness of the DITA map.
Preview - Select this button to display a preview of the changes Oxygen XML Editor is about to make.
Rename - Executes the Rename resource operation.
Cancel - Cancels the Rename resource operation. No changes are applied.
Select
Reference, Reference to the currently edited file, or any of the other specific reference actions that are
available from the Append Child and Insert After submenus when invoking the contextual menu in the DITA
Maps Manager.
To insert the reference as a child of the current node, select the reference from the Append Child submenu.
To insert the reference as a sibling of the current node (below the current node in the map), select the reference
from the Insert After submenu.
Note: The content of these submenus depends on the node that is selected in the DITA map tree when the
contextual menu is invoked. For example, if the selected node is a topic reference (topicref), its possible
child nodes include the following elements: anchorref, chapter, keydef, mapref, topicgroup,
topichead, topicref, topicset, and topicsetref.
Click the
Insert Reference button on the DITA Maps Manager extended toolbar. This action will insert the
reference as a sibling of the current node (below the current node in the map).
Select
Insert Reference from the DITA Maps menu. This action will insert the reference as a sibling of the
current node (below the current node in the map).
For the
Reference or Reference to the currently edited file actions, a Reference type drop-down list is displayed
at the top of the Insert Reference dialog box and you can select the type of reference you want to insert. Depending on
the place where the reference will be inserted, Oxygen XML Editor will propose only valid reference types . When you
change the reference type, the fields in the various tabs of the dialog box are reconfigured depending upon the availability
of the associated attributes. For the other reference actions in the Append Child and Insert After submenus, the reference
type is automatically chosen based upon the invoked action and you cannot change it.
The main section of the dialog box includes the following tabs: Target, Keys, Attributes, Metadata, and Profiling.
Target Tab
Choose key reference button to access the list of keys that are already defined
Attributes Tab
If your root DITA map references a DITA subject scheme map that defines values for the profiling attributes, those
values are used.
If your project defines project-level configuration values for the profiling attributes, those values are used.
If Oxygen XML Editor defines global-level configuration values for the profiling attributes, they are used.
Otherwise, a basic default set of profiling attributes and values are used.
When you modify a value in this tab, the change will also automatically be reflected in the Attributes tab. For more
information, see the DITA Profiling / Conditional Text on page 540 section.
Finalizing Your Insert Reference Configuration
Once you click Insert or Insert and close, the configured reference is added in the map.
Tip: You can easily insert multiple references by keeping the Insert Reference dialog box opened, using the
Insert button.
Inserting Topic Headings
The topichead element provides a title-only entry in a navigation map, as an alternative to the fully-linked title
provided by the topicref element.
You can insert a topic heading by doing the following:
Select Topic Head from the Append Child or Insert After submenus when invoking the contextual menu in the
DITA Maps Manager view.
Open the DITA map in the XML editor and select the
from the Insert submenu of the contextual menu).
Those actions open the Insert Topic Head dialog box that allows you to easily insert a topichead element. A
Navigation title (navtitle attribute) is required but other attributes can also be specified from this dialog box (such
as Type, Scope, Format, etc.)
Select Topic Group from the Append Child or Insert After submenus when invoking the contextual menu in the
DITA Maps Manager view.
Open the DITA map in the XML editor and select the
the Insert submenu of the contextual menu).
Insert Topic Group action from the main toolbar (or from
Those actions open the Insert Topic Group dialog box that allows you to easily insert a topicgroup element and
various attributes can be specified (such as Collection type, Type, Scope, Format, etc.)
Note: The profiling of the names is now contained in the map, where it only has to occur once to reuse throughout
the whole map structure.
Key Definition with a Keyword
To insert a key definition with a keyword in a DITA map, follow these steps:
1. Open the DITA map in the DITA Maps Manager.
2. Invoke the contextual menu and select Key Definition from the Append Child or Insert After submenu (depending
on where you want to insert the key definition in the DITA map). This opens an Insert Key Definition dialog box.
3. Go to the Keys tab and enter the name of the key in the Define keys field.
Choose key reference button) to select a key that is already defined in the root
Attributes Tab
For other types of targets, the tab includes the following sections and fields that can be used to edit the attributes of the
target:
Navigation title
This text field allows you to specify a custom navigation title for the target reference. You can enforce the use of
the specified title by enabling the Lock checkbox.
Collection type
This drop-down list allows you to select the collection-type attribute to create hierarchical linking between
topics in a DITA map (for example, unordered, sequence, choice, family,
-dita-use-conref-target).
Type
Allows you to select a type attribute (such as topic, task, concept, etc.) for the target element. If you want
this attribute to always be populated with a detected value (based on the specifications for the target file), enable
the Type checkbox for the Always fill values for attributes option in the DITA preferences page.
Scope
This property corresponds to the scope attribute of the target element. It is populated automatically, based on the
selected file type, unless its value for the selected target file is the same as the default attribute value. If you want
this attribute to always be populated with a detected value (based on the specifications), enable the Scope checkbox
for the Always fill values for attributes option in the DITA preferences page.
Format
This property corresponds to the format attribute of the target element. It is populated automatically, based on
the selected file type, unless its value for the selected target file is the same as the default attribute value. If you
want this attribute to always be populated with a detected value (based on the specifications), enable the Format
checkbox for the Always fill values for attributes option in the DITA preferences page.
Processing Role
This drop-down list allows you to set the processing-role attribute to one of the allowed values for DITA
reference elements (for example, resource-only, normal, -dita-use-conref-target).
Other attributes table
This table contains the attributes that are available for the selected reference. You can use this table to insert or edit
the values of any of the listed attributes. Clicking a cell in the Value column allows you to use the combo box to
enter, edit, or select attribute values.
If your root DITA map references a DITA subject scheme map that defines values for the profiling attributes, those
values are used.
If your project defines project-level configuration values for the profiling attributes, those values are used.
If Oxygen XML Editor defines global-level configuration values for the profiling attributes, they are used.
Otherwise, a basic default set of profiling attributes and values are used.
When you modify a value in this tab, the change will also automatically be reflected in the Attributes tab. For more
information, see the DITA Profiling / Conditional Text on page 540 section.
Finalizing Your Modifications
Once you click OK, all your changes are applied to the target node.
You customized your DITA map to reference topics using URIs instead of local paths
You have URI content references in your DITA topic files and you want to map them to local files when the map is
transformed
In such situations, you have to add the catalog to Oxygen XML Editor. The DITA Maps Manager view will solve the
displayed topic refs through the added XML catalog, as will DITA map transformations (for PDF output, XHTML
output, etc.)
Finding Resources Not Referenced in DITA Maps
Over the course of time large projects can accumulate a vast amount of resources from a variety of sources. Especially
in organizations with a large number of content writers or complex project structures, organizing the project resources
can become a challenge. Over time a variety of actions can cause resources to become orphaned from DITA maps. To
assist you with organizing project resources, Oxygen XML Editor includes an action, Find Unreferenced Resources,
that searches for orphaned resources that are not referenced in DITA maps.
To perform this search, open the DITA map in the DITA Maps Manager, invoke the contextual menu on the DITA
map, and select Find Unreferenced Resources. This action can also be selected from the DITA Maps menu. This
action opens the Find Unreferenced Resources dialog box, which allows you to specify some search parameters:
DITA Maps - Provides a list of DITA maps to be included in the search and allows you to Add maps to the list or
Remove them.
Folders - Provides a list of folders to be included in the search and allows you to Add or Remove specific folders.
Filters - Provides three combo boxes that allow you to filter the search to include or exclude certain files or folders:
Include files - Allows you to filter specific files to include in the search.
Exclude files - Allows you to filter specific files to exclude from the search.
Exclude folders - Allows you filter specific folders to exclude from the search.
Note: In any of the filter combo boxes you can enter multiple filters by separating them with a comma
and you can use the ? and * wildcards. Use the drop-down arrow to select a previously used filter pattern.
Validate and Check for Completeness action allows you to validate a DITA map and configure the options for
Verifies that the file paths of the topic references are valid. For example, if an href attribute points to an invalid
file path, it is reported as an error in the message panel at the bottom of the editor.
Validates each referenced topic and map. Each topic file is opened and validated against the appropriate DITA DTD.
If another DITA map is referenced in the main one, the referenced DITA map is verified recursively, applying the
same algorithm as for the main map.
If errors or warnings are found, they are displayed in a separate message pane at the bottom of the editor and clicking
them takes you to the location of the error or warning in the file where it was found.
You can configure the validation process with the following options that are available in the DITA Map Completeness
Check dialog box:
Batch validate referenced DITA resources - This option decides the level of validation that applies to referenced
DITA files:
Check the existence of non-DITA references resources - Extends the validation of referenced resources to non-DITA
files.
If the check box is left unchecked (which is the default setting), the DITA files will be validated using the rules
defined in the DTD or XML Schema declared in the document.
If the check box is checked, the DITA files will be validated using rules defined in their associated validation
scenario.
Include remote resources - Enable this option if you want to check that remote referenced binary resources
(like images, movie clips, ZIP archives) exist at the specified location.
Use DITAVAL filters - The content of the map is filtered by applying a profiling condition set before validation.
You can choose between the following options:
From the current condition set - The map is filtered using the condition set applied currently in the DITA
Maps Manager view. Clicking the
Details icon opens a topic in the Oxygen XML Editor user guide that
explains how to create a profiling condition set.
From all available condition sets - For each available condition set, the map content is filtered using the condition
set before validation.
Check for duplicate topic IDs within the DITA map context - Checks for multiple topics with the same ID in the
context of the entire map.
Report links to topics not referenced in DITA maps - Checks that all referenced topics are linked in the DITA
map.
Identify possible conflicts in profile attribute values - When the profiling attributes of a topic contain values that
are not found in parent topic profiling attributes, the content of the topic is overshadowed when generating profiled
output. This option reports these possible conflicts.
Report attributes and values that conflict with profiling preferences - Looks for profiling attributes and values
not defined in the Profiling / Conditional Text preferences page (you can click the
button to open this preferences
page). It also checks if profiling attributes defined as single-value have multiple values set in the searched topics.
Additional schematron checks - Allows you to select a Schematron schema that Oxygen XML Editor uses for the
validation of DITA resources.
A task element specifies that a block of content contains the description of a task
A codeblock element specifies that a block of text consists of programming code
A uicontrol element specifies that a word is the name of a control in a computer GUI
The platform profiling attribute specifies that a particular piece of content applies only to certain computing
platforms
Semantic structure is important in a structured writing system because it allows both authors and readers to find content,
and it allows processing scripts to process various pieces of content differently, based on their role or meaning. This
can be used to do things such as filtering content related to a specific product so that you can produce documentation
on many products from the same source.
There can be many forms of semantics captured in a document set. DITA captures some of these in topics and some of
them in maps. If you are using a CMS, it may capture additional semantics.
Document Semantics
Documents consist of a number of different elements that may be made up of the same basic text structures as the rest
of the text, but have a special function within the structure of the document. For instance, both tables of contents and
indexes are lists, but they play a special role in the document. Chapters and sections are just sequences of paragraphs
and other text structures, yet they are meaningful in the structure of the document. In some cases, such as indexes and
tables of contents, these structures can be generated from semantic information embedded in the source. For instance,
a table of contents can be built by reading the titles of chapters and sections. DITA provides elements to describe common
document semantics.
Subject Matter Semantics
In some cases, the semantics of the content relate directly to the subject matter that the content describes. For instance,
DITA supports tags that allow you to mark a piece of text as the name of a window in a software application (wintitle),
or to mark a piece of text as applying only to a particular product.
Audience Semantics
In some cases, the semantics of the content relate to the audience that it is addressed to. For instance, a topic might be
addressed to a particular role, or to a person with a particular level of experience. DITA provides an audience element
to capture audience metadata.
Creating Topic Structures
Oxygen XML Editor provides a number of tools to help you create topic structures:
The Content Completion Assistant, which shows you which elements can be created at the current position
The Model view, which shows you the complete structure supported by the current element
The Outline view, which shows you the current structure of your document
The DITA toolbar, which helps you insert many common structures
Author mode is not a WYSIWYG view. It does not show you exactly what your content will look like when printed
or displayed on-screen. The appearance of your output is determined by the DITA publishing process, and your
organization may have modified that process to change how the output is displayed. Oxygen XML Editor has no
way of determining what your final output will look like or where line breaks or page breaks will fall. Treat Author
mode as a friendly visual editing environment, not a faithful preview of your output.
Your document is still an XML document. Author mode creates a visual representation of your document by applying
a CSS stylesheet to the XML. You can see the XML at any time by switching to Text mode. You, or someone in
your organization, can change how the Author view looks by changing the CSS stylesheet or providing an alternate
stylesheet.
Your aim in editing a DITA document is not to make it look right, but to create a complete and correct DITA XML
document. Author mode keeps you informed of the correctness of your content by highlighting XML errors in the
text and showing you the current status in a box at the top right of the editor window. Green means that your document
is valid, yellow means valid with warnings, and red means invalid. Warnings and errors are displayed when you
place the cursor on the error location.
Your XML elements may have attributes set on them. Conventionally, attributes are used to contain metadata that
is not displayed to the reader. By default, attributes are not displayed in the Author view (though there are some
exceptions) and cannot be edited directly in the Author view (though in some cases the CSS that drives the display
may use form controls to let you edit attributes directly). To edit the attributes of an element, place your cursor on
the element and press Alt+Enter to bring up the attribute editor. Alternatively, you can use the Attributes view to
edit attributes.
Tip: You can select Hints from the Styles drop-down menu (available on the Author Styles toolbar) to display
tooltips throughout the DITA document that offers additional information to help you with the DITA structure.
For more information, see the Selecting and Combining Multiple CSS Styles section.
The Enter key: In Author mode, the Enter key does not create line breaks, it brings up the Content Completion
Assistant to help you enter a new element. In XML, you do not use line breaks to separate paragraphs. You create
paragraphs by creating paragraph elements (element p in DITA) and tools insert the line breaks in the output and
on-screen.
The Content Completion Assistant not only suggests new elements you can add. If you press Enter at the end of
a block element (such as a paragraph) it suggests creating a new element of the same type. If you press Enter in the
middle of a block element, it suggests splitting that element into two elements.
A useful consequence of this behavior is that you can create a new paragraph simply by hitting Enter twice (just as
you might in a text editor).
As you highlight an element name, a basic description of the element is displayed. Select the desired element and
press Enter to create it.
To wrap an element around an existing element or piece of text, simply select it and press Enter and use the Content
Completion Assistant to choose the wrapper element.
The Model view: You can see the entire model of the current element by opening the Model view (Window > Show
View > Model, if the view is not already open). The Model view shows you what type of content the current element
can contain, all the child elements it can contain, all its permitted attributes, and their types.
Tip: You can also select Inline actions from the Styles drop-down menu (available on the Author Styles
toolbar) to display possible elements that are allowed to be inserted at various locations throughout the DITA
document. For more information, see the Selecting and Combining Multiple CSS Styles section.
If the DITA toolbar is not displayed, right-click anywhere on the toolbar area, select Configure Toolbars, and select
it from the displayed dialog box.
Note: The DITA toolbar contains a list of the most common elements and actions for DITA, such as inserting
an image, creating a link, inserting a content reference, or creating a table. It does not contain a button for every
possible DITA element. For a complete list of elements you can currently create, press Enter to bring up the
Content Completion Assistant.
The DITA Menu
Whenever the current document in the editor is a DITA document, the DITA menu is displayed in the menu bar. It
contains a large number of commands for inserting elements, creating content references and keys, edit DITA documents,
and controlling the display. These commands are specific to DITA and supplement the general editing commands
available for all document types. As with the DITA Toolbar, the DITA menu does not list every possible DITA element.
Reusable components - With this strategy, you create a new file for each piece of content that you want to reuse and
you insert references from the content of the reusable component files. For example, suppose that you have a disclaimer
that needs to be included in certain sections of your documentation. You can create a reusable component that contains
your disclaimer and reuse it as often as you need to. If the disclaimer ever needed to be updated, you only have to
edit it in one file.
Oxygen XML Editor creates a reference to the external content by adding a conref attribute to an element in the local
document. The conref attribute defines a link to the referenced content, made up of a path to the file and the topic ID
within the file. The path may also reference a specific element ID within the topic. Referenced content is not physically
copied to the referencing file. However, by default Oxygen XML Editor displays it in Author mode as if it is there in
the referencing file. If you do not want referenced content displayed, open the Preferences dialog box, go to Editor >
Edit modes > Author, and disable the Display referenced content option.
Note: A reference also displays tracked changes and comments that are included in the source fragment. To
edit these comments (or accept/reject changes) right-click the comment or tracked change and select Edit
Reference.
Tip: To search for references made through a direct content references, use the Search References action from
the contextual menu.
Creating a DITA Content Reference
DITA Content Reference
A DITA content reference, or conref, is one of the main content reuse features of DITA. It is a mechanism for re-using
the same content in multiple topics (or even in multiple locations within the same topic).
In order for a conref to be created, the source content must have an id attribute that the conref can reference.
Therefore, creating a conref requires that you add an id to the content to be reused before inserting a conref into
the topic that reuses the referenced content.
Assigning an ID to the Referenced Content
To add an id to a DITA element in a topic, place the cursor on the element and select
Edit Attributes from the
contextual menu (or simply press Alt+Enter) to open the in-place attribute editor. Enter id as the Name of the attribute
and a value of your choice in the Value field. You can also use the Attributes view to enter a value in the id attribute.
Note: The element may already have an id, since in some cases Oxygen XML Editor automatically generates
an id value when the id attribute is created.
Creating a Content Reference
To create a content reference (conref), follow these steps:
1. Make sure the element you want to reference has an id assigned to it.
2. In Author mode, place the cursor at the location where you want the reused content to be inserted.
3. Select the
Reuse Content action on the main toolbar (or from the DITA menu or Reuse submenu of the contextual
menu). The Reuse Content dialog box is displayed.
4. In the Location field of the Reuse Content dialog box, select the topic that contains the element you want to reference.
The elements that you can reference are presented in a table.
5. Select the Element ID of the element (or elements) from which you want to insert the content, and verify the content
in the Preview pane. The id value of the element that you select is automatically added to the Reference to (conref)
field.
Go to DITA >
Click the
Reuse Content.
Your selection at the top of the dialog box for choosing the content source determines whether Oxygen XML Editor
will insert a conref, conkeyref, or keyref.
If you select Location for the content source, a content reference (conref) will be inserted. If you select Key for the
content source, keys will be used to insert a content key reference (conkeyref) or a key reference (keyref).
Figure 269: The Reuse Content Dialog Box (with the Default Insert Content Reference Options
Displayed)
When Location is selected for the content source, a content reference (conref) will be inserted. Here you can specify
the path of the topic that contains the content you want to reference.
The dialog box offers the following options:
Select an element from the content source Section
Show elements of type
You can use this drop-down list to select specific types of elements to be displayed in the subsequent table. This
can help you narrow down the list of possible source elements that you can select.
Text Filter Field
You can also use the text filter field to narrow down the list of possible source elements to be displayed in the
subsequent table.
Element Table
Present all the element IDs defined in the source topic. Use this table to select the Element ID of the element
that you want to reference. You can select multiple contiguous elements to reference a block of content.
Preview Pane
Displays the content that will be references. If you select multiple elements in the element table, the content
from all the selected elements is displayed.
After you select a key, click OK to return to the Reuse Content dialog box.
When a key that references metadata has been selected, the Reuse Content dialog box offers the following additional
options for inserting a keyref:
Select an element from the content source Section
This section is not used when referencing metadata.
Reference details Section
Reference type
The type of reference that will be inserted. If you selected a key that does not reference a DITA resource, you
will notice that keyref value is automatically selected.
Reference to
Oxygen XML Editor automatically fills this text field with the value of the keyref attribute to be inserted.
Element name
Oxygen XML Editor automatically selects the element that is most commonly used for the selected type of key
reference, but you can use the drop-down list to choose another element to use for the reference.
Finalizing Your Content Reference Configuration
Once you click Insert or Insert and close, the configured content reference is inserted into your document.
You need a way to substitute the correct product name for each product.
One way to do this would be to use conditional profiling, as in this figure:
<p>The quick-heat feature allows
<ph product="basic">Basic Widget</ph>
<ph product="pro">Pro Widget</ph>
<ph product="enterprise">Enterprise Widget</ph>
to come up to temperature quickly.</p>
Linking in DITA
DITA provides support for various types of linking between topics, some of which is automated, while others are specified
by the author. Oxygen XML Editor provides support for all forms of linking in DITA.
Linking Between Parent, Child, and Sibling Topics
A DITA map creates a hierarchical relationship between topics. That relationship map expresses a narrative flow from
one topic to another, or it may be used as a classification system to help the reader find topics based on their classification,
without creating a narrative flow. Since there may be various types of relationships between topics in a hierarchy, you
may want to create links between topics in a variety of different ways. For instance, if your topics are supposed to be
organized into a narrative flow, you may want to have links to the next and previous topics in that flow. If your topics
are part of a hierarchical classification, you may want links from parent to child topics, and vice versa, but not to the
next and previous topics.
Parent, child, and sibling links are created automatically by the DITA output transformations (and may differ between
various output formats). The kinds of links that are created are determined by the DITA collection-type attribute.
In-Line Linking in the Content of a Topic
DITA supports linking within the text of a topic using the xref element. The destination of the link can be expressed
directly using the href attribute or indirectly using the keyref attribute. If you use the keyref attribute, you link
to a key rather than directly to a topic. That key is then assigned to a topic in a map that includes that topic. This means
that you can change the destination that a key points to by editing the key definition in the map or by substituting a
different map in the build.
Linking Between Related Topics
In addition to the relationships between topics that expressed by their place in the hierarchy of a map, a topic may be
related to other topics in various ways. For instance, a task topic may be related to a concept topic that gives the background
of the task, or to a reference topic that provides data needed to complete the task. Task topics may also be related to
other tasks in a related area, or concepts to related concepts.
Typically, they are grouped in a list at the end of the topic, although this depends on the behavior of the output
transformation. DITA provides two mechanisms for expressing relationships between topics at the topic level: the related
links section of a topic and relationship tables in maps.
Managing Links
Links can break for a variety of reasons. The topic that a link points to may be renamed or removed. A topic may be
used in a map that does not include a linked topic. A topic or a key may not exist in a map when a particular profile is
applied. The DITA Maps Manager provides a way to validate all the links in the documents that are included in the
map. This can include validating all the profiling conditions that are applied.
Key Definition - Assigns a key to a topic so that other topics can link to it. For more information, see Inserting and
Defining Keys in DITA Maps on page 488.
Key Reference - Created in an xref element and specifies the key to link to.
The key reference points to a key definition, and the key definition points to a topic. Key definitions are created in maps,
as an element on the topicref element that points to a topic. This allows you to assign a particular key to one topic
in one map and to another topic in another map. When a topic that links to that key is used in each of these maps, the
links work correctly in both maps.
Inserting a Link in Oxygen XML Editor
To insert a link in Author mode, use the actions available in the
Link submenu in the contextual menu or DITA menu). You can choose between the following types of in-line
links:
Cross Reference
Opens the Cross Reference (xref) dialog box that allows you to insert a link to a target resource at the current
location within a document. The target resource can be the location of a file or a key that is already defined in your
DITA map structure. Once the target resource has been selected, you can also target specific elements within that
resource. Depending on the context where it is invoked, the action inserts one of the following two elements:
xref - Used to link to other topics or another location within the same topic and points to the target using the
href attribute.
If the map is currently open in the DITA Maps Manager, double-click the map icon
to open the map in Author
mode. If it opens in Text mode, click Author at the bottom left to switch to Author mode.
2. Move the insertion point inside the map root element (usually map, but it might be bookmap, or another specialization
of the map element). The easiest way to do this is to click below the title of the map in the editor and then press the
up arrow once. Confirm that you are inside the map root element by checking the breadcrumbs at the top left of the
editor window. You should only see the name of the map root element.
3. Select the
Insert Relationship Table action on the toolbar or from the Relationship Table submenu of the
contextual menu. The Insert Relationship Table dialog box is displayed.
4. Make the appropriate selections in the Insert Relationship Table dialog box. See the DITA documentation for a
full explanation of the relationship table format and its options. Note that you can change all the selections that you
You can open the DITA map to edit the relationship table by doing one of the following:
If the map is currently open in the DITA Maps Manager, double-click the map icon
to open the map in Author
mode. If it opens in Text mode, click Author at the bottom left to switch to Author mode.
Browse for local file - Displays the Open dialog box to select a local file.
Browse for remote file - Displays the Open URL dialog box to select a remote file.
Browse for archived file - Opens the Archive Browser to select a file from an archive.
Browse Data Source Explorer - Opens the Data Source Explorer to select a file from a connected data source.
Search for file - Displays the Find Resource dialog box to search for a file.
Keyref
You can use the
Choose Key Reference button to open the Choose Key dialog box that presents the list of
keys available in the selected root map. Use this dialog box to insert an image element with a keyref attribute.
All keys that are presented in the dialog box are gathered from the root map of the current DITA map. Elements
that have the keyref attribute set are displayed as links. For more information, see the Adding an Image Using a
Key Reference on page 523 section.
Note: If your defined keys are not listed in this dialog box, it is most likely trying to gather keys from the
wrong root map. You can change the root map by using the Change Root Map link.
Tip: You can easily create a keydef element that targets an image by using the Key Definition action
from the Append Child or Insert After submenus.
3. If you are using profiling, add the alternative keydef elements and the appropriate profiling attributes:
<keydef keys="image.test" href="img/win/test.png" platform="windows" format="png">
<keydef keys="image.test" href="img/mac/test.png" platform="mac" format="png">
Tip: If you create the keydef element using the Key Definition action, you can use the Profiling tab of
the Insert Reference dialog box to easily add profiling attributes to the target.
4. If you are using separate maps, repeat in each map. For instance, if you are using a separate map for images in PDF
output, add a topic ref to that map like this:
<keydef keys="image.test" href="img/test.eps"
format="eps">
Tip: You can also use the Keyref section of the Insert Image dialog box to insert a keyref attribute inside
an image element.
Oxygen XML Editor displays the image in Author mode. Which image is displayed depends on the current profiling
set that is applied and which root map is being used to resolve references.
6. Configure your build so that the appropriate image map is included for each output type and/or the appropriate
profiling conditions are applied to each output.
DITA simple table model - This is the most commonly used model for basic tables.
OASIS Exchange Table Model (a subset of the CALS table model) - This is used for more advanced functionality.
If you are using a specialized DITA vocabulary, it may contain specialized versions of these table models.
Since DITA is a structured format, you can only insert a table in places in the structure of a topic where tables are
allowed. The Oxygen XML Editor DITA toolbar provides support for entering and editing tables. It also helps to indicate
where you are allowed to insert a table or its components by disabling the appropriate buttons.
The DITA toolbar showing the insert table button available and the table editing buttons are disabled:
Embed MathML directly into a DITA topic. You can start with the Framework templates / DITA / topic / Composite
with MathML document template, available from the New file action wizard.
Note: MathML equations contained in DITA topics can only be published out-of-the-box in PDF using the
DITA PDF transformation scenario. For other publishing formats, you must employ additional customizations
for handling MathML content.
You can also assign keys to a topic (and insert the topicref element in its DITA map) by using the Keys tab in the
Edit Properties dialog box. In the DITA Maps Manager, invoke the contextual menu on the topic for which you want
to assign a key and select
field.
Edit Properties. Go to the Keys tab and enter the name of the key in the Define keys
Once a key is assigned to a topic, you can use it to reference that topic for various purposes:
You can create a link to it using <xref keyref="feature.quick-heat"/>. This allows you to change
the target of the link by changing the topic that is pointed to by the key (for example, by profiling).
You can use it in a map to create a reference to a topic by key: <topicref keyref="feature.quick-heat".
This allows you to change which topic is inserted in the map by the build, by changing the topic that is pointed to
by the key.
You can use it to insert a content reference. In this case, the content reference uses the key to locate the topic to pull
content from. It uses a conkeyref attribute: <procedure
conkeyref="feature.quick-heat/preheat-procedure"/>. In this example, feature.quick-heat
is the key, and preheat-procedure is the id of a procedure within the topic for that key. Using this mechanism,
you could have multiple versions of the preheat procedure in various topics and control which one is inserted by
changing the topic that is pointed to by the key.
Use the
Configure Transformation Scenario(s) (Ctrl Shift C (Meta Shift C on OS X)) action from the
Transformation toolbar or the Document > Transformation menu. Then click the New button and select DITA
OT Transformation.
Use the
Apply Transformation Scenario(s) (Ctrl Shift T (Meta Shift T on OS X)) action from the
Transformation toolbar or the Document > Transformation menu. Then click the New button and select DITA
OT Transformation.
Global Options - The scenario is saved in the global options that are stored in the user home directory and is not
accessible to other users.
Project Options - The scenario is stored in the project file and can be shared with other users. For example, if your
project is saved on a source versioning/sharing system (CVS, SVN, Source Safe, etc.) or a shared folder, your team
can use the scenarios that you store in the project file.
The lower part of the dialog box contains the following tabs (only those that are appropriate for the chosen output type
will be displayed):
Skins (Available for WebHelp and WebHelp with Feedback output types).
FO Processor (Available for PDF output types).
Parameters
Filters
Advanced
Output
For information about creating an entirely new DITA OT transformation, see Creating a DITA OT Customization Plugin
on page 545 and Installing a Plugin in the DITA Open Toolkit on page 547.
The FO Processor Tab
This tab allows you to select an FO Processor, when you choose to generate PDF output.
Apache FOP - The default processor that comes bundled with Oxygen XML Editor.
XEP - The RenderX XEP processor.
If XEP is already installed, Oxygen XML Editordisplays the detected installation path under the drop-down menu.
XEP is considered installed if it was detected in one of the following sources:
Environment variable set by Antenna House installation (the newest installation version will be used).
Antenna House was added as an external FO Processor in the Oxygen XML Editor preferences pages.
To further customize the PDF output obtained from the Antenna House processor:
Use DITAVAL file - If you already have a DITAVAL file associated with the DITA map, you can specify the file
to be used when filtering content. An editor variable can be inserted for the file path by using the
Insert Editor
Variables button. You can find out more about constructing a DITAVAL file in the DITA OT Documentation.
Use profiling condition set - Sets the profiling condition set that will apply to your transformation.
Exclude from output all elements with any of the following attributes - By using the
New,
Edit, or
Delete buttons at the bottom of the pane, you can configure a list of attributes (name and value) to exclude all
elements that contain any of these attributes from the output.
Custom build file - If you use a custom DITA-OT build file, you can specify the path to the customized build file.
If empty, the build.xml file from the dita.dir parameter that is configured in the Parameters tab is used. An
editor variable can be inserted for the file path by using the
Insert Editor Variables button.
Build target - Optionally, you can specify a build target for the build file. If no target is specified, the default init
target is used.
Additional arguments - You can specify additional command-line arguments to be passed to the Ant transformation
(such as -verbose).
Ant Home - You can choose between the default or custom Ant installation to run the transformation. The default
path can be configured in the Ant preferences page.
Java Home - You can choose between the default or custom Java installation to run the transformation. The default
path is the Java installation that is used by Oxygen XML Editor.
Note: It may be possible that the used Java version is incompatible with the DITA Open Toolkit engine.
For example, DITA OT 1.8.5 and older requires Java 1.6 or later, while DITA OT 2.0 and newer requires
Java 1.7 or newer. Thus, if you encounter related errors running the publishing, consider installing a Java
VM that is supported by the DITA OT publishing engine and using it in the Java Home text field.
JVM Arguments - This parameter allows you to set specific parameters for the Java Virtual Machine used by Ant.
For example, if it is set to -Xmx384m, the transformation process is allowed to use 384 megabytes of memory. When
performing a large transformation, you may want to increase the memory allocated to the Java Virtual Machine.
This will help avoid Out of Memory error messages (OutOfMemoryError).
Libraries - By default, Oxygen XML Editor adds (as high priority) libraries that are not transformation-dependent
and also patches for certain DITA Open Toolkit bugs. You can use this button to specify additional libraries (jar
files or additional class paths) to be used by the Ant transformer.
Base directory - All the relative paths that appear as values in parameters are considered relative to the base directory.
The default value is the directory where the transformed map is located. An editor variable can be inserted for the
path by using the
Insert Editor Variables button.
Temporary files directory - This directory is used to store pre-processed temporary files until the final output is
obtained. An editor variable can be inserted for the path by using the
Insert Editor Variables button.
Output folder - The folder where the content of the final output is stored. An editor variable can be inserted for the
path by using the
Insert Editor Variables button.
Note: If the DITA map or topic is opened from a remote location or a ZIP file, the parameters must specify
absolute paths.
Open in Browser/System Application - If enabled, Oxygen XML Editor automatically opens the result of the
transformation in a system application associated with the file type of the result (for example, .pdf files are usually
opened in the Acrobat Reader application).
Note: To set the web browser that is used for displaying HTML/XHTML pages, open the Preferences
dialog box, then go to Global and set it in the Default Internet browser field.
Saved file - When Open in Browser/System Application is selected, this button can be used to specify
that Oxygen XML Editor automatically opens the file specified in the Save As text field at the end of
the transformation.
Other location - When Open in System Application is selected, this option can be used to specify that
Oxygen XML Editor opens the file specified here. The file path can include special Oxygen XML Editor
editor variables or custom editor variables by using the
Insert Editor Variables button.
Note: If you use the built-in Ant 1.8.2 build tool that comes bundled with Oxygen XML Editor, it is located in
the [OXYGEN_DIR]/tools/ant directory. Any additional libraries for Ant must be copied to the Oxygen
XML Editor Ant lib directory.
DITA to PDF Output Customization
This section includes topics about customizing DITA to PDF output.
Creating a Customization Directory for PDF Output
DITA Open Toolkit PDF output can be customized in several ways:
Creating a DITA Open Toolkit plugin which adds extensions to the PDF plugin. More details can be found in the
DITA Open Toolkit user manual.
Creating a customization directory and using it from the PDF transformation scenario. A small example of this
procedure can be found below.
The following procedure explains how to do a basic customization of the PDF output by setting up a customization
directory. An example of a common use case is embedding a company logo image in the front matter of the book.
1. Copy the entire directory: DITA_OT_DIR\plugins\org.dita.pdf2\Customization to another location
(for instance, C:\Customization).
2. Copy your logo image to: C:\Customization\common\artwork\logo.png.
3. Rename C:\Customization\catalog.xml.orig to: C:\Customization\catalog.xml.
4. Open the catalog.xml in Oxygen XML Editor and uncomment this line:
<!--uri name="cfg:fo/xsl/custom.xsl" uri="fo/xsl/custom.xsl"/-->
7. Edit the DITA Map to PDF transformation scenario and in the Parameters tab, set the customization.dir parameter
to C:\Customization.
Header and Footer Customization in PDF Output
The XSLT stylesheet DITA_OT_DIR/plugins/org.dita.pdf2/xsl/fo/static-content.xsl contains
templates which output the static header and footers for various parts of the PDF like the prolog, table of contents, front
matter or body.
The templates for generating a footer for pages in the body are called insertBodyOddFooter or
insertBodyEvenFooter.
These templates get the static content from resource files which depend on the language used for generating the PDF.
The default resource file is DITA_OT_DIR/plugins/org.dita.pdf2/cfg/common/vars/en.xml. These
resource files contain variables like Body odd footer which can be set to specific user values.
Instead of modifying these resource files directly, they can be overwritten with modified versions of the resources in a
PDF customization directory as explained in Creating a Customization Directory for PDF Output on page 535.
Adding a Watermark to PDF Output
To add a watermark to the PDF output of a DITA map transformation, follow these steps:
6. In the same file (static-content.xsl), add a call to this template before the <fo:block> tag in each of the
header templates (insertBodyOddHeader, insertBodyEvenHeader, insertBodyFirstHeader,
insertBodyLastHeader, insertTocOddHeader, insertTocEvenHeader, and
insertBodyFootnoteSeparator), or in each of the footer templates (insertBodyFirstFooter,
insertBodyLastFooter, insertBodyOddFooter, insertBodyEvenFooter, insertTocOddFooter,
insertTocEvenFooter, and insertBodyFootnoteSeparator). The call would look like this:
<xsl:call-template name="insertImage"/>
Note: If you add the call in both the header and footer templates, the watermark image will be displayed
twice in each page of the output.
7. Edit a DITA Map PDF transformation scenario and in the Parameters tab, set the value of the customization.dir
parameter to something like:
${frameworksDir}/dita/DITA-OT/plugins/org.dita.pdf2/Customization, where
${frameworksDir}/dita/DITA-OT is pointing to your DITA_OT_DIR.
8. Apply the transformation scenario.
Force Page Breaks Between Two Block Elements
Suppose that at some point in your DITA content you have two block level elements, such as two paragraphs:
<p>First para</p>
<p>Second para</p>
and you want to force a page break between them in the PDF output.
Here is how you can implement a DITA Open Toolkit plugin that would achieve this:
2. Locate the DITA Open Toolkit distribution and in the plugins directory create a new plugin folder named
pdf-page-break, for example.
3. In this new folder, create a new plugin.xml file with the content:
<plugin id="com.yourpackage.pagebreak">
<feature extension="package.support.name" value="Force Page Break Plugin"/>
<feature extension="package.support.email" value="[email protected]"/>
<feature extension="package.version"value="1.0.0"/>
<feature extension="dita.xsl.xslfo" value="pageBreak.xsl" type="file"/>
</plugin>
The most important feature in the plugin is that it will add a new XSLT stylesheet to the XSL processing that produces
the PDF content.
4. In the same folder, create an XSLT stylesheet named pageBreak.xsl with the following content:
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:fo="http://www.w3.org/1999/XSL/Format"version="1.0">
<xsl:template match="processing-instruction('pagebreak')">
<fo:block break-after="page"/>
</xsl:template>
</xsl:stylesheet>
to:
<variable id="notice Note Image Path">Customization/OpenTopic/common/artwork/notice.gif</variable>
The font-family is defined to be monospace, but monospace is just an alias, it is not a physical font name. So another
stage in the PDF generation takes this monospace alias and looks in the font-mappings.xml.
If it finds a mapping like this:
<aliases>
<alias name="monospace">Monospaced</alias>
</aliases>
then it looks to see if the Monospaced has a logical-font definition and if so it will use the physical-font specified there:
<logical-font name="Monospaced">
<physical-font char-set="default">
<font-face>Courier New, Courier</font-face>
</physical-font>
............
</logical-font>
Important:
If no alias mapping is found for a font-family specified in the XSLT stylesheets, the processing defaults to
Helvetica.
Adding a Watermark to XHTML Output
To add a watermark to the XHTML output of a DITA map transformation, follow these steps:
1. Create a custom CSS stylesheet that includes the watermark image, as in the following example:
body {
background-image: url(MyWatermarkImage.png);
}
2. Edit a DITA Map XHTML transformation scenario and in the Parameters tab set the value of the args.css
parameter as the path to your watermark image.
3. Set the value of the args.copycss parameter to yes.
4. Apply the transformation scenario.
5. Copy the watermark image in the output directory of the transformation scenario, next to the CSS file created in step
1.
DITA Map to PDF WYSIWYG Transformation
Oxygen XML Editor comes bundled with a DITA OT plugin that converts DITA maps to PDF using a CSS layout
processor. Oxygen XML Editor supports the following processors (not included in the Oxygen XML Editor installation
kit):
Prince Print with CSS - A third-party component that needs to be purchased from http://www.princexml.com.
Antenna House Formatter - A third-party component that needs to be purchased from
http://www.antennahouse.com/antenna1/formatter/.
css.processor.path.prince (if you are using the Prince Print with CSS processor) - Specifies the path
to the Prince executable file that will be run to produce the PDF. If you installed Prince using its default settings,
you can leave this blank.
css.processor.path.antenna-house (if you are using the Antenna House Formatter processor) Specifies the path to the Antenna House executable file that will be run to produce the PDF. If you installed
Antenna House using its default settings, you can leave this blank.
show.changes.and.comments - When set to yes, the user comments and tracked changes are shown in
the output. The default value is no.
The profiling attributes, and their potential values, that appear in this dialog box depend on what has been configured
in Oxygen XML Editor. The content of the dialog box is determined as follows:
If your root DITA map references a DITA subject scheme map that defines values for the profiling attributes, those
values are used. In the image above, which is taken from the Oxygen XML Editor documentation project, values
are defined for seven different products, but none for other profiling attributes, which are therefore omitted from the
dialog box.
If your project defines project-level configuration values for the profiling attributes, those values are used.
If Oxygen XML Editor defines global-level configuration values for the profiling attributes, they are used.
Otherwise, a basic default set of profiling attributes and values are available.
Edit Properties
from the contextual menu, and go to the Profiling tab.
b) To profile DITA content in Author mode, highlight the content and select Edit Profiling Attributes from the
contextual menu.
c) To profile specific XML elements in Author mode, right-click inside the element and select Edit Profiling
Attributes or use the Attributes view to set the profiling attributes on the element at the current cursor position.
Enable the Show Profiling Attributes option to display the profiling markup in the Author editing mode.
When you edit a DITA topic in the Text or Author mode, Oxygen XML Editor collects all the profiling values from
the Subject Scheme Map that is referenced in the map that is currently opened in the DITA Maps Manager. The values
of profiling attribute defined in a Subject Scheme Map are available in the Edit Profiling Attribute dialog box, regardless
of their mapping in the Profiling/Conditional Text preferences page. They are also available as proposals for values in
the Content Completion Assistant.
In the example above, the values therapist, oncologist, physicist, and so on, are displayed
in the content completion window as values for the audience attribute.
Consider that you have the following fragment in a topic:
<p audience="neuro-surgeon">Some text.. </p>
When you define a DITAVAL filter, you can, for instance, exclude anything that is profiled as surgeon:
<val>
<prop action="exclude" att="audience" val="surgeon"/>
</val>
If you then transform the main DITA map specifying the DITAVAL filter file in the transformation scenario, the p
element should be excluded from the output. Therefore, excluding the surgeon audience also excludes
neuro-surgeon and plastic-surgeon from the output. More details about how hierarchical filtering and Subject
Scheme Maps should work are found in the following
specification:http://docs.oasis-open.org/dita/v1.2/os/spec/langref/subjectScheme.html#subjectSchemehttp://docs.oasis-open.org/dita/v1.2/os/spec/langref/subjectScheme.html%23subjectScheme
The most important extensions in it are the references to the XSLT stylesheets that will be used to style the HTML
and PDF outputs.
You can find other DITA OT plugin extension points here:
http://dita-ot.sourceforge.net/1.5.3/dev_ref/extension-points.html
3. Create an XSLT stylesheet to customize the output types. In our example, to customize the HTML output we need
to create an XSLT stylesheet called xhtmlHighlight.xsl (in the same plugin folder).
Tip: You can use the Find/Replace in Files to find an XSLT stylesheet with content that is similar to the
desired output and use it as a template to overwrite parts of your stylesheet. In our example we want to
overwrite the creation of the HTML content from a DITA codeblock element. Since a DITA codeblock
element has the class attribute value + topic/pre pr-d/codeblock we can take part of the class
attribute value (topic/pre) and search the DITA OT resources for a similar stylesheet.
Our search found the XSLT stylesheet
DITA_OT_DIR/org.dita.xhtml/xsl/xslhtml/dita2htmlImpl.xsl, which contains:
You could also use another XSLT template that applies the XSLTHL library as a Java extension to style the
content.
4. Create additional XSLT stylesheets to customize all other desired output types. In our example, to customize the
PDF output we need to create an XSLT stylesheet called pdfHighlight.xsl (in the same plugin folder).
In this case we found an appropriate XSLT stylesheet
DITA_OT_DIR/plugins/legacypdf/xslfo/dita2fo-elems.xsl to use as a template that we use to
overwrite our pdfHighlight.xsl stylesheet, which results in the following:
<xsl:template match="*[contains(@class,' topic/pre ')]">
<xsl:call-template name="gen-att-label"/>
<fo:block xsl:use-attribute-sets="pre">
<!-- setclass -->
<!-- set id -->
<xsl:call-template name="setscale"/>
<xsl:call-template name="setframe"/>
<xsl:apply-templates/>
</fo:block>
</xsl:template>
Note: You can edit the newly created stylesheets to customize different outputs in a variety of ways. For
example, in our case you could edit the xhtmlHighlight.xsl or pdfHighlight.xsl stylesheets that we created
to customize various colors for syntax highlighting.
5. To install the created plugin in the DITA OT, run the predefined transformation scenario called Run DITA OT
Integrator by executing it from the
visible, enable the Show all scenarios action that is available in the
settings drop-down menu. For more
information, see Installing a Plugin in the DITA Open Toolkit on page 547.
Results of running the integrator using our example:
XSLT content is applied with priority when publishing to both HTML and PDF outputs.
a. For the HTML output, in the XSLT stylesheet DITA_OT_DIR/xsl/dita2html-base.xsl a new import
automatically appeared:
<xsl:import href="../plugins/com.oxygenxml.highlight/xhtmlHighlight.xsl"/>
This import is placed after all base imports and thus has a higher priority. See more about imported template
precedence in the XSLT specs: http://www.w3.org/TR/xslt#import
b. Likewise, for the PDF output, in the top-level stylesheet
DITA_OT_DIR/plugins/org.dita.pdf2/xsl/fo/topic2fo_shell_fop.xsl a new import
statement appeared:
<xsl:import href="../../../com.oxygenxml.highlight/pdfHighlight.xsl"/>
Important: The folder where the DITA OT is located needs to have full write access permissions set to it.
For example if you are integrating plugins in the DITA OT folder bundled with Oxygen XML Editor and
if you are running on Windows and your application is installed in the Program Files folder, you can start
the Oxygen XML Editor main executable with administrative rights in order for the integrator process to be
able to modify resources in the DITA OT folder.
Starting with version 17.0, Oxygen XML Editor detects the transformation type (transtype) declarations from
DITA OT plugins and presents descriptions, which are contributed in the transtype declarations, in the DITA
Transformation Type dialog box. Oxygen XML Editor also shows the contributed parameters from DITA OT
plugins in the Parameters tab in the Edit DITA Scenario dialog box.
3. If the plugin contributed a new transformation type that is not detected (for instance, if you are using a previous
version of Oxygen XML Editor that does not detect the transtype declarations), you can create a new DITA OT
transformation scenario with a predefined type that is similar to the new transformation type. Then edit the
transformation scenario, and in the Parameters tab add a transtype parameter with the value of the new
transformation type.
Note: A transformation type can also extend another transtype. For example, the pdf-prince transtype
extends a commons transformation type that contains all the common DITA OT parameters.
Example:
<plugin id="com.oxygenxml.pdf.prince">
<!-- extensions -->
<feature extension="dita.conductor.transtype.check" value="pdf-prince" type="txt"/>
<feature extension="dita.conductor.target.relative" value="integrator.xml" type="file"/>
<feature extension="dita.transtype.print" value="pdf-prince"/>
<transtype name="pdf-prince"extends="commons" desc="PDF (Prince XML - Experimental)">
<param name="princeExecPath" type="file" desc="Path to the Prince executable file (eg:
"c:\path\to\prince.exe" on Windows) which should be run to produce the PDF"/>
</ Transtype>
</plugin>
If the DTD that define the extension elements are located in a folder outside the DITA Open Toolkit folder, add
new rules to the DITA OT catalog file for resolving the DTD references from the DITA files that use the specialized
elements to that folder. This allows correct resolution of DTD references to your local DTD files and is needed
for both validation and transformation of the DITA maps or topics. The DITA OT catalog file is called
catalog-dita.xml and is located in the root folder of the DITA Open Toolkit.
If there is specialized processing provided by XSLT stylesheets that override the default stylesheets from DITA
OT, these new stylesheets must be called from the Ant build scripts of DITA OT.
Important: If you are using DITA specialization elements in your DITA files, it is recommended that
you activate the Enable DTD/XML Schema processing in document type detection checkbox in the
Document Type Association preferences page.
In your specialization plugin directory, create a folder called template_folders, which would contain all
the folders with new file templates. In Oxygen XML Editor, the templates contributed by the plugin will be
available in the New document wizard.
Metadata
Metadata is a broad concept that describes data that explains or identifies other data. Metadata can be used for many
purposes, from driving automation of document builds to enabling authors and readers to find content more easily. DITA
provides a number of different types of metadata, each of which has different uses and is created in different places and
ways. Some of the most important forms of metadata in DITA are topic and taxonomy.
Topic Metadata
Topic metadata describes the topic and what it is about. Topic metadata can be inserted in the prolog element of a
topic or inside the topicref element that points to a topic from a map. In other words, metadata about the topic can
be asserted by the topic itself, or can be assigned to it by the map that includes it in the build. This allows various different
maps to assign metadata to the same topic. This may be appropriate where you want to describe a topic differently in
various documents.
Taxonomy and Subject Scheme
A taxonomy is a controlled vocabulary. It can be used to standardize how many things in your content and metadata are
named. This consistency in naming can help ensure that automated processes work correctly, and that consistent
terminology is used in content, and in metadata. In DITA, taxonomies are created using subject scheme maps. When
you are authoring, many of the values you choose from have been defined in subject scheme maps.
In the header of a topic. In paginated media, such as a printed book or a PDF, this results in an index entry that points
to the page in which the topic starts, even if it is not the page in which the indexed term occurs.
In the topicref element in a map that references the topic. This applies those index terms to that topic only when
used in that map, allowing you to index topics differently in various publications. In paginated media, index entries
point to the page in which the topic starts.
In the body of a topic. In paginated media, this results in an index entry that points to the page in which the
indexterm element occurs, even if that is not the page in which the topic starts.
To add index terms to the text of a topic of the topic header, create the elements, as you normally would, in Oxygen
XML Editor. To add index terms to a map, open the map in the editor and add the elements, as you normally would, in
a topic.
In some media, indexes will be generated automatically when index entries are found in the source. For other media,
such as books, you may need to tell DITA where to place the index. For instance, to add an index to a bookmap, you
need to add an indexlist element to the backmatter of the book.
Editing
Publishing [Latest
DITA Open Toolkit
2.x is used.]
No specific support
implemented
Troubleshooting specialization
No specific support
implemented
Special rendering in
PDF and
XHTML-based
outputs
Special rendering in
PDF and
XHTML-based
outputs
SVG domain
Special rendering in
PDF and
XHTML-based
outputs
Editing
Publishing [Latest
DITA Open Toolkit
2.x is used.]
Special rendering in
PDF and
XHTML-based
outputs
No specific support
implemented
Scoped keys
Partially implemented
(Various issues may
still be encountered)
Key-based cross deliverable addressing Special display for references to DITA maps with
scope="peer" and a defined keyscope
Partially implemented
(Various issues may
still be encountered)
Not implemented.
Implemented
Not implemented
Implemented
Chapter
8
Document Types (Frameworks)
Topics:
A default grammar used for validation and content completion in both Author
mode and Text mode.
CSS stylesheets for rendering XML documents in Author mode.
User actions invoked from toolbars or menus in Author mode.
Predefined scenarios used for transformations for the class of XML
documents defined by the document type.
XML catalogs.
Directories with file templates.
User-defined extensions for customizing the interaction with the content
author in Author mode.
Oxygen XML Editor comes with built-in support for many common document
types. Each document type is defined in a framework. You can create new
frameworks or make changes to existing frameworks to suit your individual
requirements.
To see a video on configuring a framework in Oxygen XML Editor, go to
http://oxygenxml.com/demo/FrameworkConfiguration.html.
DocBook 4 - A document type standard for books, articles, and other prose documents (particularly technical
documentation).
DocBook 5 - An enhanced (version 5) document type standard designed for a variety of documents (particularly
technical documentation).
DITA - An XML-based architecture designed for authoring, producing, and delivering technical information.
DITA Map - A document type that collects and organizes references to DITA topics or other maps.
XHTML - Extensible HyperText Markup Language includes the same depth of expression as HTML, but also conforms
to XML syntax.
TEI ODD - Text Encoding Initiative One Document Does it all is an XML-conformant specification that allows you
to create TEI P5 schema in a literate programming style.
TEI P4 - The Text Encoding Initiative guidelines is a standard for the academic community that collectively define
an XML format for text that is primarily semantic rather than presentational.
TEI P5 - The Text Encoding Initiative guidelines is a standard for the academic community that collectively define
an XML format for text that is primarily semantic rather than presentational.
JATS - The NISO Journal Article Tag Suite is a technical standard that defines an XML format for scientific literature.
EPUB (NCX, OCF, OPF 2.0 & 3.0) - A standard for e-book files.
DocBook Targetset - For resolving cross-references when using olinks.
Ant Build Scripts - A tool for automating software build processes, written in Java and primarily intended for use
with Java.
XSLT Stylesheets - A document type that provides a visual mode for editing XSLT stylesheets.
WSDL - Web Services Description Language is an XML language for describing the functionality offered by a web
service.
Schematron - For making assertions about the presence or absence of patterns in XML documents. This document
type applies to the ISO Schematron version.
Schematron Quick Fixes (SQF) - An extension of the ISO standard Schematron, allows developers to define QuickFixes
for Schematron errors.
StratML (Part 1 & 2) - Part 1 and 2 of the Strategy Markup Language specification.
XProc - A document type for processing XProc script files.
XML Schema - Documents that provide support for editing annotations.
SVG - Scalable Vector Graphics is a language for describing two-dimensional graphics in XML.
MathML - Mathematical Markup Language (2.0 and 3.0) is an application of XML for describing mathematical
notations.
XLIFF (1.2 & 2.0) - XML Localization Interchange File Format is a standard for passing data between tools during
a localization process.
XQuery - The common query language for XML.
CSS - Cascading Style Sheets is a language used for describing the look and formatting of a document.
LESS - A dynamic style sheet language that can be compiled into CSS.
Relax NG Schema - A schema language that specifies a pattern for the structure and content of an XML document.
NVDL Schema - Namespace Validation Dispatching Language allows you to specify sections of XML documents
to be validated against various schemas.
The default schema that is used if one is not detected in the DocBook 4 file is docbookxi.dtd and it is stored in
[OXYGEN_DIR]/frameworks/docbook/4.5/dtd/.
The default CSS files used for rendering DocBook content in Author mode are stored in
[OXYGEN_DIR]/frameworks/docbook/css/.
The default XML catalog, catalog.xml, is stored in [OXYGEN_DIR]/frameworks/docbook/.
To watch our video demonstration about editing DocBook documents, go to
http://oxygenxml.com/demo/DocBook_Editing_in_Author.html.
DocBook 4 Author Mode Actions
A variety of actions are available in the DocBook 4 framework that can be added to the DocBook4 menu, the Author
Custom Actions toolbar, the contextual menu, and the Content Completion Assistant.
DocBook 4 Toolbar Actions
The following default actions are readily available on the DocBook (Author Custom Actions) toolbar when editing in
Author mode (by default, most of them are also available in the DocBook4 menu and in various submenus of the
contextual menu):
Bold
Emphasizes the selected text by surrounding it with <emphasis role="bold"> tag. You can use this action
on multiple non-contiguous selections.
Italic
Emphasizes the selected text by surrounding it with <emphasis role="italic"> tag. You can use this action
on multiple non-contiguous selections.
Underline
Emphasizes the selected text by surrounding it with <emphasis role="underline"> tag. You can use this
action on multiple non-contiguous selections.
Link Actions Drop-Down Menu
The following link actions are available from this menu:
When invoked on a single selection, an ID is generated for the selected element at the cursor position.
When invoked on a block of selected content, IDs are generated for all top-level elements and elements from
the list in the ID Options dialog box that are found in the current selection.
Note: The Generate IDs action does not overwrite existing ID values. It only affects elements that do not
already have an id attribute.
When invoked on a single selection, an ID is generated for the selected element at the cursor position.
When invoked on a block of selected content, IDs are generated for all top-level elements and elements from
the list in the ID Options dialog box that are found in the current selection.
Note: The Generate IDs action does not overwrite existing ID values. It only affects elements that do not
already have an id attribute.
webhelp.footer.include
Specifies whether or not to include footer in each WebHelp page. Possible values: yes, no. If set to no, no footer
is added to the WebHelp pages. If set to yes and the webhelp.footer.file parameter has a value, then the
content of that file is used as footer. If the webhelp.footer.file has no value then the default Oxygen XML
Editor footer is inserted in each WebHelp page.
webhelp.logo.image (not available for the WebHelp Mobile transformation)
Specifies a path to an image displayed as a logo in the left side of the output header.
webhelp.logo.image.target.url (not available for the WebHelp Mobile transformation)
Specifies a target URL that is set on the logo image. When you click the logo image, you will be redirected to this
address.
webhelp.search.ranking (not available for the WebHelp Mobile transformation)
If this parameter is set to false then the 5-star rating mechanism is no longer included in the search results that
are displayed on the Search tab (default setting is true).
2. Generate a new XSLT stylesheet from the title spec file from the previous step.
Apply [OXYGEN_DIR]/frameworks/docbook/xsl/template/titlepage.xsl to the title spec file.
The result is an XSLT stylesheet (for example, mytitlepages.xsl).
3. Import mytitlepages.xsl in a DocBook customization layer.
The customization layer is the stylesheet that will be applied to the XML document. The mytitlepages.xsl
should be imported with an element like:
<xsl:import href="dir-name/mytitlepages.xsl"/>
2. In the CSS, specify where this font is used. To set it as default for h1 elements, use the font-family rule, as in
the following example:
h1 {
font-size:20pt;
margin-bottom:20px;
font-weight: bold;
font-family: "MyFont";
text-align: center;
}
Article
Article with MathML
Article with SVG
Article with XInclude
Book
Book with XInclude
Chapter
Section
Set of Books
You can form a cross reference to that chapter by adding an olink, as in the following example:
You may need to update your
<olink targetdoc="MailAdminGuide" targetptr="user_accounts">user accounts
</olink>
when you get a new machine.
When invoked on a single selection, an ID is generated for the selected element at the cursor position.
When invoked on a block of selected content, IDs are generated for all top-level elements and elements from
the list in the ID Options dialog box that are found in the current selection.
Note: The Generate IDs action does not overwrite existing ID values. It only affects elements that do not
already have an id attribute.
Refresh References
You can use this action to manually trigger a refresh and update of all referenced resources.
Tags display mode Submenu
Full Tags with Attributes - Displays full tag names with attributes for both block level and in-line level elements.
Full Tags - Displays full tag names without attributes for both block level and in-line level elements.
Block Tags - Displays full tag names for block level elements and simple tags without names for in-line level
elements.
Inline Tags - Displays full tag names for inline level elements, while block level elements are not displayed.
Partial Tags - Displays simple tags without names for in-line level elements, while block level elements are
not displayed.
When invoked on a single selection, an ID is generated for the selected element at the cursor position.
When invoked on a block of selected content, IDs are generated for all top-level elements and elements from
the list in the ID Options dialog box that are found in the current selection.
Note: The Generate IDs action does not overwrite existing ID values. It only affects elements that do not
already have an id attribute.
webhelp.footer.include
Specifies whether or not to include footer in each WebHelp page. Possible values: yes, no. If set to no, no footer
is added to the WebHelp pages. If set to yes and the webhelp.footer.file parameter has a value, then the
content of that file is used as footer. If the webhelp.footer.file has no value then the default Oxygen XML
Editor footer is inserted in each WebHelp page.
webhelp.logo.image (not available for the WebHelp Mobile transformation)
Specifies a path to an image displayed as a logo in the left side of the output header.
webhelp.logo.image.target.url (not available for the WebHelp Mobile transformation)
Specifies a target URL that is set on the logo image. When you click the logo image, you will be redirected to this
address.
webhelp.search.ranking (not available for the WebHelp Mobile transformation)
If this parameter is set to false then the 5-star rating mechanism is no longer included in the search results that
are displayed on the Search tab (default setting is true).
webhelp.search.japanese.dictionary
The file path of the dictionary that will be used by the Kuromoji morphological engine that Oxygen XML Editor
uses for indexing Japanese content in the WebHelp pages. This indexer does not come bundled with Oxygen XML
Editor or the Oxygen XML WebHelp plugin. To use it, you need to download it from
http://mvnrepository.com/artifact/org.apache.lucene/lucene-analyzers-kuromoji/4.0.0 and add it in the
DITA_OT_DIR/plugins/com.oxygenxml.webhelp/lib directory.
use.stemming
Controls whether or not you want to include stemming search algorithms into the published output (default setting
is false).
clean.output
Deletes all files from the output folder before the transformation is performed (only no and yes values are valid
and the default value is no).
2. Generate a new XSLT stylesheet from the title spec file from the previous step.
Apply [OXYGEN_DIR]/frameworks/docbook/xsl/template/titlepage.xsl to the title spec file.
The result is an XSLT stylesheet (for example, mytitlepages.xsl).
3. Import mytitlepages.xsl in a DocBook customization layer.
2. In the CSS, specify where this font is used. To set it as default for h1 elements, use the font-family rule, as in
the following example:
h1 {
font-size:20pt;
margin-bottom:20px;
font-weight: bold;
font-family: "MyFont";
text-align: center;
}
Article
Article with MathML
Article with SVG
Article with XInclude
Book
Book with XInclude
Chapter
Section
Set of Books
Some experimental DocBook 5.1 templates are also available and are stored in the
[OXYGEN_DIR]/frameworks/docbook/templates/DocBook 5.1 (Experimental) folder. They
include the following:
Assembly
Topic
You can form a cross reference to that chapter by adding an olink, as in the following example:
You may need to update your
<olink targetdoc="MailAdminGuide" targetptr="user_accounts">user accounts
</olink>
when you get a new machine.
The root element name is one of the following: concept, task, reference, dita, or topic.
The PUBLIC ID of the document is a PUBLIC ID for the elements listed above.
The root element of the file has an attribute named DITAArchVersion for the
http://dita.oasis-open.org/architecture/2005/ namespace. This enhanced case of matching is only applied when the
Enable DTD/XML Schema processing in document type detection option is enabled from the Document Type
Association preferences page.
Default schemas that are used if one is not detected in the DITA documents are stored in the various folders inside
[OXYGEN_DIR]/frameworks/dita/DITA-OT/dtd/ or
[OXYGEN_DIR]/frameworks/dita/DITA-OT/schema/ (or if you are using DITA 2.x, inside
[OXYGEN_DIR]/frameworks/dita/catalog.xml
[OXYGEN_DIR]/frameworks/dita/DITA-OT/catalog-dita.xml (or if you are using DITA 2.x,
[OXYGEN_DIR]/frameworks/dita/DITA-OT2.x/catalog-dita.xml)
[OXYGEN_DIR]/frameworks/dita/plugin/catalog.xml
[OXYGEN_DIR]/frameworks/dita/styleguide/catalog.xml
When invoked on a single selection, an ID is generated for the selected element at the cursor position.
When invoked on a block of selected content, IDs are generated for all top-level elements and elements from
the list in the ID Options dialog box that are found in the current selection.
When invoked on a single selection, an ID is generated for the selected element at the cursor position.
When invoked on a block of selected content, IDs are generated for all top-level elements and elements from
the list in the ID Options dialog box that are found in the current selection.
Note: The Generate IDs action does not overwrite existing ID values. It only affects elements that do not
already have an id attribute.
Reuse submenu
This submenu includes the following actions in regards to reusing content in DITA:
Push Current Element
Opens the Push current element dialog box that allows content from a source topic to be inserted into another
topic without any special coding in the topic where the content will be re-used.
DITA XHTML - Transforms a DITA topic to XHTML using DITA Open Toolkit.
DITA PDF - Transforms a DITA topic to PDF using the DITA Open Toolkit and the Apache FOP engine.
DITA for Publishers topic specialization templates (available when using the built-in DITA-OT 1.8 version):
[OXYGEN_DIR]/frameworks/dita/catalog.xml
[OXYGEN_DIR]/frameworks/dita/DITA-OT/catalog-dita.xml (or if you are using DITA 2.x,
[OXYGEN_DIR]/frameworks/dita/DITA-OT2.x/catalog-dita.xml)
Predefined transformation scenarios allow you to transform a DITA map to PDF, ODF, XHTML, WebHelp, EPUB,
and CHM files.
Many more output formats are available by clicking the New button. The transformation process relies on the DITA
Open Toolkit.
DITA Map to WebHelp Output
DITA maps can be transformed into WebHelp systems.
WebHelp Output
To publish a DITA map to WebHelp, follow these steps:
1. Click the
Configure Transformation Scenario(s) action from the toolbar (or the Document > Transformation
menu.
2. Select the DITA Map WebHelp scenario from the DITA Map section.
3. Click Apply associated.
When the DITA Map WebHelp transformation is complete, the output is automatically opened in your default
browser.
WebHelp With Feedback Output
To publish a DITA map as WebHelp with Feedback:
1. Click
Configure Transformation Scenarios.
2. Select the DITA Map WebHelp with Feedback scenario from the DITA Map section.
3. Click Apply associated.
4. Enter the documentation product ID and the documentation version.
When the DITA Map WebHelp with Feedback transformation is complete, your default browser opens the
installation.html file. This file contains information about the output location, system requirements, installation
instructions, and deployment of the output.
To watch our video demonstration about the feedback-enabled WebHelp system, go to
http://oxygenxml.com/demo/Feedback_Enabled_WebHelp.html.
WebHelp Mobile Output
To generate a mobile WebHelp system from your DITA map:
1. From the DITA Maps Manager view click
Configure Transformation Scenarios.
2. Select the DITA Map WebHelp - Mobile transformation scenario.
3. Click Apply associated.
When the DITA Map WebHelp - Mobile transformation is complete, the output is automatically opened in your default
browser.
webhelp.footer.include
Specifies whether or not to include footer in each WebHelp page. Possible values: yes, no. If set to no, no footer
is added to the WebHelp pages. If set to yes and the webhelp.footer.file parameter has a value, then the
content of that file is used as footer. If the webhelp.footer.file has no value then the default Oxygen XML
Editor footer is inserted in each WebHelp page.
webhelp.logo.image (not available for the WebHelp Mobile transformation)
Specifies a path to an image displayed as a logo in the left side of the output header.
webhelp.logo.image.target.url (not available for the WebHelp Mobile transformation)
Specifies a target URL that is set on the logo image. When you click the logo image, you will be redirected to this
address.
webhelp.search.ranking (not available for the WebHelp Mobile transformation)
If this parameter is set to false then the 5-star rating mechanism is no longer included in the search results that
are displayed on the Search tab (default setting is true).
webhelp.search.japanese.dictionary
The file path of the dictionary that will be used by the Kuromoji morphological engine that Oxygen XML Editor
uses for indexing Japanese content in the WebHelp pages. This indexer does not come bundled with Oxygen XML
ar-eg - Arabic
he-il - Hebrew
ur-pk - Urdu
Each page has a <url> element structure containing additional information, such as:
loc - the URL of the page. This URL must begin with the protocol (such as http), if required by your web server.
It is constructed from the value of the webhelp.sitemap.base.url parameter from the transformation scenario
and the relative path to the page (collected from the href attribute of a topicref element in the DITA map).
Note: The value must have less than 2,048 characters.
lastmod - the date when the page was last modified. The date format is YYYY-MM-DD.
changefreq - indicates how frequently the page is likely to change. This value provides general information to
assist search engines, but may not correlate exactly to how often they crawl the page. Valid values are: always,
hourly, daily, weekly, monthly, yearly, and never. The first time the sitemap.xml file is generated,
the value is set based upon the value of the webhelp.sitemap.change.frequency parameter in the DITA
WebHelp transformation scenario. You can change the value in each url element by editing the sitemap.xml
file.
Note: The value always should be used to describe documents that change each time they are accessed.
The value never should be used to describe archived URLs.
priority - the priority of this page relative to other pages on your site. Valid values range from 0.0 to 1.0. This
value does not affect how your pages are compared to pages on other sites. It only lets the search engines know
which pages you deem most important for the crawlers. The first time the sitemap.xml file is generated, the
value is set based upon the value of the webhelp.sitemap.priority parameter in the DITA WebHelp
transformation scenario. You can change the value in each url element by editing the sitemap.xml file.
Note: lastmod, changefreq, and priority are optional elements.
webhelp.sitemap.base.url - the URL of the location where your WebHelp system is deployed
Note: This parameter is required in order for Oxygen XML Editor to generate the sitemap.xml file.
webhelp.sitemap.change.frequency - how frequently the WebHelp pages are likely to change (accepted
values are: always, hourly, daily, weekly, monthly, yearly, and never)
webhelp.sitemap.priority - the priority of each page (value ranging from 0.0 to 1.0)
Configure
Go to www.amazon.com/kindleformat/kindlegen and download the zip file that matches your operating system.
Unzip the file on your local disk.
Start Oxygen XML Editor and open a DITA map in the DITA Maps Manager view.
Click
Configure Transformation Scenario(s) on the toolbar and apply the DOCX DITA scenario. If you
encounter any issues with the transformation, click the link below for further details about the Word to DITA
Transformation Framework.
The CSS options for the XHTML document type are set to merge the CSS stylesheets specified in the document with
the CSS stylesheets defined in the XHTML document type.
The default CSS files used for rendering XHTML content in Author mode are stored in
[OXYGEN_DIR]/frameworks/xhtml/css/.
The default catalogs for the XHTML document type are as follows:
[OXYGEN_DIR]/frameworks/xhtml/dtd/xhtmlcatalog.xml
[OXYGEN_DIR]/frameworks/relaxng/catalog.xml
[OXYGEN_DIR]/frameworks/nvdl/catalog.xml
[OXYGEN_DIR]/frameworks/xhtml11/dtd/xhtmlcatalog.xml
[OXYGEN_DIR]/frameworks/xhtml11/schema/xhtmlcatalog.xml
[OXYGEN_DIR]/xhtml5 (epub3)/catalog-compat.xml
Browse for local file - Displays the Open dialog box to select a local file.
Browse for remote file - Displays the Open URL dialog box to select a remote file.
Browse for archived file - Opens the Archive Browser to select a file from an archive.
Browse Data Source Explorer - Open the Data Source Explorer to select a file from a connected data source.
Search for file - Opens the Find Resource dialog box to search for a file.
Insert Image
Inserts a graphic object at the cursor position. This is done by inserting an img element regardless of the current
context. The following graphical formats are supported: GIF, JPG, JPEG, BMP, PNG, SVG.
Headings Drop-down Menu
A drop-down menu that includes actions for inserting h1, h2, h3, h4, h5, h6 elements.
Insert Paragraph
Insert a new paragraph element at current cursor position.
Insert Equation
Opens the XML Fragment Editor that allows you to insert and edit MathML notations.
Insert List Item
Inserts a list item in the current list type.
Insert Unordered List
Inserts an unordered list at the cursor position. A child list item is also automatically inserted by default.
Insert Ordered List
Inserts an ordered list at the cursor position. A child list item is also automatically inserted by default.
Insert a definition list at the cursor position
Inserts a definition list (dl element) with one list item (a dt child element and a dd child element).
Sort
Sorts cells or list items in a table.
XHTML Templates
Default templates are available for XHTML. They are stored in [OXYGEN_DIR]/frameworks/xhtml/templates
folder and they can be used for easily creating basic XHTML documents.
Here are some of the XHTML templates available when creating new documents from templates.
The default schema that is used if one is not detected in the TEI ODD document is tei_odds.rng and it is stored in
[OXYGEN_DIR]/frameworks/tei/xml/tei/custom/schema/relaxng/.
The default CSS files used for rendering TEI ODD content in Author mode are stored in
[OXYGEN_DIR]/frameworks/tei/xml/tei/css/.
The default catalogs for the TEI ODD document type are as follows:
[OXYGEN_DIR]/frameworks/tei/xml/tei/custom/schema/catalog.xml
[OXYGEN_DIR]/frameworks/tei/xml/tei/schema/catalog.xml
When invoked on a single selection, an ID is generated for the selected element at the cursor position.
When invoked on a block of selected content, IDs are generated for all top-level elements and elements from
the list in the ID Options dialog box that are found in the current selection.
Note: The Generate IDs action does not overwrite existing ID values. It only affects elements that do not
already have an id attribute.
Refresh References
You can use this action to manually trigger a refresh and update of all referenced resources.
Tags display mode Submenu
Full Tags with Attributes - Displays full tag names with attributes for both block level and in-line level elements.
Full Tags - Displays full tag names without attributes for both block level and in-line level elements.
Block Tags - Displays full tag names for block level elements and simple tags without names for in-line level
elements.
Inline Tags - Displays full tag names for inline level elements, while block level elements are not displayed.
Partial Tags - Displays simple tags without names for in-line level elements, while block level elements are
not displayed.
No Tags - No tags are displayed. This is the most compact mode and is as close as possible to a word-processor
view.
Profiling/Conditional Text Submenu
Edit Profiling Attributes - Allows you to configure the profiling attributes and their values.
Show Profiling Colors and Styles - Select this option to turn on conditional styling.
Show Profiling Attributes - Select this option to turn on conditional text markers. They are displayed at the end
of conditional text blocks, as a list of attribute name and their currently set values.
Show Excluded Content - When this option is enabled, the content filtered by the currently applied condition set
is greyed-out. To show only the content that matches the currently applied condition set, disable this option.
List of all profiling condition sets that match the current document type - You can click a listed condition set
to activate it.
Profiling Settings - Opens the profiling options preferences page, where you can manage profiling attributes
and profiling conditions sets. You can also configure the profiling styles and colors options from the colors/styles
preferences page and the attributes rendering preferences page.
TEI ODD Drag/Drop Actions
Dragging a file from the Project view or DITA Maps Manager view and dropping it into a TEI ODD document that is
edited in Author mode, creates a link to the dragged file (the ptr element with the target attribute) at the drop
location.
TEI ODD XHTML - Transforms a TEI ODD document into an XHTML document
TEI ODD PDF - Transforms a TEI ODD document into a PDF document using the Apache FOP engine
TEI ODD EPUB - Transforms a TEI ODD document into an EPUB document
TEI ODD DOCX - Transforms a TEI ODD document into a DOCX document
TEI ODD ODT - Transforms a TEI ODD document into an ODT document
TEI ODD RelaxNG XML - Transforms a TEI ODD document into a RelaxNG XML document
TEI ODD to DTD - Transforms a TEI ODD document into a DTD document
TEI ODD to XML Schema - Transforms a TEI ODD document into an XML Schema document
TEI ODD to RelaxNG Compact - Transforms a TEI ODD document into an RelaxNG Compact document
The default schema that is used if one is not detected in the TEI P4 document is tei2.dtd and it is stored in
[OXYGEN_DIR]/frameworks/tei/xml/teip4/schema/dtd/.
The default CSS files used for rendering TEI P4 content in Author mode is stored in
[OXYGEN_DIR]/frameworks/tei/xml/tei/css/.
The default catalogs for the TEI P4 document type are as follows:
[OXYGEN_DIR]/frameworks/tei/xml/teip4/schema/dtd/catalog.xml
[OXYGEN_DIR]/frameworks/tei/xml/teip4/custom/schema/dtd/catalog.xml
[OXYGEN_DIR]/frameworks/tei/xml/teip4/stylesheet/catalog.xml
When invoked on a single selection, an ID is generated for the selected element at the cursor position.
When invoked on a block of selected content, IDs are generated for all top-level elements and elements from
the list in the ID Options dialog box that are found in the current selection.
Note: The Generate IDs action does not overwrite existing ID values. It only affects elements that do not
already have an id attribute.
Refresh References
You can use this action to manually trigger a refresh and update of all referenced resources.
Tags display mode Submenu
Full Tags with Attributes - Displays full tag names with attributes for both block level and in-line level elements.
Full Tags - Displays full tag names without attributes for both block level and in-line level elements.
Block Tags - Displays full tag names for block level elements and simple tags without names for in-line level
elements.
Inline Tags - Displays full tag names for inline level elements, while block level elements are not displayed.
Partial Tags - Displays simple tags without names for in-line level elements, while block level elements are
not displayed.
No Tags - No tags are displayed. This is the most compact mode and is as close as possible to a word-processor
view.
Profiling/Conditional Text Submenu
Edit Profiling Attributes - Allows you to configure the profiling attributes and their values.
Show Profiling Colors and Styles - Select this option to turn on conditional styling.
Show Profiling Attributes - Select this option to turn on conditional text markers. They are displayed at the end
of conditional text blocks, as a list of attribute name and their currently set values.
Show Excluded Content - When this option is enabled, the content filtered by the currently applied condition set
is greyed-out. To show only the content that matches the currently applied condition set, disable this option.
List of all profiling condition sets that match the current document type - You can click a listed condition set
to activate it.
Profiling Settings - Opens the profiling options preferences page, where you can manage profiling attributes
and profiling conditions sets. You can also configure the profiling styles and colors options from the colors/styles
preferences page and the attributes rendering preferences page.
TEI P4 Drag/Drop Actions
Dragging a file from the Project view or DITA Maps Manager view and dropping it into a TEI P4 document that is
edited in Author mode, creates a link to the dragged file (the ptr element with the target attribute) at the drop
location.
TEI P4 Templates
The default templates are stored in [OXYGEN_DIR]/frameworks/tei/templates/TEI P4 folder and they
can be used for easily creating basic TEI P4 documents. These templates are available when creating new documents
from templates.
The default schema that is used if one is not detected in the TEI P5 document is tei_all.rng and it is stored in
[OXYGEN_DIR]/frameworks/tei/xml/tei/custom/schema/relaxng/.
[OXYGEN_DIR]/frameworks/tei/xml/tei/schema/dtd/catalog.xml
[OXYGEN_DIR]/frameworks/tei/xml/tei/custom/schema/dtd/catalog.xml
[OXYGEN_DIR]/frameworks/tei/xml/tei/stylesheet/catalog.xml
When invoked on a single selection, an ID is generated for the selected element at the cursor position.
When invoked on a block of selected content, IDs are generated for all top-level elements and elements from
the list in the ID Options dialog box that are found in the current selection.
Note: The Generate IDs action does not overwrite existing ID values. It only affects elements that do not
already have an id attribute.
Refresh References
You can use this action to manually trigger a refresh and update of all referenced resources.
Tags display mode Submenu
Full Tags with Attributes - Displays full tag names with attributes for both block level and in-line level elements.
Full Tags - Displays full tag names without attributes for both block level and in-line level elements.
Block Tags - Displays full tag names for block level elements and simple tags without names for in-line level
elements.
TEI P5 Templates
The default templates are stored in [OXYGEN_DIR]/frameworks/tei/templates/TEI P5 folder and they
can be used for easily creating basic TEI P5 documents. These templates are available when creating new documents
from templates:
JATS Preview (simple HTML) - Converts a JATS document to a simple HTML document.
JATS Templates
Default templates are available for JATS documents. They are stored in
[OXYGEN_DIR]/frameworks/jats/templates folder and they can be used for easily creating basic JATS
documents.
The default JATS templates that are available when creating new documents from templates are as follows:
Document Templates
The default templates for the NCX and OCF document types are located in the
[OXYGEN_DIR]/frameworks/docbook/templates folder.
The default template for the OPF 2.0 document type is located in the
[OXYGEN_DIR]/frameworks/docbook/templates/2.0 folder.
The default template for the OPF 3.0 document type is located in the
[OXYGEN_DIR]/frameworks/docbook/templates/3.0 folder.
The following EPUB templates are available when creating new documents from templates:
Chapter
9
Author Mode Customization
Topics:
This section contains an Author Mode Customization Guide on page 620, CSS
Support in Author Mode on page 706, a collection of Frequently Asked Questions
regarding the Oxygen XML Editor API, and other topics in regards to customizing
the Author mode.
CSS Stylesheet
A set of rules must be defined for describing how the XML document is to be rendered in Author mode. This is done
using Cascading Style Sheets (CSS). CSS is a language used to describe how an HTML or XML document should be
formatted by a browser. CSS is widely used in the majority of websites.
The elements from an XML document are displayed in the layout as a series of boxes. Some of the boxes contain text
and may flow one after the other, from left to right. These are called in-line boxes. There are also other type of boxes
that flow one below the other, like paragraphs. These are called block boxes.
For example, consider the way a traditional text editor arranges the text. A paragraph is a block, because it contains a
vertical list of lines. The lines are also blocks. However, blocks that contains in-line boxes arrange its children in a
horizontal flow. That is why the paragraph lines are also blocks, while the traditional "bold" and "italic" sections are
represented as in-line boxes.
The CSS allows us to specify that some elements are displayed as tables. In CSS, a table is a complex structure and
consists of rows and cells. The table element must have children that have a table-row style. Similarly, the row
elements must contain elements with a table-cell style.
To make it easy to understand, the following section describes how each element from a schema is formatted using a
CSS file. Note that this is just one of infinite possibilities for formatting the content.
title
The title of the report. Usually titles have a large font. The block display is used so that the subsequent elements
will be placed below it, and its font is changed to double the size of the normal text.
title {
display:block;
font-size:2em;
}
description
This element contains several lines of text describing the report. The lines of text are displayed one below the other,
so the description has the block display. Also, the background color is changed to make it standout.
description {
display:block;
background-color:#EEEEFF;
color:black;
}
line
A line of text in the description. A specific aspect is not defined and it just indicates that the display should be block
style.
line {
display:block;
}
important
The important element defines important text from the description. Since it can be mixed with text, its display
property must be set to inline. Also, the text is emphasized with boldto make it easier to spot.
important {
display:inline;
font-weight:bold;
}
results
The results element displays the list of test_names and the results for each one. To make it easier to read, it is
displayed as a table, with a green border and margins.
results{
display:table;
margin:2em;
border:1px solid green;
}
entry
An item in the results element. The results are displayed as a table so the entry is a row in the table. Thus, the display
is table-row.
entry {
display:table-row;
}
LESS example:
<?xml-stylesheet type="text/css" href="test.less"?>
Note: XHTML documents need a link element, with the href and type attributes in the head child
element, as specified in the W3C CSS specification. XHTML example:
<link href="/style/screen.css" rel="stylesheet" type="text/css"/>
Tip: You can also insert the xml-stylesheet processing instruction by using the
Associate
XSLT/CSS Stylesheet action that is available on the toolbar or in the Document > XML Document menu.
2. Configure a Document Type Association by adding a new CSS or LESS file in the settings. To do so, open the
Preferences dialog box and go to Document Type Association. Edit the appropriate framework, open the Author
tab, then the CSS tab. Press the
Note: The Document Type Associations are read-only, so you need to extend an existing one.
The processing instruction xml-stylesheet associates the CSS stylesheet to the XML file. The href pseudo
attribute contains the URI reference to the stylesheet file. In our case the CSS is in the same directory as the XML file.
The next step is to place the XSD file and the CSS file on a web server and modify the template to use the HTTP URLs,
like this:
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/css"
href="http://www.mysite.com/reports/test_report.css"?>
Description - The document type description displayed as a tool tip in the Document Type Association preferences
page.
Storage - The location where the document type is saved. If you select the External storage option, the document
type is saved in the specified file with a mandatory framework extension, located in a subdirectory of the current
frameworks directory. If you select the Internal storage option, the document type data is saved in the current
.xpr Oxygen XML Editor project file (for Project-level Document Type Association options) or in the Oxygen
XML Editor internal options (for Global-level Document Type Association Options). You can change the Document
Type Association options level in the Document Type Association preferences page.
Initial edit mode - Allows you to select the initial editing mode for this document type: Editor specific, Text,
Author, Grid and Design (available only for the W3C XML Schema editor). If the Editor specific option is selected,
the initial editing mode is determined based upon the editor type. You can find the mapping between editors and
edit modes in the Edit modes preferences page. You can impose an initial mode for opening files that match the
association rules of the document type. For example, if the files are usually edited in the Author mode you can set
it in the Initial edit mode combo box.
Note: You can also customize the initial mode for a document type in the Edit modes preferences page. Open
the Preferences dialog box and go to Editor > Edit modes.
You can specify the Association rules used for determining a document type for an opened XML document. A rule can
define one or more conditions. All conditions need to be fulfilled in order for a specific rule to be chosen. Conditions
can specify:
Namespace - The namespace of the document that matches the document type.
Root local name of document - The local name of the document that matches the document type.
File name - The file name (including the extension) of the document that matches the document type.
Public ID (for DTDs) - The PUBLIC identifier of the document that matches the document type.
Attribute - This field allows you to associate a document type depending on a certain value of the attribute in the
root.
Java class - Name of the Java class that is called to determine if the document type should be used for an XML
document. Java class must either implement the
ro.sync.ecss.extensions.api.DocumentTypeCustomRuleMatcher interface or extend the
ro.sync.ecss.extensions.api.DocumentTypeAdvancedCustomRuleMatcher abstract class from
the Author API.
In the Schema tab, you can specify the type and URI of schema used for validation and content completion of all
documents from the document type, when there is no schema detected in the document.
You can choose one of the following schema types:
DTD
Relax NG schema (XML syntax)
Relax NG schema (XML syntax) + Schematron
Relax NG schema (compact syntax)
XML Schema
XML Schema + Schematron rules
NVDL schema
New button and use the Action dialog box to create an action.
b) Set the invoke operation field to InsertFragmentOperation built-in operation, designed to insert an
XML fragment at cursor position. This belongs to a set of built-in operations, a complete list of which can be
found in the Author Default Operations section. This set can be expanded with your own Java operation
implementations.
c) Configure the arguments section as follows:
<section xmlns=
"http://www.oxygenxml.com/sample/documentation">
<title/>
</section>
insertLocation - leave it empty. This means the location will be at the cursor position.
insertPosition - select "Inside".
Configure the Insert Table Action for a Framework
The procedure described below will create an action that inserts a table with three rows and three columns into a document.
The first row is the table header. As with the insert section action, you will use the InsertFragmentOperation
built-in operation.
Place the icon files for the menu item, and for the toolbar, in the frameworks/sdf directory.
1.
2.
3.
4.
5.
6.
7.
8.
insertLocation - to add tables at the end of the section use the following code:
ancestor::section/*[last()]
3. The right side of the panel displays the menu tree with Menu entry as root. To change its name, click this label to
select it, then press the
Edit button. Enter SD Framework as name, and D as menu access key.
4. Select the Submenu label in the left panel section and the SD Framework label in the right panel section, then press
the
Add as child button. Change the submenu name to Table, using the
Edit button.
5. Select the Insert section action in the left panel section and the Table label in the right panel section, then press the
Add as sibling button.
6. Now select the Insert table action in the left panel section and the Table in the right panel section. Press the
as child button.
Add
Tip: If you have many custom toolbar actions, or want to group actions according to their category, add
additional toolbars with custom names and split the actions to better suit your purpose. If your toolbar is not
displayed when switching to the Author mode, right click the main toolbar, select Configure Toolbars,
and make sure the Author Custom Actions 1 toolbar is enabled.
Configure Content Completion for a Framework
You can customize the content of the following Author controls, adding items (which, when invoked, perform custom
actions) or filtering the default contributed ones:
You can use the content completion customization support in the Simple Documentation Framework following the next
steps:
1. Open the Document type configuration dialog box for the SDF framework and select the Author tab. Next, go to
the Content Completion tab.
InsertFragmentOperation
Inserts an XML fragment at the current cursor position. The selection - if there is one, remains unchanged. The
fragment will be inserted in the current context of the cursor position meaning that if the current XML document
uses some namespace declarations then the inserted fragment must use the same declarations. The namespace
declarations of the inserted fragment will be adapted to the existing namespace declarations of the XML document.
For more details about the list of parameters go to: The Arguments of InsertFragmentOperation Operation on page
644.
InsertOrReplaceFragmentOperation
Similar to InsertFragmentOperation, except it removes the selected content before inserting the fragment.
InsertOrReplaceTextOperation
SurroundWithFragmentOperation
Surrounds the selected content with a text fragment. Since the fragment can have multiple nodes, the surrounded
content will be always placed in the first leaf element. If there is no selection, the operation will simply insert the
fragment at the cursor position. For more details about the list of parameters go to The Arguments of
SurroundWithFragmentOperation on page 645.
SurroundWithTextOperation
This operation has two arguments (two text values) that will be inserted before and after the selected content. If there
is no selected content, the two sections will be inserted at the cursor position. The arguments of the operation are:
InsertEquationOperation
Inserts a fragment containing a MathML equation at the cursor offset. The argument of this operation is:
fragment - The XML fragment containing the MathML content which should be inserted.
OpenInSystemAppOperation
Opens a resource in the system application that is associated with the resource in the operating system. The arguments
of this operation is:
resourcePath - An XPath expression that, when executed, returns the path of the resource to be opened.
Editor variables are expanded in the value of this parameter, before the expression is executed.
isUnparsedEntity - Possible values are true or false. If the value is true, the value of the
resourcePath argument is treated as the name of an unparsed entity.
ChangeAttributeOperation
This operation allows you to add/modify/remove an attribute. You can use this operation in your own custom Author
mode action to modify the value for a certain attribute on a specific XML element. The arguments of the operation
are:
UnwrapTagsOperation
This operation allows removing the element tags either from the current element or for an element identified with
an XPath location. The argument of the operation is
unwrapElementLocation - An XPath expression indicating the element to unwrap. If it is not defined, the
element at the cursor position is unwrapped.
ToggleSurroundWithElementOperation
This operation allows wrapping and unwrapping content in a specific wrapper element which can have certain
attributes specified on it. It is useful to implement toggle actions such as highlighting text as bold, italic, or underline.
The operation supports processing multiple selection intervals, such as multiple cells within a table column selection.
The arguments of the operation are:
RenameElementOperation
This operation allows you to rename all occurrences of the elements identified by an XPath expression. The operation
requires two parameters:
ExecuteTransformationScenariosOperation
This operation allows running one or more transformation scenarios defined in the current document type association.
It is useful to add to the toolbar buttons that trigger publishing to various output formats. The argument of the
operation is:
scenarioNames - The list of scenario names that will be executed, separated by new lines.
sourceLocation
An XPath expression indicating the element that the script will be applied on. If it is not defined then the element
at the cursor position will be used.
There may be situations in which you want to look at an ancestor of the current element and take decisions in
the script based on this. In order to do this you can set the sourceLocation to point to an ancestor node (for
example /) then declare a parameter called currentElementLocation in your script and use it to re-position
in the current element like:
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="2.0"
xpath-default-namespace="http://docbook.org/ns/docbook"
xmlns:saxon="http://saxon.sf.net/" exclude-result-prefixes="saxon">
<!-- This is an XPath location which will be sent by the operation to the script -->
<xsl:param name="currentElementLocation"/>
<xsl:template match="/">
<!-- Evaluate the XPath of the current element location -->
<xsl:apply-templates
select="saxon:eval(saxon:expression($currentElementLocation))"/>
</xsl:template>
<xsl:template match="para">
<!-- And the context is again inside the current element,
but we can use information from the entire XML -->
<xsl:variable
name="keyImage" select="//imagedata[@fileref='images/lake.jpeg']
/ancestor::inlinemediaobject/@xml:id/string()"/>
<xref linkend="{$keyImage}" role="key_include"
xmlns="http://docbook.org/ns/docbook">
<xsl:value-of
select="$currentElementLocation"></xsl:value-of>
</xref>
</xsl:template>
</xsl:stylesheet>
targetLocation
script
The script content (XSLT or XQuery). The base system ID for this will be the framework file, so any include/import
reference will be resolved relative to the .framework file that contains this action definition.
For example, for the following script, the imported xslt_operation.xsl needs to be located in the current
framework's directory.
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<xsl:import href="xslt_operation.xsl"/>
</xsl:stylesheet>
action
The insert action relative to the node determined by the target XPath expression. It can be: Replace, At cursor
position, Before, After, Inside as first child or Inside as last child.
caretPosition
The position of the cursor after the action is executed. It can be: Preserve, Before, Start, First
editable position, End, or After. If this parameter is not set, you can still indicate the position of the
cursor by using the ${caret} editor variable in the inserted content.
expandEditorVariables
Parameter controlling the expansion of editor variables returned by the script processing. Expansion is enabled
by default.
XQueryUpdateOperation
Allows you to execute an XQuery Update script directly over content in Author mode.
Notice: This operation is not applicable to the Author Component or the WebApp Component.
It has one argument:
script
The XQuery Update script to be executed. The value can either be an XQuery script or a URL that points to the
XQuery Update script. You can use the ${framework} or ${frameworkDir} editor variables to refer the
scripts from the framework directory.
The script will be executed in the context of the node at the cursor position. If the script declares the following
variable, it will also receive the selected nodes (assuming that entire nodes are selected):
declare variable $oxyxq:selection external;
JSOperation
Allows you to call the Java API from custom JavaScript content.
Notice: For the WebApp Component, this operation cannot be invoked using the JavaScript API.
This operation accepts the following parameter:
script
The JavaScript content to execute. It must have a function called doOperation(), which can use the predefined
authorAccess variable. The authorAccess variable has access to the entire
ro.sync.ecss.extensions.api.AuthorAccess Java API.
The following example is a script that retrieves the current value of the type attribute on the current
element, allows the end user to edit its new value and sets the new value in the document:
function doOperation(){
//The current node is either entirely selected...
currentNode = authorAccess.getEditorAccess().getFullySelectedNode();
if(currentNode == null){
//or the cursor is placed in it
caretOffset = authorAccess.getEditorAccess().getCaretOffset();
currentNode = authorAccess.getDocumentController().getNodeAtOffset(caretOffset);
}
//Get current value of the @type attribute
currentTypeValue = "";
currentTypeValueAttr = currentNode.getAttribute("type");
if(currentTypeValueAttr != null){
currentTypeValue = currentTypeValueAttr.getValue();
}
//Ask user for new value for attribute.
newTypeValue = javax.swing.JOptionPane.showInputDialog("Input @type value", currentTypeValue);
if(newTypeValue != null){
//Create and set the new attribute value for the @type attribute.
attrValue = new Packages.ro.sync.ecss.extensions.api.node.AttrValue(newTypeValue);
authorAccess.getDocumentController().setAttribute("type", attrValue, currentNode);
}
}
Note: If you have a script called commons.js in the framework directory, you
can call functions defined inside it from your custom script content so that you can
use that external script file as a library of functions.
ExecuteMultipleActionsOperation
actionIDs - The action IDs list which will be executed in sequence, the list must be a string sequence containing
the IDs separated by new lines.
MoveElementOperation
Flexible operation for moving an XML element to another location from the same document. XPath expressions are
used to identify the source element and the target location. The operation takes the following parameters:
ChangePseudoClassesOperation
Operation that sets a list of pseudo-class values to nodes identified by an XPath expression. It can also remove a list
of values from nodes identified by an XPath expression. The operation accepts the following parameters:
setLocations - An XPath expression indicating a list of nodes on which the specified list of pseudo-classes
will be set. If it is not defined, then the element at the cursor position will be used.
setPseudoClassNames - A space-separated list of pseudo-class names which will be set on the matched
nodes.
removeLocations - An XPath expression indicating a list of nodes from which the specified list of
pseudo-classes will be removed. If it is not defined, then the element at the cursor position will be used.
removePseudoClassNames - A space-separated list of pseudo-class names which will be removed from
the matched nodes.
SetPseudoClassOperation
An operation that sets a pseudo-class to an element. The operation accepts the following parameters:
elementLocation - An XPath expression indicating the element on which the pseudo-class will be set. If it
is not defined, then the element at cursor position will be used.
name - The pseudo-class local name.
ShowElementDocumentationOperation
Opens the associated specification HTML page for the current element. The operation accepts as parameter an URL
pattern that points to the HTML page containing the documentation.
XQueryUpdateOperation
An implementation of an operation that applies an XQuery Update script. The changes are performed directly over
the AuthorNode model. The operation accepts the following parameter:
script - can be either an XQuery script or an URL pointing to the XQuery update script (you can use
${framework} and ${frameworkDir} to refer scripts from the framework directory).
The script will be executed in the context of the cursor node. If the XQuery script declares the selection variable,
it will also receive the selected nodes (assuming that the selection consists entirely of nodes).
RemovePseudoClassOperation
An operation that removes a pseudo-class from an element. Accepts the following parameters:
elementLocation - The XPath location that identifies the element. Leave it empty for the current element.
Let's consider that there is a pseudo-class called myClass on the element paragraph and there
are CSS styles matching the pseudo-class.
paragraph:myClass{
font-size:2em;
color:red;
}
paragraph{
color:blue;
}
In the previous example, by removing the pseudo-class, the layout of the paragraph is rebuilt by
matching the other rules (in this case, the foreground color of the paragraph element will become
blue.
TogglePseudoClassOperation
An implementation of an operation to toggle on/off the pseudo-class of an element. Accepts the following parameters:
elementLocation - The XPath location that identifies the element. Leave it empty for the current element.
paragraph:myClass{
color:red;
}
paragraph{
color:blue;
}
ExecuteMultipleWebappCompatibleActionsOperation
An implementation of an operation that runs a sequence of Oxygen XML WebApp-compatible actions, defined as
a list of IDs.
DeleteElementsOperation
Deletes the nodes indicated by the elementLocations parameter XPath expression. If missing, the operation
will delete the node at the cursor location.
DeleteElementOperation
Deletes the node indicated by the elementLocation parameter XPath expression. If missing, the operation will
delete the node at the cursor location.
InsertXIncludeOperation
Insert an XInclude element at the cursor offset. Opens a dialog box that allows you to browse and select content
to be included in your document and automatically generates the corresponding XInclude instruction.
Author mode operations can include parameters that contain the following editor variables:
${caret} - The position where the cursor is located. This variable can be used in a code template, in Author mode
operations, or in a selection plugin.
${selection} - The current selected text content in the current edited document. This variable can be used in a code
template, in Author mode operations, or in a selection plugin.
${ask('message', type, ('real_value1':'rendered_value1'; 'real_value2':'rendered_value2'; ...), 'default_value')} - To
prompt for values at runtime, use the ask('message', type, ('real_value1':'rendered_value1';
'real_value2':'rendered_value2'; ...), 'default-value'') editor variable. You can set the following parameters:
'message' - The displayed message. Note the quotes that enclose the message.
type - Optional parameter, with one of the following values:
Parameter
url
${ask('Input URL', url)} - The displayed dialog box has the name Input
URL. The expected input type is URL.
password
generic
relative_url
combobox
${ask('File location', relative_url, 'C:/example.txt')} - The dialog box has the name
'File location'. The URL inserted in the input box is made relative to the
current edited document location.
radio
Can be correctly inserted in the document: ('|' marks the insertion point):
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE x:root [
<!ENTITY ent "entity">
]>
Result:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE x:root [
<!ENTITY ent "entity">
]>
<x:root xmlns:x="nsp">
<x:item id="dty2"/>
&ent;
<x:item id="dty3"/>
</x:root>
2. Default namespaces
If there is a default namespace declared in the document and the document fragment does not declare a namespace,
the elements from the fragment are considered to be in no namespace.
For instance the fragment:
<item id="dty2"/>
<item id="dty3"/>
insertLocation
An XPath expression that is relative to the current node. It selects the reference node for the fragment insertion.
insertPosition
One of the three constants: "Inside", "After", or "Before" , showing where the insertion is made relative to the
reference node selected by the insertLocation. "Inside" has the meaning of the first child of the reference
node.
goToNextEditablePosition
After inserting the fragment, the first editable position is detected and the cursor is placed at that location. It handles
any in-place editors used to edit attributes. It will be ignored if the fragment specifies a cursor position using the
cursor editor variable. The possible values of this action are true and false.
schemaAware
This argument applies only on the surround with element operation and controls whether or not the insertion is
valid, based upon the schema. If the insertion is not valid, then wrapping action will be broken up into smaller
intervals until the wrapping action is valid. For example, if you try to wrap a paragraph element with a bold element,
it would not be valid, so the operation will wrap the text inside the paragraph instead, since it would be valid at that
position.
The Arguments of SurroundWithFragmentOperation
The Author mode operation SurroundWithFragmentOperation has only one argument:
fragment
Considering the selected content to be surrounded is the sequence of elements X and Y, then the result is:
<doc>
<F>
<A>
<X></X>
<Y></Y>
</A>
<B>
<C></C>
</B>
</F>
<Z></Z>
<doc>
Since the element A was the first leaf in the fragment, it received the selected content. The fragment was then inserted
in the place of the selection.
Add a Custom Operation to an Existing Framework
This task explains how to add a custom Author mode operation to an existing document type.
1. Setup a sample project by following the instructions for installing the SDK. The framework project is
oxygen-sample-framework.
2. A number of classes in the simple.documentation.framework.operations package implement the
ro.sync.ecss.extensions.api.AuthorOperation interface. Depending on your use-case, modify one
of these classes.
3. Pack the operation class inside a Java jar library.
4. Copy the jar library to the [OXYGEN_DIR]/frameworks/[FRAMEWORK_DIR] directory.
5. Open the Preferences dialog box, go to Document Type Association, and edit the document type (you need write
access to the [OXYGEN_DIR]) to open the Document Type configuration dialog box.
a) In the Classpath tab, add a new entry like: ${framework}/customAction.jar.
b) In the Author tab, add a new action which uses your custom operation.
c) Mount the action to the toolbars or menus.
6. Share the modifications with your colleagues. The files which should be shared are your customAction.jar
library and the .framework configuration file from the [OXYGEN_DIR]/frameworks/[FRAMEWORK_DIR]
directory.
Using Retina/HiDPI Images in Author Mode
Oxygen XML Editor provides support for Retina and HiDPI images through simple naming conventions. The higher
resolution images are stored in the same images folder as the normal resolution images and they are identified by a
scaling factor that is included in the name of the image files. For instance, images with a Retina scaling factor of 2 will
include @2x in the name (for example, [email protected]).
You can reference an image to style an element in a CSS by using the url function in the content property, as in the
following example:
This would place the image that is loaded from the myImage.png file just before the listItem element. However,
if you are using a Retina display (on a Mac), the icon looks a bit blurry as it automatically gets scaled, or if you are using
an HiDPI display (on a Windows-based PC), the icon remains at the original size, thus it will look very small. To solve
this rendering problem you need to be able to reference both a normal DPI image and a high DPI image. However,
referencing both of them from the CSS is not practical, as there is no standard way of doing this.
Starting with version 17, Oxygen XML Editor interprets the argument of the url function as key rather than a fixed
URL. Therefore, when running on a system with a Retina or HiDPI display, Oxygen XML Editor will first try to find
the image file that corresponds to the retina scaling factor. For instance, using the previous example, Oxygen XML
Editor would first try to find [email protected]. If this file is not found, it defaults back to the normal resolution
image file (myImage.png).
Oxygen XML Editor also supports dark color themes. This means that the background of the editor area can be of a
dark color and the foreground a lighter color. On a dark background, you may find it useful to invert the colors of images.
Again, this can be done with simple naming conventions. If an image designed for a dark background is not found, the
normal image is used.
Retina/HiDPI Naming Convention
Refer to the following table for examples of the Retina/HiDPI image naming convention that is used in Oxygen XML
Editor:
Color Theme
normal
../img/myImage.png
../img/[email protected]
dark
../img/myImage_dark.png
../img/[email protected] ../img/[email protected]
../img/[email protected]
You need to enter an element whose attributes will be edited by the user through a graphical user interface.
The user must send selected element content (or the whole document) to a server for some kind of processing.
Content authors need to extract pieces of information from a server and insert it directly into the edited XML
document.
You need to apply an XPath expression on the current document and process the nodes of the resulting node set.
To extend the Oxygen XML Editor Author mode functionality through Java, you will need the Oxygen SDK available
on the Oxygen XML Editor website. It includes the source code of the Author mode operations in the predefined document
types and the full documentation (in Javadoc format) of the public API available for Author mode custom actions.
The doOperation method is invoked when the action is performed either by pressing the toolbar button, by
selecting the menu item or by pressing the shortcut key. The arguments taken by this methods can be one of the
following combinations:
The getArguments method is used by Oxygen XML Editor when the action is configured. It returns the list
of arguments (name and type) that are accepted by the operation.
The getDescription method is used by Oxygen XML Editor when the operation is configured. It returns a
description of the operation.
Note: The complete source code can be found in the Simple Documentation Framework project, included
in the oxygen-sample-framework module of the Oxygen SDK , available as a Maven archetype on the
Oxygen XML Editor website.
Important:
Make sure you always specify the namespace of the inserted fragments.
<image xmlns='http://www.oxygenxml.com/sample/documentation'
href='path/to/image.png'/>
3. Package the compiled class into a jar file. An example of an Ant script that packages the classes folder content
into a jar archive named sdf.jar is listed below:
<?xml version="1.0" encoding="UTF-8"?>
<project name="project" default="dist">
<target name="dist">
<jar destfile="sdf.jar" basedir="classes">
<fileset dir="classes">
<include name="**/*"/>
</fileset>
</jar>
</target>
</project>
Set ID to insert_image.
Set Name to Insert image.
Set Menu access key to letter i.
Set Toolbar action to ${framework}/toolbarImage.png.
Set Menu icon to ${framework}/menuImage.png.
Set Shortcut key to Ctrl (Meta on Mac OS)+Shift+i.
9. Next, we set up the operation. You want to add images only if the current element is a section, book or article.
ro.sync.ecss.extensions.api.ArgumentDescriptor;
ro.sync.ecss.extensions.api.ArgumentsMap;
ro.sync.ecss.extensions.api.AuthorAccess;
ro.sync.ecss.extensions.api.AuthorOperation;
ro.sync.ecss.extensions.api.AuthorOperationException;
3. Now define the operation's arguments. For each of them you will use a String constant representing the argument
name:
private
private
private
private
private
static
static
static
static
static
final
final
final
final
final
String
String
String
String
String
ARG_JDBC_DRIVER ="jdbc_driver";
ARG_USER ="user";
ARG_PASSWORD ="password";
ARG_SQL ="sql";
ARG_CONNECTION ="connection";
These names, types and descriptions will be listed in the Arguments table when the operation is configured.
5. When the operation is invoked, the implementation of the doOperation method extracts the arguments, forwards
them to the method that connects to the database and generates the XML fragment. The XML fragment is then
inserted at the cursor position.
public void doOperation(AuthorAccess authorAccess, ArgumentsMap map)
throws IllegalArgumentException, AuthorOperationException {
// Collects the arguments.
String jdbcDriver =
(String)map.getArgumentValue(ARG_JDBC_DRIVER);
String connection =
(String)map.getArgumentValue(ARG_CONNECTION);
String user =
(String)map.getArgumentValue(ARG_USER);
String password =
(String)map.getArgumentValue(ARG_PASSWORD);
String sql =
(String)map.getArgumentValue(ARG_SQL);
int caretPosition = authorAccess.getCaretOffset();
try {
authorAccess.getDocumentController().insertXMLFragment(
getFragment(jdbcDriver, connection, user, password, sql),
caretPosition);
} catch (SQLException e) {
throw new AuthorOperationException(
"The operation failed due to the following database error: "
+ e.getMessage(), e);
} catch (ClassNotFoundException e) {
throw new AuthorOperationException(
"The JDBC database driver was not found. Tried to load ' "
+ jdbcDriver + "'", e);
}
}
6. The getFragment method loads the JDBC driver, connects to the database and extracts the data. The result is a
table element from the http://www.oxygenxml.com/sample/documentation namespace. The
header element contains the names of the SQL columns. All the text from the XML fragment is escaped. This
means that the '<' and '&' characters are replaced with the '<' and '&' character entities to ensure the fragment
is well-formed.
private String getFragment(
String jdbcDriver,
String connectionURL,
String user,
String password,
String sql) throws
SQLException,
ClassNotFoundException {
Note: The complete source code can be found in the Simple Documentation Framework project, included
in the oxygen-sample-framework module of the Oxygen SDK , available as a Maven archetype on the
Oxygen XML Editor website.
7. Package the compiled class into a jar file.
8. Copy the jar file and the JDBC driver files into the frameworks/sdf directory.
9. Add the jars to the class path. To do this, open the Document Type Association preferences page, select SDF and
press the Edit button. Select the Classpath tab in the lower part of the Document Type configuration dialog box
and press the
Add button . In the displayed dialog box, enter the location of the jar file, relative to the Oxygen
XML Editor frameworks folder.
10. Go to the Actions subtab. The action properties are:
Set ID to clients_report.
Set Name to Clients Report.
Set Menu access key to letter r.
Set Description to Connects to the database and collects the list of clients.
11. The action will work only if the current element is a section. Set up the operation as follows:
Use the Java operation defined earlier to set the Invoke operation field. Press the Choose button, then select
simple.documentation.framework.QueryDatabaseOperation. Once selected, the list of arguments
is displayed. In the figure below the first argument, jdbc_driver, represents the class name of the MySQL JDBC
driver. The connection string has the URL syntax : jdbc://<database_host>:<database_port>/<database_name>.
The SQL expression used in the example follows, but it can be any valid SELECT expression which can be
applied to the database:
SELECT userID, email FROM users
12. Add the action to the toolbar, using the Toolbar panel.
Oxygen XML Editor matches the GUI language with the language set in the translation.xml file. If this language
is not found, the first available language declared in the languagelist tag for the corresponding framework is used.
Add the directory where this file is located to the Classpath list corresponding to the edited document type.
After you create this file, you are able to use the keys defined in it to customize the name and description of the following:
Framework actions
Menu entries
Contextual menus
Toolbars
Static CSS content
For example, if you want to localize the bold action, open the Preferences dialog box and go to Document Type
Association. Use the New or Edit button to open the Document type configuration dialog box, go to Author > Actions,
and rename the bold action to ${i18n(translation_key)}. Actions with a name format different than
${i18n(translation_key)} are not localized. Translation_key corresponds to the key from the
translation.xml file.
To use a description from the translation.xml file in the Java code used by your custom framework, use the new
ro.sync.ecss.extensions.api.AuthorAccess.getAuthorResourceBundle() API method to
request the associated value for a certain key. This allows all the dialog boxes that you present from your custom
operations to have labels translated in different languages.
You can also reference a key directly in the CSS content:
title:before{
content:"${i18n(title.key)} : ";
}
Note: You can enter any language you want in the languagelist tag and any number of keys.
The paragraph contains text and other styling markup, such as bold (b) and italic (i) elements.
<xs:element name="para" type="doc:paragraphType"/>
<xs:complexType name="paragraphType" mixed="true">
<xs:choice minOccurs="0" maxOccurs="unbounded">
<xs:element name="b"/>
<xs:element name="i"/>
The image element has an attribute with a reference to the file containing image data.
<xs:element name="image">
<xs:complexType>
<xs:attribute name="href" type="xs:anyURI" use="required"/>
</xs:complexType>
</xs:element>
The table contains a header row and then a sequence of rows (tr elements) each of them containing the cells. Each
cell has the same content as the paragraphs.
<xs:element name="table">
<xs:complexType>
<xs:sequence>
<xs:element name="header">
<xs:complexType>
<xs:sequence>
<xs:element name="td" maxOccurs="unbounded"
type="doc:paragraphType"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="tr" maxOccurs="unbounded">
<xs:complexType>
<xs:sequence>
<xs:element name="td" type="doc:tdType"
maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:complexType name="tdType">
<xs:complexContent>
<xs:extension base="doc:paragraphType">
<xs:attribute name="row_span" type="xs:integer"/>
<xs:attribute name="column_span" type="xs:integer"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
The def element is defined as a text only element in the imported schema abs.xsd:
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace=
"http://www.oxygenxml.com/sample/documentation/abstracts">
<xs:element name="def" type="xs:string"/>
</xs:schema>
Important: Having block display children in an inline display parent results in Oxygen XML Editor
changing the style of the parent to block display.
Styling the section Element
The title of any section must be bold and smaller than the title of the parent section. To create this effect a sequence of
CSS rules must be created. The * operator matches any element, it can be used to match titles having progressive depths
in the document.
title{
font-size: 2.4em;
font-weight:bold;
}
* * title{
font-size: 2.0em;
}
* * * title{
font-size: 1.6em;
}
* * * * title{
font-size: 1.2em;
}
It's useful to have before the title a constant text, indicating that it refers to a section. This text can include also the
current section number. The :before and :after pseudo elements will be used, plus the CSS counters.
First declare a counter named sect for each book or article. The counter is set to zero at the beginning of each
such element:
book,
article{
counter-reset:sect;
}
The sect counter is incremented with each section, that is a direct child of a book or an article element.
book > section,
article > section{
The "static" text that will prefix the section title is composed of the constant "Section ", followed by the decimal value
of the sect counter and a dot.
book > section > title:before,
article > section > title:before{
content: "Section " counter(sect) ". ";
}
To make the documents easy to read, you add a margin to the sections. In this way the higher nesting level, the larger
the left side indent. The margin is expressed relatively to the parent bounds:
section{
margin-left:1em;
margin-top:1em;
}
Styling Images
The CSS 2.1 does not specify how an element can be rendered as an image. To overpass this limitation, Oxygen XML
Editor supports a CSS Level 3 extension allowing to load image data from an URL. The URL of the image must be
specified by one of the element attributes and it is resolved through the catalogs specified in Oxygen XML Editor.
image{
Our image element has the required attribute href of type xs:anyURI. The href attribute contains an image
location so the rendered content is obtained by using the function:
attr(href, url)
The first argument is the name of the attribute pointing to the image file. The second argument of the attr function
specifies the type of the content. If the type has the url value, then Oxygen XML Editor identifies the content as being
an image. If the type is missing, then the content will be the text representing the attribute value.
Oxygen XML Editor handles both absolute and relative specified URLs. If the image has an absolute URL location (for
example: "http://www.oasis-open.org/images/standards/oasis_standard.jpg") then it is loaded directly from this location.
If the image URL is relative specified to the XML document (for example: "images/my_screenshot.jpg") then the location
is obtained by adding this value to the location of the edited XML document.
An image can also be referenced by the name of a DTD entity which specifies the location of the image file. For example
if the document declares an entity graphic which points to a JPEG image file:
<!ENTITY graphic SYSTEM "depo/keyboard_shortcut.jpg" NDATA JPEG>
and the image is referenced in the XML document by specifying the name of the entity as the value of an attribute:
<mediaobject>
<imageobject>
<imagedata entityref="graphic" scale="50"/>
</imageobject>
</mediaobject>
The CSS should use the functions url, attr and unparsed-entity-uri for displaying the image in the Author
mode:
imagedata[entityref]{
content: url(unparsed-entity-uri(attr(entityref)));
}
To take into account the value of the width attribute of the imagedata and use it for resizing the image, the CSS
can define the following rule:
imagedata[width]{
width:attr(width, length);
}
When trying to validate the document there should be no errors. Now modify the title to title2. Validate again.
This time there should be one error:
cvc-complex-type.2.4.a: Invalid content was found starting with element
'title2'. One of '{"http://www.oxygenxml.com/sample/documentation":title}'
is expected.
Undo the tag name change. Press on the Author button at the bottom of the editing area. Oxygen XML Editor should
load the CSS from the document type association and create a layout similar to this:
The frameworks directory is the container where all the Oxygen XML Editor framework customizations are located.
Each subdirectory contains files related to a specific type of XML documents (schemas, catalogs, stylesheets, CSS
stylesheets, etc.) Distributing a framework means delivering a framework directory.
It is assumed that you have the right to create files and folder inside the Oxygen XML Editor installation directory. If
you do not have this right, you will have to install another copy of the program in a folder you have access to, the home
directory for instance, or your desktop. You can download the "all platforms" distribution from the Oxygen XML Editor
website and extract it in the chosen folder.
To test your framework distribution, copy it in the frameworks directory of the newly installed application and start
Oxygen XML Editor by running the provided start-up script files.
You should copy the created schema files abs.xsd and sdf.xsd, sdf.xsd being the master schema, to the schema
directory and the CSS file sdf.css to the css directory.
Packaging and Deploying
Using a file explorer, go to the Oxygen XML Editor [OXYGEN_DIR]/frameworks directory. Select the sdf directory
and make an archive from it. Move it to another Oxygen XML Editor installation (eventually on another computer).
Extract it in the [OXYGEN_DIR]/frameworks directory. Start Oxygen XML Editor and test the association as
explained above.
If you create multiple document type associations and you have a complex directory structure it might be easy from the
deployment point of view to use an Oxygen XML Editor All Platforms distribution. Add your framework files to it,
repackage it and send it to the content authors.
Attention: When deploying your customized sdf directory, make sure that your sdf directory contains the
sdf.framework file (that is the file defined as External Storage in the Document Type Association preferences
page shall always be stored inside the sdf directory). If your external storage points somewhere else Oxygen
XML Editor will not be able to update the Document Type Association options automatically on the deployed
computers.
Configuring New File Templates
You will create a set of document templates that the content authors will use as starting points for creating Simple
Document Framework books and articles.
Each Document Type Association can point to a directory, usually named templates, containing the file templates.
All files found here are considered templates for the respective document type. The template name is taken from the
file name, and the template type is detected from the file extension.
1. Go to the [OXYGEN_DIR]\frameworks\sdf directory and create a directory named templates.
The directory tree of the documentation framework now is:
oxygen
frameworks
sdf
schema
css
templates
2. In the templates directory create two files: a file for the book template and another one for the article template.
You can also use editor variables in the template files' content and they will be expanded when the files are opened.
Note: You should avoid using the ${cfd},${cf},${currentFileURL}, and ${cfdu} editor variables
when you save your documents in a data base.
3. Open the Document Type configuration dialog box for the SDF framework and click the Templates tab. In the
Templates directory text field, introduce the ${frameworkDir}/templates path. As you have already seen
before, it is recommended that all the file references made from a Document Type Association to be relative to the
${frameworkDir} directory. Binding a Document Type Association to an absolute file (e. g.:
C:\some_dir\templates) makes the association difficult to share between users.
4. To test the templates settings, go to File > New to display the New document dialog box. The names of the two
templates are prefixed with the name of the Document Type Association (SDF in this case). Selecting one of them
should create a new XML file with the content specified in the template file.
Editor Variables
An editor variable is a shorthand notation for context-dependent information, such as a file or folder path, a time-stamp,
or a date. It is used in the definition of a command (for example, the input URL of a transformation, the output file path
of a transformation, or the command line of an external tool) to make a command or a parameter generic and re-usable
with other input files. When the same command is applied to different files, the notation is expanded at the execution
of the command so that the same command has different effects depending on the actual file.
You can use the following editor variables in Oxygen XML Editor commands of external engines or other external tools,
in transformation scenarios, Author mode operations, and in validation scenarios:
All frameworks are sorted, from high to low, according to their Priority setting from the Document Type
configuration dialog box. Only frameworks that have the Enabled checkbox set are taken into account.
Next, if the two or more frameworks have the same name and priority, a further sorting based on the
Storage setting is made, in the exact following order:
'message' - The displayed message. Note the quotes that enclose the message.
type - Optional parameter, with one of the following values:
Parameter
url
password
${ask('Input URL', url)} - The displayed dialog box has the name Input
URL. The expected input type is URL.
${ask('Input URL', url, 'http://www.example.com')} - The
displayed dialog box has the name Input URL. The expected input type is URL.
The input field displays the default value http://www.example.com.
generic
relative_url
combobox
${ask('File location', relative_url, 'C:/example.txt')} - The dialog box has the name
'File location'. The URL inserted in the input box is made relative to the
current edited document location.
radio
${date(pattern)} - Current date. The allowed patterns are equivalent to the ones in the Java SimpleDateFormat class.
Example: yyyy-MM-dd;
Note: This editor variable supports both the xs:date and xs:datetime parameters. For details about xs:date,
go to http://www.w3.org/TR/xmlschema-2/#date. For details about xs:datetime, go to
http://www.w3.org/TR/xmlschema-2/#dateTime.
${dbgXML} - The local file path to the XML document which is current selected in the Debugger source combo box
(for tools started from the XSLT/XQuery Debugger).
${dbgXSL} - The local file path to the XSL/XQuery document which is current selected in the Debugger stylesheet
combo box (for tools started from the XSLT/XQuery Debugger).
${tsf} - The transformation result file path. If the current opened file has an associated scenario which specifies a
transformation output file, this variable expands to it.
${dsu} - The path of the detected schema as an URL for the current validated XML document.
${ds} - The path of the detected schema as a local file path for the current validated XML document.
${cp} - Current page number. Used to display the current page number on each printed page in the Editor / Print
Preferences page.
${tp} - Total number of pages in the document. Used to display the total number of pages on each printed page in
the Editor / Print Preferences page.
${xpath_eval(expression)} - Evaluates an XPath 3.0 expression. Depending on the context, the expression can be:
static - When executed in a non-XML context. For example, you can use such static expressions to perform string
operations on other editor variables for composing the name of the output file in a transformation scenario's
Output tab.
Example:
${xpath_eval(upper-case(substring('${cfn}', 1, 4)))}
dynamic - When executed in an XML context. For example, you can use such dynamic expression in a code
template or as a value of a parameter of an Author mode operation.
Example:
${ask('Set new ID attribute', generic, '${xpath_eval(@id)}')}
Customize the stylesheet (add namespaces, etc.) that you want to become a template and save it to a file with an
appropriate name.
Copy the file to the templates directory in the Oxygen XML Editor installation directory.
Open Oxygen XML Editor and go to File > New to see your custom template.
2. Add catalog files to your Document Type Association using the Catalogs tab from the Document Type configuration
dialog box.
To test the catalog settings, restart Oxygen XML Editor and try to validate a new sample Simple Documentation
Framework document. There should be no errors.
The sdf.xsd schema that validates the document refers the other file abs.xsd through an import
element:
<xs:import namespace=
"http://www.oxygenxml.com/sample/documentation/abstracts"
schemaLocation="http://www.oxygenxml.com/SDF/abs.xsd"/>
2. Create the sdf.xsl file in the xsl folder. The complete content of the sdf.xsl file is found in the Example
Files Listings.
3. Open the Preferences dialog box and go to Document Type Associations. Open the Document Type dialog for
the SDF framework then choose the Transformation tab. Click the
New button and choose the appropriate
type of transformation (for example, XML transformation with XSLT).
In the New scenario dialog box, fill in the following fields:
Fill in the Name field with SDF to HTML. This will be the name of your transformation scenario.
Set the XSL URL field to ${framework}/xsl/sdf.xsl.
Set the Save as field to ${cfd}/${cfn}.html. This means the transformation output file will have the name
of the XML file and the html extension and will be stored in the same folder.
Enable the Open in Browser/System Application option.
Note: To set the browser or system application that will be used, open the Preferences dialog box, then
go to Global and set it in the Default Internet browser field. This will take precedence over the default
system application settings.
4. If you want to add a new validation unit, press the Add button.
5. To edit the URL of the main validation module, double-click its cell in the URL of the file to validate column.
Specify the URL of the main module by doing one of the following:
3. A Document Type ID and a short description should be defined first by implementing the methods
getDocumentTypeID and getDescription. The Document Type ID is used to uniquely identify the current
framework. Such an ID must be provided especially if options related to the framework need to be persistently stored
and retrieved between sessions.
public String getDocumentTypeID() {
return "Simple.Document.Framework.document.type";
}
public String getDescription() {
return "A custom extensions bundle used for the Simple Document" +
"Framework document type";
}
4. In order to be notified about the activation of the custom Author Extension in relation with an opened document an
ro.sync.ecss.extensions.api.AuthorExtensionStateListener should be implemented. The
activation and deactivation events received by this listener should be used to perform custom initializations and to
register / remove listeners like ro.sync.ecss.extensions.api.AuthorListener,
ro.sync.ecss.extensions.api.AuthorMouseListener or
ro.sync.ecss.extensions.api.AuthorCaretListener. The custom Author Extension state listener
should be provided by implementing the method createAuthorExtensionStateListener.
public AuthorExtensionStateListener createAuthorExtensionStateListener() {
return new SDFAuthorExtensionStateListener();
}
The AuthorExtensionStateListener is instantiated and notified about the activation of the framework
when the rules of the Document Type Association match a document opened in the Author editing mode. The listener
is notified about the deactivation when another framework is activated for the same document, the user switches to
another mode or the editor is closed. A complete description and implementation of an
ro.sync.ecss.extensions.api.AuthorExtensionStateListener can be found in the Implementing
an Author Extension State Listener.
If Schema Aware mode is active in Oxygen XML Editor, all actions that can generate invalid content will be redirected
toward the ro.sync.ecss.extensions.api.AuthorSchemaAwareEditingHandler. The handler
can either resolve a specific case, let the default implementation take place or reject the edit entirely by throwing an
ro.sync.ecss.extensions.api.InvalidEditException. The actions that are forwarded to this
handler include typing, delete or paste.
See Implementing an Author Mode Schema Aware Editing Handler on page 677 for more details about this handler.
5. Customizations of the content completion proposals are permitted by creating a schema manager filter extension.
The interface that declares the methods used for content completion proposals filtering is
ro.sync.contentcompletion.xml.SchemaManagerFilter. The filter can be applied on elements,
attributes or on their values. Responsible for creating the content completion filter is the method
createSchemaManagerFilter. A new SchemaManagerFilter will be created each time a document
matches the rules defined by the Document Type Association which contains the filter declaration.
public SchemaManagerFilter createSchemaManagerFilter() {
return new SDFSchemaManagerFilter();
}
A detailed presentation of the schema manager filter can be found in Configuring a Content completion handler
section.
6. The Author mode supports link based navigation between documents and document sections. Therefore, if the
document contains elements defined as links to other elements, for example links based on the id attributes, the
extension should provide the means to find the referenced content. To do this an implementation of the
The section that explains how to implement an element locator provider is Configuring a Link target element finder.
7. The drag and drop functionality can be extended by implementing the
ro.sync.exml.editor.xmleditor.pageauthor.AuthorDnDListener interface. Relevant methods
from the listener are invoked when the mouse is dragged, moved over, or exits the Author editing mode, when the
drop action changes, and when the drop occurs. Each method receives the DropTargetEvent containing information
about the drag and drop operation. The drag and drop extensions are available on Author mode for both Oxygen
XML Editor Eclipse plugin and standalone application. The Text mode corresponding listener is available only for
Oxygen XML Editor Eclipse plugin. The methods corresponding to each implementation are:
createAuthorAWTDndListener, createTextSWTDndListener and
createAuthorSWTDndListener.
public AuthorDnDListener createAuthorAWTDndListener() {
return new SDFAuthorDndListener();
}
For more details about the Author mode drag and drop listeners see the Configuring a custom Drag and Drop listener
section.
8. Another extension which can be included in the bundle is the reference resolver. In our case the references are
represented by the ref element and the attribute indicating the referenced resource is location. To be able to obtain
the content of the referenced resources you will have to implement a Java extension class which implements the
ro.sync.ecss.extensions.api.AuthorReferenceResolver. The method responsible for creating
the custom references resolver is createAuthorReferenceResolver. The method is called each time a
document opened in an Author editing mode matches the Document Type Association where the extensions bundle
is defined. The instantiated references resolver object is kept and used until another extensions bundle corresponding
to another Document Type is activated as result of the detection process.
public AuthorReferenceResolver createAuthorReferenceResolver() {
return new ReferencesResolver();
}
A more detailed description of the references resolver can be found in the Configuring a References Resolver section.
9. To be able to dynamically customize the default CSS styles for a certain
ro.sync.ecss.extensions.api.node.AuthorNode an implementation of the
ro.sync.ecss.extensions.api.StylesFilter can be provided. The extensions bundle method responsible
for creating the StylesFilter is createAuthorStylesFilter. The method is called each time a document
opened in an Author editing mode matches the document type association where the extensions bundle is defined.
The instantiated filter object is kept and used until another extensions bundle corresponding to another Document
Type is activated as a result of the detection process.
public StylesFilter createAuthorStylesFilter() {
return new SDFStylesFilter();
}
See the Configuring CSS styles filter section for more details about the styles filter extension.
10. In order to edit data in custom tabular format implementations of the
ro.sync.ecss.extensions.api.AuthorTableCellSpanProvider and the
ro.sync.ecss.extensions.api.AuthorTableColumnWidthProvider interfaces should be provided.
The two table information providers are not reused for different tables. The methods are called for each table in the
document so new instances should be provided every time. Read more about the cell span and column width
information providers in Configuring a Table Cell Span Provider and Configuring a Table Column Width Provider
sections.
If the functionality related to one of the previous extension point does not need to be modified then the developed
ro.sync.ecss.extensions.api.ExtensionsBundle should not override the corresponding method
and leave the default base implementation to return null.
11. An XML vocabulary can contain links to different areas of a document. If the document contains elements defined
as link, you can choose to present a more relevant text description for each link. To do this, an implementation of
the ro.sync.ecss.extensions.api.link.LinkTextResolver interface should be returned by the
createLinkTextResolver method. This implementation is used each time the oxy_link-text() function is
encountered in the CSS styles associated with an element.
public LinkTextResolver createLinkTextResolver() {
return new DitaLinkTextResolver();
}
Oxygen XML Editor offers built in implementations for DITA and DocBook:
ro.sync.ecss.extensions.dita.link.DitaLinkTextResolver
ro.sync.ecss.extensions.docbook.link.DocbookLinkTextResolver
12. Pack the compiled class into a jar file.
13. Copy the jar file into the frameworks/sdf directory.
14. Add the jar file to the class path. To do this, open the Preferences dialog box, go to Document Type Association,
select SDF, press the Edit button, select the Classpath tab and press the
Add button . In the displayed dialog
box, enter the location of the jar file, relative to the Oxygen XML Editor frameworks folder.
15. Register the Java class by going to the Extensions tab. Press the Choose button and select the name of the class:
SDFExtensionsBundle.
Note: The complete source code can be found in the Simple Documentation Framework project, included
in the oxygen-sample-framework module of the Oxygen SDK , available as a Maven archetype on the
Oxygen XML Editor website.
Customize Profiling Conditions
For each document type, you can configure the phrase-type elements that wrap the profiled content by setting a custom
ro.sync.ecss.extensions.api.ProfilingConditionalTextProvider. This configuration is set by
default for DITA and DocBook frameworks.
Customizing Smart Paste Support
The Smart Paste feature preserves certain style and structure information when copying content from some of the most
common applications and pasting into document types that support Smart Paste in Oxygen XML Editor. For other
document types, the default behavior of the paste operation is to keep only the text content without the styling.
The style of the pasted content can be customized by editing an XSLT stylesheet for the particular document type. The
XSLT stylesheet must accept an XHTML flavor of the copied content as input, and transform it to the equivalent XML
markup that is appropriate for the target document type of the paste operation.
The activation event received by this listener when the rules of the Document Type Association match a document
opened in the Author editing mode, should be used to perform custom initializations and to register listeners, such as
ro.sync.ecss.extensions.api.AuthorListener,
ro.sync.ecss.extensions.api.AuthorMouseListener, or
ro.sync.ecss.extensions.api.AuthorCaretListener.
public void activated(AuthorAccess authorAccess) {
// Get the value of the option.
String option = authorAccess.getOptionsStorage().getOption(
"sdf.custom.option.key", "");
// Use the option for some initializations...
// Add an OptionListener.
authorAccess.getOptionsStorage().addOptionListener(sdfOptionListener);
// Add author DocumentListeners.
sdfAuthorDocumentListener = new SDFAuthorListener();
authorAccess.getDocumentController().addAuthorListener(
sdfAuthorDocumentListener);
// Add MouseListener.
sdfMouseListener = new SDFAuthorMouseListener();
authorAccess.getEditorAccess().addAuthorMouseListener(sdfMouseListener);
// Add CaretListener.
sdfCaretListener = new SDFAuthorCaretListener();
authorAccess.getEditorAccess().addAuthorCaretListener(sdfCaretListener);
// Other custom initializations...
}
Implementing the AuthorSchemaAwareEditingHandler makes it possible to handle other events, such as the
keyboard delete event at the given offset (using Delete or Backspace keys), delete element tags, delete selection, join
elements, or paste fragment.
Note: The complete source code can be found in the Simple Documentation Framework project, included in
the oxygen-sample-framework module of the Oxygen SDK , available as a Maven archetype on the Oxygen
XML Editor website.
Configuring a Content Completion Handler
You can filter or contribute to items offered for content completion by implementing the
ro.sync.contentcompletion.xml.SchemaManagerFilter interface.
Note: The Javadoc documentation of the Author API used in the example files is available on the Oxygen XML
Editor website. Also it is available in the Oxygen SDK Maven Project.
import java.util.List;
import
import
import
import
import
import
import
import
ro.sync.contentcompletion.xml.CIAttribute;
ro.sync.contentcompletion.xml.CIElement;
ro.sync.contentcompletion.xml.CIValue;
ro.sync.contentcompletion.xml.Context;
ro.sync.contentcompletion.xml.SchemaManagerFilter;
ro.sync.contentcompletion.xml.WhatAttributesCanGoHereContext;
ro.sync.contentcompletion.xml.WhatElementsCanGoHereContext;
ro.sync.contentcompletion.xml.WhatPossibleValuesHasAttributeContext;
You can implement the various callbacks of the interface either by returning the default values given by Oxygen XML
Editor or by contributing to the list of proposals. The filter can be applied on elements, attributes or on their values.
Attributes filtering can be implemented using the filterAttributes method and changing the default content
completion list of ro.sync.contentcompletion.xml.CIAttribute for the element provided by the current
ro.sync.contentcompletion.xml.WhatAttributesCanGoHereContext context. For example, the
SDFSchemaManagerFilter checks if the element from the current context is the table element and adds the
frame attribute to the table list of attributes.
/**
* Filter attributes of the "table" element.
*/
public List<CIAttribute> filterAttributes(List<CIAttribute> attributes,
WhatAttributesCanGoHereContext context) {
// If the element from the current context is the 'table' element add the
// attribute named 'frame' to the list of default content completion proposals
if (context != null) {
ContextElement contextElement = context.getParentElement();
The elements that can be inserted in a specific context can be filtered using the filterElements method. The
SDFSchemaManagerFilter uses this method to replace the td child element with the th element when header
is the current context element.
public List<CIElement> filterElements(List<CIElement> elements,
WhatElementsCanGoHereContext context) {
// If the element from the current context is the 'header' element remove the
// 'td' element from the list of content completion proposals and add the
// 'th' element.
if (context != null) {
Stack<ContextElement> elementStack = context.getElementStack();
if (elementStack != null) {
ContextElement contextElement = context.getElementStack().peek();
if ("header".equals(contextElement.getQName())) {
if (elements != null) {
for (Iterator<CIElement> iterator = elements.iterator(); iterator.hasNext();) {
CIElement element = iterator.next();
// Remove the 'td' element
if ("td".equals(element.getQName())) {
elements.remove(element);
break;
}
}
} else {
elements = new ArrayList<CIElement>();
}
// Insert the 'th' element in the list of content completion proposals
CIElement thElement = new SDFElement();
thElement.setName("th");
elements.add(thElement);
}
}
} else {
// If the given context is null then the given list of content completion elements contains
// global elements.
}
return elements;
}
The elements or attributes values can be filtered using the filterElementValues or filterAttributeValues
methods.
Note: The complete source code can be found in the Simple Documentation Framework project, included in
the oxygen-sample-framework module of the Oxygen SDK , available as a Maven archetype on the Oxygen
XML Editor website.
Configuring a Link target element finder
The link target reference finder represents the support for finding references from links which indicate specific elements
inside an XML document. This support will only be available if a schema is associated with the document type.
If you do not define a custom link target reference finder, the DefaultElementLocatorProvider implementation
will be used by default. The interface which should be implemented for a custom link target reference finder is
ro.sync.ecss.extensions.api.link.ElementLocatorProvider. As an alternative, the
ro.sync.ecss.extensions.commons.DefaultElementLocatorProvider implementation can also be
extended.
The used ElementLocatorProvider will be queried for an ElementLocator when a link location must be
determined (when a link is clicked). Then, to find the corresponding (linked) element, the obtained ElementLocator
will be queried for each element from the document.
The method getElementLocator determines what ElementLocator should be used. In the default implementation
it checks if the link is an XPointer element() scheme otherwise it assumes it is an ID. A non-null IDTypeVerifier
will always be provided if a schema is associated with the document type.
The link string argument is the "anchor" part of the of the URL which is composed from the value of the link property
specified for the link element in the CSS.
public ElementLocator getElementLocator(IDTypeVerifier idVerifier,
String link) {
ElementLocator elementLocator = null;
try {
if(link.startsWith("element(")){
// xpointer element() scheme
elementLocator = new XPointerElementLocator(idVerifier, link);
} else {
// Locate link element by ID
elementLocator = new IDElementLocator(idVerifier, link);
}
} catch (ElementLocatorException e) {
logger.warn("Exception when create element locator for link: "
+ link + ". Cause: " + e, e);
}
return elementLocator;
}
The method startElement will be invoked at the beginning of every element in the XML document(even when the
element is empty). The arguments it takes are
uri
The namespace URI, or the empty string if the element has no namespace URI or if namespace processing is disabled.
localName
Local name of the element.
qName
Qualified name of the element.
atts
Attributes attached to the element. If there are no attributes, this argument will be empty.
The method returns true if the processed element is found to be the one indicated by the link.
The XPointerElementLocator implementation of the startElement will update the depth of the current
element and keep the index of the element in its parent. If the xpointerPath starts with an element ID then the
current element ID is verified to match the specified ID. If this is the case the depth of the XPointer is updated taking
into account the depth of the current element.
If the XPointer path depth is the same as the current element depth then the kept indices of the current element path are
compared to the indices in the XPointer path. If all of them match then the element has been found.
public boolean startElement(String uri, String localName,
String name, Attr[] atts) {
boolean linkLocated = false;
// Increase current element document depth
startElementDepth ++;
if (endElementDepth != startElementDepth) {
// The current element is the first child of the parent
currentElementIndexStack.push(new Integer(1));
} else {
// Another element in the parent element
currentElementIndexStack.push(new Integer(lastIndexInParent + 1));
}
if (startWithElementID) {
// This the case when xpointer path starts with an element ID.
String xpointerElement = xpointerPath[0];
for (int i = 0; i < atts.length; i++) {
The method endElement will be invoked at the end of every element in the XML document (even when the element
is empty).
The XPointerElementLocator implementation of the endElement updates the depth of the current element
path and the index of the element in its parent.
public void endElement(String uri, String localName, String name) {
endElementDepth = startElementDepth;
startElementDepth --;
lastIndexInParent = ((Integer)currentElementIndexStack.pop()).intValue();
}
The attribute type is checked with the help of the method IDTypeVerifier.hasIDType.
public boolean startElement(String uri, String localName,
String name, Attr[] atts) {
boolean elementFound = false;
for (int i = 0; i < atts.length; i++) {
if (link.equals(atts[i].getValue())) {
if("xml:id".equals(atts[i].getQName())) {
// xml:id attribute
elementFound = true;
} else {
// check if attribute has ID type
String attrLocalName =
ExtensionUtil.getLocalName(atts[i].getQName());
String attrUri = atts[i].getNamespace();
if (idVerifier.hasIDType(localName, uri, attrLocalName, attrUri)) {
Description
ro.sync.exml.editor.xmleditor.pageauthor.AuthorDnDListener Receives callbacks from the standalone application for
Drag And Drop in Author mode.
com.oxygenxml.editor.editors.author.AuthorDnDListener Receives callbacks from the Eclipse plugin for Drag And
Drop in Author mode.
com.oxygenxml.editor.editors.TextDnDListener Receives callbacks from the Eclipse plugin for Drag And
Drop in Text mode.
Configuring a References Resolver
You need to provide a handler for resolving references and obtain the content they reference. In our case the element
which has references is ref and the attribute indicating the referenced resource is location. You will have to implement
a Java extension class for obtaining the referenced resources.
Note: The Javadoc documentation of the Author API used in the example files is available on the Oxygen XML
Editor website. Also it is available in the Oxygen SDK Maven Project.
1. Create the class simple.documentation.framework.ReferencesResolver. This class must implement
the ro.sync.ecss.extensions.api.AuthorReferenceResolver interface.
import
import
import
import
import
ro.sync.ecss.extensions.api.AuthorReferenceResolver;
ro.sync.ecss.extensions.api.AuthorAccess;
ro.sync.ecss.extensions.api.node.AttrValue;
ro.sync.ecss.extensions.api.node.AuthorElement;
ro.sync.ecss.extensions.api.node.AuthorNode;
3. The method getDisplayName returns the display name of the node that contains the expanded referenced content.
It takes as argument an AuthorNode that represents the node for which the display name is needed. The referenced
content engine will ask this AuthorReferenceResolver implementation what is the display name for each
node which is considered a reference. In our case the display name is the value of the location attribute from the ref
element.
public String getDisplayName(AuthorNode node) {
String displayName = "ref-fragment";
if (node.getType() == AuthorNode.NODE_TYPE_ELEMENT) {
AuthorElement element = (AuthorElement) node;
if ("ref".equals(element.getLocalName())) {
AttrValue attrValue = element.getAttribute("location");
if (attrValue != null) {
displayName = attrValue.getValue();
}
}
}
return displayName;
}
4. The method resolveReference resolves the reference of the node and returns a SAXSource with the parser
and the parser's input source. It takes as arguments an AuthorNode that represents the node for which the reference
needs resolving, the systemID of the node, the AuthorAccess with access methods to the Author mode data
model and a SAX EntityResolver which resolves resources that are already opened in another editor or resolve
resources through the XML catalog. In the implementation you need to resolve the reference relative to the systemID,
and create a parser and an input source over the resolved reference.
public SAXSource resolveReference(
AuthorNode node,
String systemID,
AuthorAccess authorAccess,
EntityResolver entityResolver) {
SAXSource saxSource = null;
if (node.getType() == AuthorNode.NODE_TYPE_ELEMENT) {
AuthorElement element = (AuthorElement) node;
if ("ref".equals(element.getLocalName())) {
AttrValue attrValue = element.getAttribute("location");
if (attrValue != null) {
String attrStringVal = attrValue.getValue();
try {
URL absoluteUrl = new URL(new URL(systemID),
authorAccess.getUtilAccess().correctURL(attrStringVal));
InputSource inputSource = entityResolver.resolveEntity(null,
absoluteUrl.toString());
if(inputSource == null) {
inputSource = new InputSource(absoluteUrl.toString());
}
XMLReader xmlReader = authorAccess.newNonValidatingXMLReader();
xmlReader.setEntityResolver(entityResolver);
saxSource = new SAXSource(xmlReader, inputSource);
} catch (MalformedURLException e) {
logger.error(e, e);
} catch (SAXException e) {
logger.error(e, e);
} catch (IOException e) {
logger.error(e, e);
}
5. The method getReferenceUniqueID should return an unique identifier for the node reference. The unique
identifier is used to avoid resolving the references recursively. The method takes as argument an AuthorNode that
represents the node with the reference. In the implementation the unique identifier is the value of the location attribute
from the ref element.
public String getReferenceUniqueID(AuthorNode node) {
String id = null;
if (node.getType() == AuthorNode.NODE_TYPE_ELEMENT) {
AuthorElement element = (AuthorElement) node;
if ("ref".equals(element.getLocalName())) {
AttrValue attrValue = element.getAttribute("location");
if (attrValue != null) {
id = attrValue.getValue();
}
}
}
return id;
}
6. The method getReferenceSystemIDshould return the systemID of the referenced content. It takes as arguments
an AuthorNode that represents the node with the reference and the AuthorAccess with access methods to the
Author mode data model. In the implementation you use the value of the location attribute from the ref element and
resolve it relatively to the XML base URL of the node.
public String getReferenceSystemID(AuthorNode node,
AuthorAccess authorAccess) {
String systemID = null;
if (node.getType() == AuthorNode.NODE_TYPE_ELEMENT) {
AuthorElement element = (AuthorElement) node;
if ("ref".equals(element.getLocalName())) {
AttrValue attrValue = element.getAttribute("location");
if (attrValue != null) {
String attrStringVal = attrValue.getValue();
try {
URL absoluteUrl = new URL(node.getXMLBaseURL(),
authorAccess.getUtilAccess().correctURL(attrStringVal));
systemID = absoluteUrl.toString();
} catch (MalformedURLException e) {
logger.error(e, e);
}
}
}
}
return systemID;
}
Note: The complete source code can be found in the Simple Documentation Framework project, included
in the oxygen-sample-framework module of the Oxygen SDK , available as a Maven archetype on the
Oxygen XML Editor website.
In the listing below, the XML document contains the ref element:
<ref location="referenced.xml">Reference</ref>
When no reference resolver is specified, the reference has the following layout:
ro.sync.ecss.css.Styles;
ro.sync.ecss.extensions.api.StylesFilter;
ro.sync.ecss.extensions.api.node.AuthorNode;
ro.sync.exml.view.graphics.Font;
Configuring tables
There are standard CSS properties used to indicate what elements are tables, table rows and table cells. What CSS is
missing is the possibility to indicate the cell spanning, row separators or the column widths. Oxygen XML Editor offers
support for adding extensions to solve these problems. This will be presented in the next chapters.
The table in this example is a simple one. The header must be formatted in a different way than the ordinary rows, so it
will have a background color.
table{
display:table;
border:1px solid navy;
margin:1em;
max-width:1000px;
min-width:150px;
}
table[width]{
width:attr(width, length);
}
tr, header{
display:table-row;
}
header{
background-color: silver;
color:inherit
}
Since in the schema, the td tag has the attributes row_span and column_span that are not automatically recognized
by Oxygen XML Editor, a Java extension will be implemented which will provide information about the cell spanning.
See the section Configuring a Table Cell Span Provider.
The column widths are specified by the attributes width of the elements customcol that are not automatically recognized
by Oxygen XML Editor. It is necessary to implement a Java extension which will provide information about the column
widths. See the section Configuring a Table Column Width Provider.
The table from our example does not make use of the attributes colsep and rowsep (which are automatically
recognized) but we still want the rows to be separated by horizontal lines. It is necessary to implement a Java extension
which will provide information about the row and column separators. See the section Configuring a Table Cell Row
And Column Separator Provider on page 692.
Configuring a Table Column Width Provider
In the sample documentation framework the table element as well as the table columns can have specified widths. In
order for these widths to be considered by Author mode we need to provide the means to determine them. As explained
in the Configuring tables on page 686, if you use the table element attribute width Oxygen XML Editor can determine
the table width automatically. In this example the table has col elements with width attributes that are not recognized
by default. You will need to implement a Java extension class to determine the column widths.
Note: The Javadoc documentation of the Author API used in the example files is available on the Oxygen XML
Editor website. Also it is available in the Oxygen SDK Maven Project.
1. Create the class simple.documentation.framework.TableColumnWidthProvider. This class must
implement the ro.sync.ecss.extensions.api.AuthorTableColumnWidthProvider interface.
import
import
import
import
import
ro.sync.ecss.extensions.api.AuthorAccess;
ro.sync.ecss.extensions.api.AuthorOperationException;
ro.sync.ecss.extensions.api.AuthorTableColumnWidthProvider;
ro.sync.ecss.extensions.api.WidthRepresentation;
ro.sync.ecss.extensions.api.node.AuthorElement;
4. The method isTableAndColumnsResizable should check if the table cells are td. This method determines
if the table and its columns can be resized by dragging the edge of a column.
public boolean isTableAndColumnsResizable(String tableCellsTagName) {
return "td".equals(tableCellsTagName);
}
5. Methods getTableWidth and getCellWidth are used to determine the table and column width. The table
layout engine will ask this ro.sync.ecss.extensions.api.AuthorTableColumnWidthProvider
implementation what is the table width for each table element and the cell width for each cell element from the table
that was marked as cell in the CSS using the property display:table-cell. The implementation is simple and
just parses the value of the width attribute. The methods must return null for the tables / cells that do not have a
specified width.
public WidthRepresentation getTableWidth(String tableCellsTagName) {
WidthRepresentation toReturn = null;
if (tableElement != null && "td".equals(tableCellsTagName)) {
AttrValue widthAttr = tableElement.getAttribute("width");
if (widthAttr != null) {
String width = widthAttr.getValue();
if (width != null) {
toReturn = new WidthRepresentation(width, true);
}
}
}
return toReturn;
}
7. The following three methods are used to determine what type of column width specifications the table column width
provider support. In our case all types of specifications are allowed:
public boolean isAcceptingFixedColumnWidths(String tableCellsTagName) {
return true;
}
public boolean isAcceptingPercentageColumnWidths(String tableCellsTagName) {
return true;
}
public boolean isAcceptingProportionalColumnWidths(String tableCellsTagName) {
return true;
}
Note: The complete source code can be found in the Simple Documentation Framework project, included
in the oxygen-sample-framework module of the Oxygen SDK , available as a Maven archetype on the
Oxygen XML Editor website.
In the listing below, the XML document contains the table element:
<table width="300">
<customcol width="50.0px"/>
<customcol width="1*"/>
<customcol width="2*"/>
<customcol width="20%"/>
<header>
<td>C1</td>
<td>C2</td>
<td>C3</td>
<td>C4</td>
</header>
<tr>
<td>cs=1, rs=1</td>
<td>cs=1, rs=1</td>
<td row_span="2">cs=1, rs=2</td>
<td row_span="3">cs=1, rs=3</td>
</tr>
<tr>
<td>cs=1, rs=1</td>
<td>cs=1, rs=1</td>
</tr>
<tr>
<td column_span="3">cs=3, rs=1</td>
</tr>
</table>
3. The getColSpan method is taking as argument the table cell. The table layout engine will ask this
AuthorTableSpanSupport implementation what is the column span and the row span for each XML element
from the table that was marked as cell in the CSS using the property display:table-cell. The implementation
is simple and just parses the value of column_span attribute. The method must return null for all the cells that do
not change the span specification.
public Integer getColSpan(AuthorElement cell) {
Integer colSpan = null;
AttrValue attrValue = cell.getAttribute("column_span");
if(attrValue != null) {
// The attribute was found.
String cs = attrValue.getValue();
if(cs != null) {
try {
colSpan = new Integer(cs);
} catch (NumberFormatException ex) {
// The attribute value was not a number.
}
}
}
return colSpan;
}
5. The method hasColumnSpecifications always returns true considering column specifications always
available.
public boolean hasColumnSpecifications(AuthorElement tableElement) {
return true;
}
Note: The complete source code can be found in the Simple Documentation Framework project, included
in the oxygen-sample-framework module of the Oxygen SDK , available as a Maven archetype on the
Oxygen XML Editor website.
6. In the listing below, the XML document contains the table element:
<table>
<header>
<td>C1</td>
<td>C2</td>
<td>C3</td>
<td>C4</td>
</header>
<tr>
<td>cs=1, rs=1</td>
<td column_span="2" row_span="2">cs=2, rs=2</td>
<td row_span="3">cs=1, rs=3</td>
</tr>
When no table cell span provider is specified, the table has the following layout:
3. The getColSep method is taking as argument the table cell. The table layout engine will ask this
AuthorTableCellSepProvider implementation if there is a column separator for each XML element from
the table that was marked as cell in the CSS using the property display:table-cell. In our case we choose
to return false since we do not need column separators.
/**
* @return false - No column separator at the right of the cell.
*/
@Override
public boolean getColSep(AuthorElement cellElement, int columnIndex) {
return false;
}
4. The row separators are determined in a similar manner. This time the method returns true, forcing a separator between
the rows.
/**
* @return true - A row separator below each cell.
*/
@Override
public boolean getRowSep(AuthorElement cellElement, int columnIndex) {
return true;
}
Note: The complete source code can be found in the Simple Documentation Framework project, included
in the oxygen-sample-framework module of the Oxygen SDK , available as a Maven archetype on the
Oxygen XML Editor website.
5. In the listing below, the XML document contains the table element:
<table>
<header>
<td>H1</td>
<td>H2</td>
<td>H3</td>
<td>H4</td>
</header>
<tr>
<td>C11</td>
<td>C12</td>
<td>C13</td>
<td>C14</td>
</tr>
<tr>
<td>C21</td>
When the borders for the td element are removed from the CSS, the row separators become visible:
Automatic ID generation - You can automatically generate unique IDs for newly inserted elements. Implementations
are already available for the DITA and DocBook frameworks. The following methods can be implemented to
accomplish this: assignUniqueIDs(int startOffset, int endOffset),
isAutoIDGenerationActive()
Avoiding copying unique attributes when "Split" is called inside an element - You can split the current block
element by pressing the "Enter" key and then choosing "Split". This is a very useful way to create new paragraphs,
for example. All attributes are by default copied on the new element but if those attributes are IDs you sometimes
want to avoid creating validation errors in the editor. Implementing the following method, you can decide whether
an attribute should be copied or not during the split: boolean copyAttributeOnSplit(String
attrQName, AuthorElement element)
Tip:
The ro.sync.ecss.extensions.commons.id.DefaultUniqueAttributesRecognizer
class is an implementation of the interface which can be extended by your customization to provide easy
assignation of IDs in your framework. You can also check out the DITA and DocBook implementations of
ro.sync.ecss.extensions.api.UniqueAttributesRecognizer to see how they were
implemented and connected to the extensions bundle.
Figure 322: CSS Subtab of the Document Type Association Author Tab
3. Add the new stylesheet as an alternate CSS stylesheet:
After your team members install the framework they can check the list of Document Types in the Document Type
Association preferences page to see if the framework is present and if it appears before the bundled DITA framework
(meaning that it has higher priority).
Adding Custom Persistent Highlights
The Author API includes a class that allows you to create or remove custom persistent highlights, set new properties
for the highlights, and customize their appearance. An example of a possible use case would be if you want to implement
your own way of editing review comments. The custom persistent highlights get serialized in the XML document as
processing instructions, with the following format:
<?oxy_custom_start prop1="val1"....?> xml content <?oxy_custom_end?>
This functionality is available through the AuthorPersistentHighlighter class that is accessible through the
AuthorEditorAccess#getPersistentHighlighter() method.
For more information, see the JavaDoc details for this class at
http://www.oxygenxml.com/InstData/Editor/SDK/javadoc/ro/sync/ecss/extensions/api/highlights/AuthorPersistentHighlighter.html.
Providing Additional Documentation for XML Elements and Attributes
Oxygen XML Editor gathers documentation from the associated schemas (DTD, XML Schema, RelaxNG) and presents
it for each element or attribute. For example, if you open the Content Completion Assistant for a recognized XML
vocabulary, documentation is displayed for each element provided by the associated schema. Similar information is
displayed when you hover over tag names presented in the Elements view. If you hover over attributes in the Attributes
view you also see information about each attribute, gathered from the same schema.
If you have a document type configuration set up for your XML vocabulary, there is a special XML configuration file
that can be added to provide additional documentation information or links to specification web pages for certain elements
and attributes. To provide this additional information, follow these steps:
1. Create a new folder in the configuration directory for the document type.
OXYGEN_INSTALL_DIR/frameworks/dita/styleguide
2. Use the New document wizard to create a file using the Oxygen content completion styleguide file
template.
3. Save the file in the folder created in step 1, using the fixed name: contentCompletionElementsMap.xml.
4. Open the Preferences dialog box, go to Document Type Association, and edit the document type configuration for
your XML vocabulary. Now you need to indicate where Oxygen XML Editor will locate your mapping file by doing
one of the following:
where {processed_dt_name} is the name of the document type in lower case and with spaces replaced by
underscores.
Note: If Oxygen XML Editor finds a mapping file in both locations, the one in the Catalogs tab takes
precedence.
5. Make the appropriate changes to your custom mapping file.
You can look at how the DITA mapping file is
configured:OXYGEN_INSTALL_DIR/frameworks/dita/styleguide/contentCompletionElementsMap.xml
The associated XML Schema contains additional details about how each element and attribute is used in the mapping
file.
6. Re-open the application and open an XML document.
In the Content Completion Assistant you should see the additional annotations for each element.
Configuring the Proposals in the Content Completion Assistant
Oxygen XML Editor gathers information from the associated schemas (DTDs, XML Schema, RelaxNG) to determine
the proposals that appear in the Content Completion Assistant. Oxygen XML Editor also includes support that allows
you to configure the possible attribute or element values for the proposals. To do so, a configuration file can be used,
along with the associated schema, to add or replace possible values for attributes or elements that are proposed in the
Content Completion Assistant. An example of a specific use-case is if you want the Content Completion Assistant
to propose several possible values for the language code whenever you use an xml:lang attribute.
To configure content completion proposals, follow these steps:
1. Create a new resources folder (if it does not already exist) in the frameworks directory for the document type.
For instance: OXYGEN_INSTALL_DIR/frameworks/dita/resources.
2. Open the Preferences dialog box and go to Document Type Association. Edit the document type configuration for
your XML vocabulary, and in the Classpath tab add a link to that resources folder.
3. Use the New document wizard to create a configuration file using the Content Completion Configuration file
template.
4. Make the appropriate changes to your custom configuration file. The file template includes details about how each
element and attribute is used in the configuration file.
5. Save the file in the resources folder, using the fixed name: cc_value_config.xml.
6. Re-open the application and open an XML document. In the Content Completion Assistant you should see your
customizations.
The Configuration File
The configuration file is composed of a series of match instructions that will match either an element or an attribute
name. A new value is specified inside one or more item elements, which are grouped inside an items element. The
behavior of the items element is specified with the help of the action attribute, which can have any of the following
values:
append - Adds new values to appear in the proposals list (default value).
addIfEmpty - Adds new values to the proposals list, only if no other values are contributed by the schema.
replace - Replaces the values contributed by the schema with new values to appear in the proposals list.
In this example, the get_values_from_db.xsl is executed in order to extract values from a database.
Note: A comprehensive XSLT sample is included in the Content Completion Configuration file template.
Configuring Proposals in the Context for which the Content Completion was Invoked
A more complex scenario for configuring the content completion proposals would be if you want to choose the possible
values to provide, depending on the context of the element in which the content completion was invoked.
Suppose that you want to propose certain possible values for one property (for example, color) and other values for
another property (for example, shape). If the property represents a color, then the values should represent applicable
colors, while if the property represents a shape, then the values should represent applicable shapes. See the following
code snippets:
Your main document:
<sampleArticle>
<!-- The possible values for @value should be "red" and "blue" -->
<property name="color" value=""/>
<!-- The possible values for @value should be "square" and "rectangle" -->
<property name="shape" value=""/>
</sampleArticle>
The stylesheet that defines the possible values based on the context of the property on which the content completion
was invoked:
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:saxon="http://saxon.sf.net/"
exclude-result-prefixes="xs"
version="2.0">
<xsl:param name="documentSystemID" as="xs:string"></xsl:param>
<xsl:param name="contextElementXPathExpression" as="xs:string"></xsl:param>
<xsl:template name="start">
<xsl:apply-templates select="doc($documentSystemID)"/>
</xsl:template>
The contextElementXPathExpression parameter will be bound to an XPath expression that identifies the
element in the context for which the content completion was invoked.
abs.xsd
This sample file can also be found in the Oxygen SDK distribution in the "oxygensdk\samples\Simple
Documentation Framework - SDF\framework\schema" directory.
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace=
"http://www.oxygenxml.com/sample/documentation/abstracts">
<xs:element name="def" type="xs:string"/>
</xs:schema>
CSS
CSS file listing.
sdf.css
This sample file can also be found in the Oxygen SDK distribution in the oxygensdk\samples\Simple
Documentation Framework - SDF\framework\css directory.
/* Element from another namespace */
@namespace abs "http://www.oxygenxml.com/sample/documentation/abstracts";
abs|def{
font-family:monospace;
font-size:smaller;
}
XML
XML file listing.
sdf_sample.xml
This sample file can also be found in the Oxygen SDK distribution in the "oxygensdk\samples\Simple
Documentation Framework - SDF\framework" directory.
<?xml version="1.0" encoding="UTF-8"?>
<book xmlns="http://www.oxygenxml.com/sample/documentation"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:abs="http://www.oxygenxml.com/sample/documentation/abstracts">
<title>My Technical Book</title>
<section>
<title>XML</title>
<abs:def>Extensible Markup Language</abs:def>
<para>In this section of the book I will explain
different XML applications.</para>
</section>
<section>
<title>Accessing XML data.</title>
<section>
<title>XSLT</title>
<abs:def>Extensible stylesheet language
transformation (XSLT) is a language for
transforming XML documents into other XML
documents.</abs:def>
<para>A list of XSL elements and what they do..</para>
<table>
<header>
<td>XSLT Elements</td>
<td>Description</td>
</header>
<tr>
<td>
<b>xsl:stylesheet</b>
</td>
<td>The <i>xsl:stylesheet</i> element is
always the top-level element of an
XSL stylesheet. The name
<i>xsl:transform</i> may be used
as a synonym.</td>
</tr>
<tr>
<td>
<b>xsl:template</b>
</td>
<td>The <i>xsl:template</i> element has
an optional mode attribute. If this
is present, the template will only
be matched when the same mode is
used in the invoking
<i>xsl:apply-templates</i>
element.</td>
</tr>
<tr>
<td>
<b>for-each</b>
</td>
<td>The xsl:for-each element causes
iteration over the nodes selected by
a node-set expression.</td>
</tr>
<tr>
<td column_span="2">End of the list</td>
XSL
XSL file listing.
sdf.xsl
This sample file can also be found in the Oxygen SDK distribution in the "oxygensdk\samples\Simple
Documentation Framework - SDF\framework\xsl" directory.
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="2.0"
xpath-default-namespace=
"http://www.oxygenxml.com/sample/documentation">
<xsl:template match="/">
<html><xsl:apply-templates/></html>
</xsl:template>
<xsl:template match="section">
<xsl:apply-templates/>
</xsl:template>
<xsl:template match="image">
<img src="{@href}"/>
</xsl:template>
<xsl:template match="para">
<p>
This extra mapped CSS location will be parsed every time the application processes the CSS stylesheets used to render
the opened XML document in the visual Author editing mode. This allows your custom CSS to be used without the
need to modify all other CSS stylesheets contributed in the document type configuration.
Figure 323: Main and Alternate CSS Styles in the Document Type Association Dialog Box
The URI column shows the path of each CSS file. The names listed in the Styles drop-down menu match the values in
the Title column. The value in the Alternate column determines whether it is a main or alternate CSS. If the value is
no it is a main CSS. If the value is yes it is an alternate CSS and the style can be combined with a main CSS or other
alternate styles when using the Styles drop-down menu.
Note: To group alternate styles into categories (submenus), use a vertical bar character ( | ) in the Title column.
You can use multiple vertical bars for multiple submenus. The text before each vertical bar will be rendered as
the name of a submenu entry in the Styles drop-down menu, while the text after the final vertical bar will be
rendered as the name of the style inside the submenu.
Example: Suppose that you want to add two alternate stylesheets in separate submenus, with the Title column
set to My Styles|User Assistance|Hints and My Styles|User Actions|Inline Actions,
respectively. Oxygen XML Editor will add a My Styles submenu with two submenus (User Assistance
that contains the Hints style, and User Actions that contains the Inline Actions style) in the Styles
drop-down menu.
The Enable multiple selection of alternate CSSs box at the bottom of the pane must be checked in order for the
alternate styles to be combined. They are applied like layers and you can activate any number of them. If this option is
disabled, the alternate styles are treated like main CSS styles and you can only select one at a time. By default, this
The selections from the Styles drop-down menu are persistent, meaning that Oxygen XML Editor will remember the
selections when subsequent documents are opened.
Note: The application also supports working directly with LESS stylesheets, instead of CSS.
CSS Styles in DITA
Oxygen XML Editor comes with a set of predefined CSS layer stylesheets for DITA documents
(including maps). In the subsequent figure, a DITA document has the Century style selected for the
main CSS and the alternate styles Full width, Show table column specification, Hints, and Inline
actions are combined for additive styling to specific parts of the document.
Tip: The Hints style displays tooltips throughout DITA documents that offer
additional information to help you with the DITA structure. The Inline actions style
displays possible elements that are allowed to be inserted at various locations
throughout DITA documents.
This example results in the text being bold if the document is opened in a web browser that does not recognize @media
oxygen, while the text is bold and underlined when opened in Oxygen XML Editor Author mode.
Name
CSS Level
Description / Example
Universal selector
CSS Level 2
Type selector
CSS Level 2
E F
Descendant selector
CSS Level 2
E > F
Child selectors
CSS Level 2
E:lang(c)
Language pseudo-class
CSS Level 2
E + F
Adjacent selector
CSS Level 2
E ~ F
CSS Level 3
E[foo]
Attribute selector
CSS Level 2
CSS Level 2
E[lang|="en"]
CSS Level 2
E:before and
E:after
Pseudo elements
CSS Level 2
Name
CSS Level
Description / Example
generated content before or after an
element's content.
CSS Level 3
E:first-child
CSS Level 2
E:not(s)
Negation pseudo-class
CSS Level 2
E:has
Relational pseudo-class
CSS Level 4
E:hover
CSS Level 2
E:focus
CSS Level 2
E:focus-within
CSS Level 4
E#myid
The ID selector
CSS Level 2
E[att^="val"]
CSS Level 3
E[att$="val"]
CSS Level 3
Name
CSS Level
Description / Example
E[att*="val"]
CSS Level 3
E:root
Root pseudo-class
CSS Level 3
E:empty
Empty pseudo-class
CSS Level 3
E:nth-child(n)
CSS Level 3
CSS Level 3
CSS Level 3
CSS Level 3
CSS Level 3
E:last-of-type
CSS Level 3
E:only-child
CSS Level 3
E:only-of-type
CSS Level 3
ns|E
CSS Level 3
E:last-child
@namespace ns
"http://some_namespace_uri";
CSS Level 4
(experimental)
Namespace Selector
In the CSS 2.1 standard the element selectors are ignoring the namespaces of the elements they are matching. Only the
local name of the elements are considered in the selector matching process.
Oxygen XML Editor uses a different approach similar to the CSS Level 3 specification. If the element name from the
CSS selector is not preceded by a namespace prefix it is considered to match an element with the same local name as
the selector value and ANY namespace, otherwise the element must match both the local name and the namespace.
In CSS up to version 2.1 the name tokens from selectors are matching all elements from ANY namespace that have the
same local name. Example:
<x:b xmlns:x="ns_x"/>
<y:b xmlns:y="ns_y"/>
Starting with CSS Level 3 you can create selectors that are namespace aware.
Defining both prefixed namespaces and the default namespace
Given the namespace declarations:
@namespace sync "http://sync.example.org";
@namespace "http://example.com/foo";
Then:
sync|A
represents the name A in the http://sync.example.org namespace.
|B
represents the name B that belongs to NO NAMESPACE.
*|C
represents the name C in ANY namespace, including NO NAMESPACE.
D
represents the name D in ANY namespace, including NO NAMESPACE.
Then:
A border will be drawn to the table elements that contain a caption as direct child.
This is different from:
table > caption {
border: 1px solid red;
}
and:
a! > b > c
This will result in a border being drawn for the table elements that contain at least a thead element
in the tbody element.
and
:has(> b > c)
Rendered Values
'background-attachment'
NONE
'background-color'
<color> | inherit
'background-image'
'background-position'
'background-repeat'
repeat | repeat-x |
repeat-y | no-repeat |
inherit
'background'
NONE
'border-collapse'
NONE
'border-color'
<color> | inherit
'border-spacing'
NONE
'border-style'
<border-style> | inherit
Ignored Values
transparent
<percentage> | <length>
transparent
<color> | inherit
'border-top-style'
'border-right-style'
'border-bottom-style'
'border-left-style'
<border-style> | inherit
'border-top-width'
'border-right-width'
'border-bottom-width'
'border-left-width'
<border-width> | inherit
'border-width'
<border-width> | inherit
transparent
Rendered Values
Ignored Values
'border'
[ <border-width> ||
<border-style> ||
<border-color> ] | inherit
'bottom'
'caption-side'
NONE
'clear'
NONE
'clip'
NONE
'color'
<color> | inherit
'content'
'counter-increment'
[ <identifier> <integer>
? ]+ | none | inherit
'counter-reset'
[ <identifier> <integer>
? ]+ | none | inherit
'cursor'
NONE
'direction'
'display'
'empty-cells'
'float'
NONE
'font-family'
[[ <family-name> |
<generic-family> ] [,
<family-name> |
<generic-family> ]* ] |
inherit
'font-size'
<absolute-size> |
<relative-size> | <length>
| <percentage> | inherit
'font-style'
'font-variant'
NONE
'font-weight'
Rendered Values
Ignored Values
[ [ 'font-style' ||
'font-weight' ]?
'font-size' [ /
'line-height' ]?
'font-family' ] | inherit
'font-variant'
'line-height' caption |
icon | menu | message-box
| small-caption |
status-bar
'height'
NONE
'left'
'letter-spacing'
normal | <length> |
inherit
'line-height'
normal | <number> |
<length> | <percentage> |
inherit
'list-style-image'
NONE
'list-style-position'
NONE
'list-style-type'
'list-style'
[ 'list-style-type' ] |
inherit
'list-style-position' ||
'list-style-image'
<margin-width> | inherit
| auto
'max-height'
NONE
'max-width'
<length> | <percentage> |
none | inherit - supported for
inline, block-level, and replaced
elements (i.e. images, tables, table
cells).
'min-height'
'min-width'
<length> | <percentage> |
inherit - supported for inline,
Rendered Values
Ignored Values
[ <color> | invert |
inherit
'outline-style'
[ <border-style> | inherit
'outline-width'
[ <border-width> | inherit
'outline'
[ <outline-width> ||
<outline-style> ||
<outline-color> ] |
inherit
'overflow'
NONE
'padding-top'
'padding-right'
'padding-bottom'
'padding-left'
<padding-width> | inherit
'padding'
<padding-width> | inherit
'position'
'quotes'
NONE
'right'
'table-layout'
auto
fixed | inherit
'text-align'
justify
'text-decoration'
none | [ underline ||
overline || line-through
] | inherit
blink
'text-decoration-style'
'text-indent'
<length> | <percentage> |
inherit
'text-transform'
none | capitalize |
uppercase | lowercase |
inherit
'top'
'unicode-bidi'
bidi-override| normal|
embed| inherit
'vertical-align'
Rendered Values
Ignored Values
'visibility'
'white-space'
'width'
<length> | <percentage> |
auto | inherit - supported for
inline, block-level, and replaced
elements (i.e. images, tables, table
cells).
'word-spacing'
NONE
'z-index'
NONE
Transparent Colors
CSS3 supports RGBA colors. The RGBA declaration allows you to set opacity (via the Alpha channel) as part of the
color value. A value of 0 corresponds to a completely transparent color, while a value of 1 corresponds to a completely
opaque color. To specify a value, you can use either a real number between 0 and 1, or a percent.
RGBA color
personnel:before {
display:block;
padding: 1em;
font-size: 1.8em;
content: "Employees";
font-weight: bold;
color:#EEEEEE;
background-color: rgba(50, 50, 50, 0.6);
}
The attr() Function: Properties Values Collected from the Edited Document.
In CSS Level 2.1 you may collect attribute values and use them as content only for the pseudo-elements. For instance
the :before pseudo-element can be used to insert some content before an element. This is valid in CSS 2.1:
title:before{
content: "Title id=(" attr(id) ")";
}
In Oxygen XML Editor, the use of attr() function is available not only for the content property, but also for any
other property. This is similar to the CSS Level 3 working draft:
http://www.w3.org/TR/2006/WD-css3-values-20060919/#functional. The arguments of the function are:
attr ( attribute_name , attribute_type , default_value )
attribute_name
The attribute name. This argument is required.
The para elements have bg_color attributes with RGB color values like #AAAAFF. You can use
the attr() function to change the elements appearance in the editor based on the value of this
attribute:
background-color:attr(bg_color, color);
The attribute font_size represents the font size in em units. You can use this value to change the
style of the element:
font-size:attr(font_size, em);
screen - The styles marked with this media type are used only for rendering a document on screen.
print - The styles marked with this media type are used only for printing a document.
all - The styles marked with this media type are used for rendering a document in all supported types of media.
oxygen - The styles marked with this media type are used only for rendering a document in the Oxygen XML
Editor Author mode. For more information, see The oxygen Media Type on page 710 section.
oxygen-dark-theme - The styles marked with this media type are used only for rendering a document in the
Oxygen XML Editor Author mode when a dark theme is used (for example, Graphite).
oxygen-high-contrast-black - The styles marked with this media type are used only for rendering a
document in the Oxygen XML Editor Author mode on a Windows High Contrast Theme with a black background.
oxygen-high-contrast-white - The styles marked with this media type are used only for rendering a
document in the Oxygen XML Editor Author mode on a Windows High Contrast Theme with a white background.
@media oxygen{
b{
text-decoration:underline;
}
}
@media oxygen-high-contrast-white{
b{
font-weight:bold;
}
}
Supported Properties
Oxygen XML Editor also supports a few properties to set specific style rules that depend upon the size of the visible
area in Author mode. These supported properties are as follows:
min-width - The styles selected in this property are applied if the visible area in Author mode is equal to or greater
than the specified value.
max-width - The styles selected in this property are applied if the visible area in Author mode is less than or equal
to the specified value.
@media (min-width:500px){
p{
content:'XXX';
}
}
@media (max-width:700px){
p:after{
content:'yyy';
}
}
To match the processing instructions, you can use the oxy|processing-instruction selector:
oxy|processing-instruction {
display:block !important;
color:purple !important;
background-color:transparent !important;
}
A processing instruction usually has a target and one or more pseudo attributes:
<?target_name data="b"?>
You can match a processing instruction with a particular target from the CSS using the construct:
oxy|processing-instruction[target_name]
You can also match the processing instructions having a certain target and pseudo attribute value like:
oxy|processing-instruction[target_name][data="b"]
The XML comments display in Author mode can be changed using the oxy|comment selector:
oxy|comment {
display:block !important;
color:green !important;
To match particular entities, use the oxy|entity selector in expressions such as:
oxy|entity[name='amp'],
oxy|entity[name='lt'],
oxy|entity[name='gt'],
oxy|entity[name='quot'],
oxy|entity[name='apos'],
oxy|entity[name^='#']{
-oxy-display-tags: none;
}
The references to entities, XInclude, and DITA conrefs and conkeyrefs are expanded by default in Author mode and
the referenced content is displayed. The referenced resources are displayed inside the element or entity that refers
to them.
You can use the reference property to customize the way these references are rendered in Author mode:
oxy|reference {
border:1px solid gray !important;
}
In the Author mode, content is highlighted when text contains comments and changes (if Track Changes was active
when the content was modified).
If this content is referenced, the Author mode does not display the highlighted areas in the new context. If you want
to mark the existence of this comments and changes you can use the oxy|reference[comments],
oxy|reference[changeTracking], and oxy|reference[changeTracking][comments] selectors.
Note: Two artificial attributes (comments and changeTracking) are set on the reference node, containing
information about the number of comments and track changes in the content.
The following example represents the customization of the reference fragments that contain comments:
oxy|reference[comments]:before {
content: "Comments: " attr(comments) !important;
}
To match reference fragments based on the fact that they contain change tracking inside, use the
oxy|reference[changeTracking] selector.
oxy|reference[changeTracking]:before {
content: "Change tracking: " attr(changeTracking) !important;
}
Here is an example of how you can set a custom color to the reference containing both track changes and comments:
oxy|reference[changeTracking][comments]:before {
content: "Change tracking: " attr(changeTracking) " and comments: " attr(comments) !important;
}
none - Tags markers must not be presented regardless of the current display mode..
default - The tag markers will be created depending on the current display mode..
To configure the default background and foreground colors of the tags, go to Editor > Edit modes > Author. The
-oxy-tags-background-color and -oxy-tags-color properties allow you to control the background and
foreground colors for any particular XML element.
para {
-oxy-tags-color:white;
-oxy-tags-background-color:green;
}
title {
-oxy-tags-color:yellow;
-oxy-tags-background-color:black;
}
and returns:
'http://www.oxygenxml.com/dir1/dir4/dir5/test.xml'
The following function receives the result of the evaluation of two other functions as parameters:
image[href]{
content:oxy_url(oxy_base-uri(), oxy_replace(attr(href), '.jpeg', 'Thumbnail.jpeg'));
}
You can use the above example when you have image references and you want to see thumbnail
images stored in the same folder.
The following function uses an editor variable as the first parameter to point to the Oxygen XML
Editor installation location:
image[href] {
content: oxy_url('${oxygenHome}', 'logo.png');
}
and you want to add a padding before it with that specific amount specified in the attribute value:
*[padding-left]{
padding-left:oxy_concat(attr(padding-left), "px");
}
dynamic - Evaluates the XPath each time there are changes in the document.
dynamic-once - Separately evaluates the XPath for each node that matches the CSS selector. It will not
re-evaluate the expression when changes are made to other nodes in the document. This will lead to improved
performance, but the displayed content may not be updated to reflect the actual document content.
static - If the same XPath is evaluated on several nodes, the result for the first evaluation will be used for
all other matches. Use this only if the XPath does not contain a relationship with the node on which the CSS
The latter will be the actual content in which the XPath expression is executed.
An Example of the oxy_xpath() Function
The following example counts the number of words from a paragraph (including tracked changes)
and displays the result in front of it:
para:before{
content:
concat("|Number of words:",
oxy_xpath(
"count(tokenize(normalize-space(string-join(text(), '')), ' '))",
processChangeMarkers,
true),
"| ");
}
Form Controls
Oxygen XML Editor provides a variety of built-in form controls that allow users to interact with documents with familiar
user interface objects.
Oxygen XML Editor provides the following built-in form controls:
Text Field - A graphical user interface box that allows you to enter a single line of text.
Combo Box - A graphical user interface object that can be a drop-down menu or a combination of a drop-down menu
and a single-line text field.
Check Box - A graphical user interface box that you can click to select or deselect a value.
Pop-up - A contextual menu that provides quick access to various actions.
Button - A graphical user interface object that performs a specific action.
Button Group - A graphical user interface group of buttons (such as radio buttons) that perform specific actions.
Text Area - A box that allows you to enter multiple lines of text.
URL Chooser - A dialog box that allows you to select the location of local or remote resources.
Date Picker - A form control object that allows you to select a date in a specified format.
HTML Content - A graphical user interface box that is used for rendering HTML content.
For customization purposes, Oxygen XML Editor also supports custom form controls in Java.
To watch our video demonstration in regards to form controls, go to http://oxygenxml.com/demo/Form_Controls.html.
The Text Field Form Control
The oxy_textfield built-in form control is used for entering a single line of text in a graphical user interface box.
A text field may include optional content completion capabilities, used to present and edit the value of an attribute or
an element.
The oxy_textfield form control supports the following properties:
edit - Lets you edit the value of an attribute, the text content of an element, or Processing Instructions (PI). This
property can have the following values:
columns - Controls the width of the form control. The unit size is the width of the w character.
width - Specifies the width of the content area using relative (em, ex), absolute (in, cm, mm, pt, pc, px), and
percentage (followed by the % character) length units. The width property takes precedence over the columns
property (if the two are used together).
fontInherit - This value specifies whether the form control inherits its font from its parent element. The values
of this property can be true or false (default value). To make the form control inherit its font from its parent
element, set the fontInherit property to true.
visible - Specifies whether or not the form control is visible. The possible values of this property are true
(default value) and false.
values - Specifies the values that populate the content completion list of proposals. If these values are not specified
in the CSS, they are collected from the associated XML Schema.
tooltips - Associates tooltips to each value in the values property. The value of this property is a list of tooltips
separated by commas. If you want the tooltip to display a comma, use the ${comma} variable.
tooltip - Specifies a tooltip to be displayed when you hover over the form control.
color - Specifies the foreground color of the form control. If the value of the color property is inherit, the
form control has the same color as the element in which it is inserted.
hoverPseudoclassName - Allows you to change the way an element is rendered when you hover over a form
control. The value is the name of a CSS pseudo-class. When you hover over the form control, the specified pseudo-class
will be set on the element that contains the form control.
p:before {
content: oxy_textfield(hoverPseudoclassName, 'showBorder')
}
p:showBorder {
border: 1px solid red;
}
Note: You can use the Content Completion Assistant in the CSS or LESS editor to easily insert a sample of
the form control by selecting the corresponding code template. The form control code templates are displayed
with a symbol in the content complete list.
Tip: To insert a sample of the oxy_textfield form control, invoke the Content Completion Assistant by
pressing Ctrl Space (Command Space on OS X) and select the oxy_textfield code template.
The Combo Box Form Control
The oxy_combobox built-in form control is used for providing a graphical user interface object that is a drop-down
menu of proposed values. This form control can also be used for a combination of a drop-down menu and an editable
single-line text field.
The oxy_combobox form control supports the following properties:
@attribute_name - The name of the attribute whose value is being edited. If the attribute is in a namespace, the
value of the property must be a QName and the CSS must have a namespace declaration for the prefix.
#text - Specifies that the presented/edited value is the simple text value of an element.
Note: You can set the value of the visibility property to -oxy-collapse-text to render the
text only in the form control that the oxy_editor function specifies.
columns - Controls the width of the form control. The unit size is the width of the w character.
width - Specifies the width of the content area using relative (em, ex), absolute (in, cm, mm, pt, pc, px), and
percentage (followed by the % character) length units. The width property takes precedence over the columns
property (if the two are used together).
visible - Specifies whether or not the form control is visible. The possible values of this property are true
(default value) and false.
editable - This property accepts the true and false values. In addition to a drop-down menu, the true value also
generates an editable text field box that allows you to insert other values than the proposed ones. The false value
generates a drop-down menu that only accepts the proposed values.
tooltips - Associates tooltips to each value in the values property. The value of this property is a list of tooltips
separated by commas. If you want the tooltip to display a comma, use the ${comma} variable.
values - Specifies the values that populate the content completion list of proposals. If these values are not specified
in the CSS, they are collected from the associated XML Schema..
fontInherit - This value specifies whether the form control inherits its font from its parent element. The values
of this property can be true or false (default value). To make the form control inherit its font from its parent
element, set the fontInherit property to true.
labels - This property must have the same number of items as the values property. Each item provides a literal
description of the items listed in the values property.
Note: This property is only available for read-only combo boxes (the editable property is set to false).
color - Specifies the foreground color of the form control. If the value of the color property is inherit, the
form control has the same color as the element in which it is inserted.
hoverPseudoclassName - Allows you to change the way an element is rendered when you hover over a form
control. The value is the name of a CSS pseudo-class. When you hover over the form control, the specified pseudo-class
will be set on the element that contains the form control.
p:before {
content: oxy_combobox(hoverPseudoclassName, 'showBorder')
}
p:showBorder {
border: 1px solid red;
}
Note: You can use the Content Completion Assistant in the CSS or LESS editor to easily insert a sample of
the form control by selecting the corresponding code template. The form control code templates are displayed
with a symbol in the content complete list.
edit - Lets you edit the value of an attribute, the text content of an element, or Processing Instructions (PI). This
property can have the following values:
@attribute_name - The name of the attribute whose value is being edited. If the attribute is in a namespace, the
value of the property must be a QName and the CSS must have a namespace declaration for the prefix.
#text - Specifies that the presented/edited value is the simple text value of an element.
Note: You can set the value of the visibility property to -oxy-collapse-text to render the
text only in the form control that the oxy_editor function specifies.
resultSeparator - If multiple check-boxes are used, the separator is used to compose the final result. If not
specified, the space character is used.
tooltips - Associates tooltips to each value in the values property. The value of this property is a list of tooltips
separated by commas. If you want the tooltip to display a comma, use the ${comma} variable.
visible - Specifies whether or not the form control is visible. The possible values of this property are true
(default value) and false.
values - Specifies the values that are committed when the check-boxes are selected. If these values are not specified
in the CSS, they are collected from the associated XML Schema.
Note: Typically, when you use a comma in the values of a form control, the content that follows a comma
is considered a new value. If you want to include a comma in the values, precede the comma with two
backslashes. For example, oxy_combobox(values, '1\\, 2\\, 3, 4, edit, false) will
display a combo box having the first value 1, 2, 3 and the second value 4.
fontInherit - This value specifies whether the form control inherits its font from its parent element. The values
of this property can be true or false (default value). To make the form control inherit its font from its parent
element, set the fontInherit property to true..
uncheckedValues - Specifies the values that are committed when check-boxes are not selected.
labels - This property must have the same number of items as the values property. Each item provides a literal
description of the items listed in the values property.. If this property is not specified, the values property is
used as the label.
columns - Controls the width of the form control. The unit size is the width of the w character.
color - Specifies the foreground color of the form control. If the value of the color property is inherit, the
form control has the same color as the element in which it is inserted.
hoverPseudoclassName - Allows you to change the way an element is rendered when you hover over a form
control. The value is the name of a CSS pseudo-class. When you hover over the form control, the specified pseudo-class
will be set on the element that contains the form control.
p:before {
content: oxy_checkbox(hoverPseudoclassName, 'showBorder')
}
p:showBorder {
border: 1px solid red;
}
Note: You can use the Content Completion Assistant in the CSS or LESS editor to easily insert a sample of
the form control by selecting the corresponding code template. The form control code templates are displayed
with a symbol in the content complete list.
Tip: To insert a sample of the oxy_checkbox form control, invoke the Content Completion Assistant by
pressing Ctrl Space (Command Space on OS X) and select the oxy_checkbox code template.
The Pop-up Form Control
The oxy_popup built-in form control is used to offer a contextual menu that provides quick access to various actions.
A pop-up form control can display single or multiple selections.
The oxy_popup form control supports the following properties:
edit - Lets you edit the value of an attribute, the text content of an element, or Processing Instructions (PI). This
property can have the following values:
@attribute_name - The name of the attribute whose value is being edited. If the attribute is in a namespace, the
value of the property must be a QName and the CSS must have a namespace declaration for the prefix.
#text - Specifies that the presented/edited value is the simple text value of an element.
Note: You can set the value of the visibility property to -oxy-collapse-text to render the
text only in the form control that the oxy_editor function specifies.
rows - This property specifies the number of rows that the form control presents.
Note: If the value of the rows property is not specified, the default value of 12 is used.
color - Specifies the foreground color of the form control. If the value of the color property is inherit, the
form control has the same color as the element in which it is inserted.
Note: This property is used for rendering in the Author mode.
visible - Specifies whether or not the form control is visible. The possible values of this property are true
(default value) and false.
tooltips - Associates tooltips to each value in the values property. The value of this property is a list of tooltips
separated by commas. If you want the tooltip to display a comma, use the ${comma} variable.
resultSeparator - If multiple check-boxes are used, the separator is used to compose the final result. If not
specified, the space character is used.
Note: The value of the resultSeparator property cannot exceed one character.
selectionMode - Specifies whether the form control allows the selection of a single value or multiple values.
The predefined values of this property are single (default value) and multiple.
labels - Specifies the label associated with each entry used for presentation. If this property is not specified, the
values property is used instead.
columns - Controls the width of the form control. The unit size is the width of the w character. This property is
used for the visual representation of the form control.
width - Specifies the width of the content area using relative (em, ex), absolute (in, cm, mm, pt, pc, px), and
percentage (followed by the % character) length units. The width property takes precedence over the columns
property (if the two are used together).
rendererSort - Allows you to sort the values rendered on the form control label. The possible values of this
property are ascending and descending.
editorSort - Allows you to sort the values rendered on the form control. The possible values of this property are
ascending and descending.
rendererSeparator - Defines a separator used when multiple values are rendered. If not specified, the value
of the resultSeparator property is used.
fontInherit - This value specifies whether the form control inherits its font from its parent element. The values
of this property can be true or false (default value). To make the form control inherit its font from its parent
element, set the fontInherit property to true.
hoverPseudoclassName - Allows you to change the way an element is rendered when you hover over a form
control. The value is the name of a CSS pseudo-class. When you hover over the form control, the specified pseudo-class
will be set on the element that contains the form control.
p:before {
content: oxy_popup(hoverPseudoclassName, 'showBorder')
}
p:showBorder {
border: 1px solid red;
}
specified
Note: You can use the Content Completion Assistant in the CSS or LESS editor to easily insert a sample of
the form control by selecting the corresponding code template. The form control code templates are displayed
with a symbol in the content complete list.
actionContext - Specifies the context in which the action associated with the form control is executed. Its
possible values are element (default value) and caret. If you select the element value, the context is the
element that holds the form control. If you select the caret value, the action is invoked at the cursor location. If
the cursor is not inside the element that holds the form control, the element value is selected automatically.
fontInherit - This value specifies whether the form control inherits its font from its parent element. The values
of this property can be true or false (default value). To make the form control inherit its font from its parent
element, set the fontInherit property to true.
color - Specifies the foreground color of the form control. If the value of the color property is inherit, the
form control has the same color as the element in which it is inserted.
actionID - The ID of the action, specified in the associated document type framework, that is invoked when you
click the button.
Note: The element that contains the form control represents the context where the action is invoked.
action - Defines an action directly, rather than using the actionID parameter to reference an action from the
associated document type framework. This property is defined using the oxy_action function.
oxy_button(action, oxy_action(
name, 'Insert',
description, 'Insert an element after the current one',
icon, url('insert.png'),
operation, 'ro.sync.ecss.extensions.commons.operations.InsertFragmentOperation',
arg-fragment, '<element>${caret}</element>',
arg-insertLocation, '.',
arg-insertPosition, 'After'
)
Tip: A code template is available to make it easy to add the oxy_action function.
visible - Specifies whether or not the form control is visible. The possible values of this property are true
(default value) and false.
transparent - Flattens the aspect of the button form control, removing its border and background. The values
of this property can be true or false (default value).
showText - Specifies if the action text should be displayed on the button form control. If this property is missing
then the button displays the icon only if it is available, or the text if the icon is not available. The values of this
property can be true or false.
element {
content: oxy_button(actionID, 'remove.attribute', showText, true);
}
showIcon - Specifies if the action icon should be displayed on the button form control. If this property is missing
then the button displays the icon only if it is available, or the text if the icon is not available. The values of this
property can be true or false.
element {
content: oxy_button(actionID, 'remove.attribute', showIcon, true);
}
enableInReadOnlyContext - To enable button form controls or groups of buttons form controls this property
needs to be set to true. This property can be used to specify areas as read-only (by setting the -oxy-editable
property to false). This is useful when you want to use an action that does not modify the context.
Note: You can use the Content Completion Assistant in the CSS or LESS editor to easily insert a sample of
the form control by selecting the corresponding code template. The form control code templates are displayed
with a symbol in the content complete list.
Tip: To insert a sample of the oxy_button form control, invoke the Content Completion Assistant by
pressing Ctrl Space (Command Space on OS X) and select the oxy_button code template. Also, an
oxy_button_in_place_action code template is available that inserts an oxy_button function that
includes an action parameter.
The Button Group Form Control
The oxy_buttonGroup built-in form control is used for a graphical user interface group of buttons that invokes one
of several custom Author mode actions (defined in the associated Document Type) referencing it by its ID, or directly
in the CSS.
The oxy_buttonGroup form control supports the following properties:
actionIDs - The IDs of the actions that will be presented in the group of buttons.
actionID - The ID of the action, specified in the associated document type framework, that is invoked when you
click the button.
Note: The element that contains the form control represents the context where the action is invoked.
action_list - Defines a list of actions directly, rather than using the actionID parameter to reference actions
from the associated document type framework. This property is defined using the oxy_action_list function.
oxy_buttonGroup(
label, 'A group of actions',
icon, url('http://www.oxygenxml.com/img/icn_oxy20.png'),
actions,
oxy_action_list(
oxy_action(
name, 'Insert',
description, 'Insert an element after the current one',
operation, 'ro.sync.ecss.extensions.commons.operations.InsertFragmentOperation',
arg-fragment, '<element></element>',
arg-insertLocation, '.',
arg-insertPosition, 'After'
),
oxy_action(
name, 'Delete',
description, 'Deletes the current element',
operation, 'ro.sync.ecss.extensions.commons.operations.DeleteElementOperation'
)
)
)
Tip: A code template is available to make it easy to add the oxy_action_list function.
Note: You can use the Content Completion Assistant in the CSS or LESS editor to easily insert a sample of
the form control by selecting the corresponding code template. The form control code templates are displayed
with a symbol in the content complete list.
Tip: To insert a sample of the oxy_buttonGroup form control, invoke the Content Completion Assistant
by pressing Ctrl Space (Command Space on OS X) and select the oxy_buttonGroup code template.
Also, an oxy_buttonGroup_in_place_action code template is available that inserts an
oxy_buttonGroup function that includes an oxy_action_list function.
The Text Area Form Control
The oxy_textArea built-in form control is used for entering multiple lines of text in a graphical user interface box.
A text area may include optional syntax highlight capabilities to present the form control.
The oxy_textArea form control supports the following properties:
edit - Lets you edit the value of an attribute, the text content of an element, or Processing Instructions (PI). This
property can have the following values:
#content - This parameter is useful when an element has mixed or element-only content and you want to edit its
content inside a text area form control.
For example, if you have the following XML content:
<codeblock outputclass="language-xml">START_TEXT<ph>phase</ph><apiname><text>API</text></apiname></codeblock>
then the text area form control will edit the following fragment:
START_TEXT<ph>phase</ph><apiname><text>API</text></apiname>
Note: When the value of the edit property is #content, the text area form control will also offer
content completion proposals.
#content - This parameter is useful when an element has mixed or element-only content and you want to edit its
content inside a text area form control.
For example, if you have the following XML content:
<codeblock outputclass="language-xml">START_TEXT<ph>phase</ph><apiname><text>API</text></apiname></codeblock>
then the text area form control will edit the following fragment:
START_TEXT<ph>phase</ph><apiname><text>API</text></apiname>
Note: When the value of the edit property is #content, the text area form control will also offer content
completion proposals.
columns - Controls the width of the form control. The unit size is the width of the w character.
width - Specifies the width of the content area using relative (em, ex), absolute (in, cm, mm, pt, pc, px), and
percentage (followed by the % character) length units. The width property takes precedence over the columns
property (if the two are used together).
fontInherit - This value specifies whether the form control inherits its font from its parent element. The values
of this property can be true or false (default value). To make the form control inherit its font from its parent
element, set the fontInherit property to true.
visible - Specifies whether or not the form control is visible. The possible values of this property are true
(default value) and false.
pre - The whitespaces and new lines of the value are preserved and edited. If the rows and columns properties
are not specifies, the form control calculates its size on its own so that all the text is visible.
pre-wrap - The long lines are wrapped to avoid horizontal scrolling.
Note: The rows and columns properties must be specified. If these are not specified, the form control
considers the value to be pre.
hoverPseudoclassName - Allows you to change the way an element is rendered when you hover over a form
control. The value is the name of a CSS pseudo-class. When you hover over the form control, the specified pseudo-class
will be set on the element that contains the form control.
p:before {
content: oxy_textArea(hoverPseudoclassName, 'showBorder')
}
p:showBorder {
border: 1px solid red;
}
The following example presents a text area with CSS syntax highlighting that calculates its own
dimension, and a second one with XML syntax highlighting with defined dimension.
textArea {
visibility: -oxy-collapse-text;
white-space: pre;
}
textArea[language="CSS"]:before {
content: oxy_textArea(
edit, '#text',
contentType, 'text/css');
}
textArea[language="XML"]:before {
content: oxy_textArea(
edit, '#text',
contentType, 'text/xml',
rows, 10,
columns, 30);
}
Note: You can use the Content Completion Assistant in the CSS or LESS editor to easily insert a sample of
the form control by selecting the corresponding code template. The form control code templates are displayed
with a symbol in the content complete list.
Tip: To insert a sample of the oxy_textArea form control, invoke the Content Completion Assistant by
pressing Ctrl Space (Command Space on OS X) and select the oxy_textArea code template.
edit - Lets you edit the value of an attribute, the text content of an element, or Processing Instructions (PI). This
property can have the following values:
@attribute_name - The name of the attribute whose value is being edited. If the attribute is in a namespace, the
value of the property must be a QName and the CSS must have a namespace declaration for the prefix.
#text - Specifies that the presented/edited value is the simple text value of an element.
Note: You can set the value of the visibility property to -oxy-collapse-text to render the
text only in the form control that the oxy_editor function specifies.
columns - Controls the width of the form control. The unit size is the width of the w character.
width - Specifies the width of the content area using relative (em, ex), absolute (in, cm, mm, pt, pc, px), and
percentage (followed by the % character) length units. The width property takes precedence over the columns
property (if the two are used together).
color - Specifies the foreground color of the form control. If the value of the color property is inherit, the
form control has the same color as the element in which it is inserted.
visible - Specifies whether or not the form control is visible. The possible values of this property are true
(default value) and false.
fontInherit - This value specifies whether the form control inherits its font from its parent element. The values
of this property can be true or false (default value). To make the form control inherit its font from its parent
element, set the fontInherit property to true.
fileFilter - string value that holds comma-separated file extensions. The URL chooser uses these extensions
to filter the displayed files. A value such as "jpg,png,gif" is mapped to a single filter that will display all jpg,
png, and gif files.
hoverPseudoclassName - Allows you to change the way an element is rendered when you hover over a form
control. The value is the name of a CSS pseudo-class. When you hover over the form control, the specified pseudo-class
will be set on the element that contains the form control.
p:before {
content: oxy_urlChooser(hoverPseudoclassName, 'showBorder')
}
p:showBorder {
border: 1px solid red;
}
Note: You can use the Content Completion Assistant in the CSS or LESS editor to easily insert a sample of
the form control by selecting the corresponding code template. The form control code templates are displayed
with a symbol in the content complete list.
Tip: To insert a sample of the oxy_urlChooser form control, invoke the Content Completion Assistant
by pressing Ctrl Space (Command Space on OS X) and select the oxy_urlChooser code template.
edit - Lets you edit the value of an attribute, the text content of an element, or Processing Instructions (PI). This
property can have the following values:
@attribute_name - The name of the attribute whose value is being edited. If the attribute is in a namespace, the
value of the property must be a QName and the CSS must have a namespace declaration for the prefix.
#text - Specifies that the presented/edited value is the simple text value of an element.
Note: You can set the value of the visibility property to -oxy-collapse-text to render the
text only in the form control that the oxy_editor function specifies.
columns - Controls the width of the form control. The unit size is the width of the w character.
width - Specifies the width of the content area using relative (em, ex), absolute (in, cm, mm, pt, pc, px), and
percentage (followed by the % character) length units. The width property takes precedence over the columns
property (if the two are used together).
color - Specifies the foreground color of the form control. If the value of the color property is inherit, the
form control has the same color as the element in which it is inserted.
format - This property specifies the format of the inserted date. The pattern value must be a valid Java date (or
date-time) format. If missing, the type of the date is determined from the associated schema.
visible - Specifies whether or not the form control is visible. The possible values of this property are true
(default value) and false.
validateInput - Specifies if the form control is validated. If you introduce a date that does not respect the format,
the datePicker form control is rendered with a red foreground. By default, the input is validated. To disable the
validation, set this property to false.
hoverPseudoclassName - Allows you to change the way an element is rendered when you hover over a form
control. The value is the name of a CSS pseudo-class. When you hover over the form control, the specified pseudo-class
will be set on the element that contains the form control.
p:before {
content: oxy_datePicker(hoverPseudoclassName, 'showBorder')
}
p:showBorder {
border: 1px solid red;
}
Note: You can use the Content Completion Assistant in the CSS or LESS editor to easily insert a sample of
the form control by selecting the corresponding code template. The form control code templates are displayed
with a symbol in the content complete list.
Tip: To insert a sample of the oxy_datePicker form control, invoke the Content Completion Assistant
by pressing Ctrl Space (Command Space on OS X) and select the oxy_datePicker code template.
href - The absolute or relative location of a resource. The resource needs to be a well-formed HTML file.
id - The unique identifier of an item. This is a div element that has a unique id and is a child of the body element.
The div element is the container of the HTML content to be rendered by the form control.
content - An alternative to the href and id pair of elements. It provides the HTML content that will be displayed
in the form control.
width - Specifies the width of the content area using relative (em, ex), absolute (in, cm, mm, pt, pc, px), and
percentage (followed by the % character) length units. The width property takes precedence over the columns
property (if the two are used together).
hoverPseudoclassName - Allows you to change the way an element is rendered when you hover over a form
control. The value is the name of a CSS pseudo-class. When you hover over the form control, the specified pseudo-class
will be set on the element that contains the form control.
p:before {
content: oxy_htmlContent(hoverPseudoclassName, 'showBorder')
}
p:showBorder {
border: 1px solid red;
}
You can customize the style of the content using CSS that is either referenced by the file identified by the href property
or is defined in-line. If you change the HTML content or CSS and you want your changes to be reflected in the XML
that renders the form control, then you need to refresh the XML file. If the HTML does not have an associated style,
then a default text and background color will be applied.
In the following example, the form control collects the content from the p_description div element
found in the descriptions.html file. The box is 400 pixels wide and is displayed before a paragraph
identified by the intro_id attribute value.
p#intro_id:before {
content:
oxy_htmlContent(
href, "descriptions.html",
id, "p_description",
width, 400px);
}
Note: You can use the Content Completion Assistant in the CSS or LESS editor to easily insert a sample of
the form control by selecting the corresponding code template. The form control code templates are displayed
with a symbol in the content complete list.
Tip: To insert a sample of the oxy_htmlContent form control, invoke the Content Completion Assistant
by pressing Ctrl Space (Command Space on OS X) and select the oxy_htmlContent code template.
Implementing Custom Form Controls
If the built-in form controls are not sufficient for your needs, you can implement custom form controls in Java.
rendererClassName - The name of the class that draws the edited value. It must be an implementation of
ro.sync.ecss.extensions.api.editor.InplaceRenderer. The renderer has to be a SWING
implementation and can be used both in the standalone and Eclipse distributions.
swingEditorClassName - You can use this property for the standalone (Swing-based) distribution to specify the
name of the class used for editing. It is a Swing implementation of
ro.sync.ecss.extensions.api.editor.InplaceEditor.
swtEditorClassName - You can use this property for the Eclipse plug-in distribution to specify the name of the
class used for editing. It is a SWT implementation of the
ro.sync.ecss.extensions.api.editor.InplaceEditor.
Note: If the custom form control is intended to work in the Oxygen XML Editor standalone distribution,
the declaration of swtEditorClassName is not required. The renderer (the class that draws the value) and
the editor (the class that edits the value) have different properties because you can present a value in one
way and edit it in another.
classpath - You can use this property to specify the location of the classes used for a custom form control. The value
of the classpath property is an enumeration of URLs separated by comma.
edit - If your form control edits the value of an attribute or the text value of an element, you can use the
@attribute_name and #text predefined values and Oxygen XML Editor will perform the commit logic by itself.
You can use the custom value to perform the commit logic yourself.
The following is a sample Java code for implementing a custom combo box form control that inserts an XML element
in the content when the editing stops:
public class ComboBoxEditor extends AbstractInplaceEditor {
/**
* @see ro.sync.ecss.extensions.api.editor.InplaceEditor#stopEditing()
*/
@Override
public void stopEditing() {
Runnable customCommit = new Runnable() {
@Override
public void run() {
AuthorDocumentController documentController = context.getAuthorAccess().getDocumentController();
documentController.insertXMLFragment( "<custom/>", offset);
}
};
EditingEvent event = new EditingEvent(customCommit, true);
fireEditingStopped(event);
}
The custom form controls can use any of the predefined properties of the built-in form controls, as well as specified
custom properties.
This following is an example of how to specify a custom form control in the CSS:
myElement {
content: oxy_editor(
rendererClassName, "com.custom.editors.CustomRenderer",
swingEditorClassName, "com.custom.editors.SwingCustomEditor",
swtEditorClassName, "com.custom.editors.SwtCustomEditor",
edit, "@my_attr",
customProperty1, "customValue1",
customProperty2, "customValue2"
)
}
3.
4.
5.
6.
CSS
oxy|processing-instruction:before {
display:inline;
content:
"EDIT attribute: " oxy_textfield(edit, '@attr', columns, 15);
visibility:visible;
}
oxy|processing-instruction{
visibility:-oxy-collapse-text;
}
name - The name of the action. It will be displayed as the label for the button or menu item.
description (optional) - A short description with details about the result of the action.
icon (optional) - A path relative to the CSS pointing to an image (the icon for the action). The path can point to
resources that are packed in Oxygen XML Editor (oxygen.jar) by starting its value with / (for example,
/images/Remove16.png). It can also be expressed as editor variables.
operation - The name of the Java class implementing the
ro.sync.ecss.extensions.api.AuthorOperation interface. There is also a variety of predefined
operations that can be used.
Note: If the name of the operation specified in the CSS is not qualified (has no Java package name), then
it is considered to be one of the built-in Oxygen XML Editor operations from
ro.sync.ecss.extensions.commons.operations package. If the class is not found in this
package, then it will be loaded using the specified name.
arg-<string> - All arguments with the arg- prefix are passed to the operation (the string that follows the argprefix is passed).
Tip: A code template is available to make it easy to add the oxy_action function
with the Content Completion Assistant by pressing Ctrl Space (Command Space
on OS X) and select the oxy_action code template..
The oxy_action_list() Function
The oxy_action_list() function allows you to define a list of actions directly in the CSS, rather than referencing
them from the associated framework.
The oxy_action_list() function is used from the oxy_buttonGroup() function.
The arguments received by the oxy_action_list() function are a list of actions that are defined with the
oxy_action() function. The following properties are supported in the oxy_action_list() function:
name - The name of the action. It will be displayed as the label for the button or menu item.
description (optional) - A short description with details about the result of the action.
icon (optional) - A path relative to the CSS pointing to an image (the icon for the action). The path can point to
resources that are packed in Oxygen XML Editor (oxygen.jar) by starting its value with / (for example,
/images/Remove16.png). It can also be expressed as editor variables.
operation - The name of the Java class implementing the
ro.sync.ecss.extensions.api.AuthorOperation interface. There is also a variety of predefined
operations that can be used.
Note: If the name of the operation specified in the CSS is not qualified (has no Java package name), then
it is considered to be one of the built-in Oxygen XML Editor operations from
ro.sync.ecss.extensions.commons.operations package. If the class is not found in this
package, then it will be loaded using the specified name.
arg-<string> - All arguments with the arg- prefix are passed to the operation (the string that follows the argprefix is passed).
ID - (optional) - The ID of the action from the framework. If this is specified, all others parameters are disregarded.
oxy_action_list(
oxy_action(
name, 'Insert',
description, 'Insert an element after the current one',
operation, 'ro.sync.ecss.extensions.commons.operations.InsertFragmentOperation',
arg-fragment, '<element></element>',
arg-insertLocation, '.',
arg-insertPosition, 'After'
),
oxy_action(
name, 'Delete',
description, 'Deletes the current element',
operation, 'ro.sync.ecss.extensions.commons.operations.DeleteElementOperation'
)
)
text - This property specifies the built-in form control you are using.
width - Specifies the width of the content area using relative (em, ex), absolute (in, cm, mm, pt, pc, px), and
percentage (followed by the % character) length units. The width property takes precedence over the columns
property (if the two are used together).
color - Specifies the foreground color of the form control. If the value of the color property is inherit, the
form control has the same color as the element in which it is inserted.
background-color - Specifies the background color of the form control. If the value of the background-color
property is inherit, the form control has the same color as the element in which it is inserted.
styles - Specifies styles for the form control. The values of this property are a set of CSS properties:
element{
content: oxy_label(text, "Label Text", styles,
"font-size:2em;color:red;link:attr(href);");
}
Instead of using the values of the styles property individually, you can define them in a CSS file as in the following
example:
* {
width: 40%;
text-align:center;
}
Caution: Extensive use of the styles property may lead to performance issues.
If the text from an oxy_label() function contains new lines, for example oxy_label(text, 'LINE1\A
LINE2', width, 100px), the text is split in two. Each of the two new lines has the specified width of 100 pixels.
Note: The text is split after \A, which represents a new line character.
You can use the oxy_label() function together with a built-in form control function to create a form control based
layouts.
An example of a use case is if you have multiple attributes on a single element and you want use form
controls on separate lines and style them differently. Consider the following CSS rule:
person:before {
content: "Name:*" oxy_textfield(edit, '@name', columns, 20) "\A Address:" oxy_textfield(edit,
Suppose you only want the Name label to be set to bold, while you want both labels aligned to look
like a table (the first column with labels and the second with a text field). To achieve this, you can use
the oxy_label() to style each label differently.
person:before {
content: oxy_label(text, "Name:*", styles, "font-weight:bold;width:200px") oxy_textfield(edit,
'@name', columns, 20) "\A "
oxy_label(text, "Address:", styles, "width:200px") oxy_textfield(edit, '@address',
columns, 20)
}
Tip: A code template is available to make it easy to add the oxy_label function
with the Content Completion Assistant by pressing Ctrl Space (Command Space
on OS X) and select the oxy_label code template..
The oxy_link-text() Function
You can use the oxy_link-text() function on the CSS content property to obtain a text description from the
source of a reference.
By default, the oxy_link-text() function resolves DITA and DocBook references. For further details about how
you can also extend this functionality to other frameworks, go to Configuring an Extensions Bundle.
DITA Support
For DITA, the oxy_link-text() function resolves the xref element and the elements that have a keyref attribute.
The text description is the same as the one presented in the final output for those elements. If you use this function for
a topicref element that has the navtitle and locktitle attributes set, the function returns the value of the
navtitle attribute.
DocBook Support
For DocBook, the oxy_link-text() function resolves the xref element that defines a link in the same document.
The text description is the same as the one presented in the final output for those elements.
For the following XML and associated CSS fragments the oxy_link-text() function is resolved
to the value of the xreflabel attribute.
<para><code id="para.id" xreflabel="The reference label">my code</code></para>
<para><xref linkend="para.id"/></para>
xref {
content: oxy_link-text();
}
If the text from the target cannot extracted (for instance, if the href is not valid), you can use an
optional argument to display fallback text.
*[class~="map/topicref"]:before{
content: oxy_link-text("Cannot find the topic reference");
link:attr(href);
}
Details
oxy_subtract(param1, , paramN,
'returnType')
oxy_multiply(param1, , paramN,
'returnType')
oxy_divide(param1, param2,
'returnType')
oxy_modulo(param1, param2,
'returnType')
Note: The returnType can be 'integer', 'number', or any of the supported CSS measuring types.
If we have an image with width and height specified on it we can compute the number of pixels on
it:
image:before{
content: "Number of pixels: " oxy_multiply(attr(width), attr(height), "px");
}
By setting the pseudo-class access-control-user, the element section will become visible by
matching the second CSS selector.
You could create an AuthorCaretListener that sets the caret-visited pseudo-class to the element
at the cursor location. The effect will be that all the elements traversed by the cursor become red.
The API that you can use from the CaretListener:
ro.sync.ecss.extensions.api.AuthorDocumentController#setPseudoClass(java.lang.String,
ro.sync.ecss.extensions.api.node.AuthorElement)
ro.sync.ecss.extensions.api.AuthorDocumentController#removePseudoClass(java.lang.String,
ro.sync.ecss.extensions.api.node.AuthorElement)
Pre-defined Author mode operations can be used directly in your framework to work with custom pseudo-classes:
1. TogglePseudoClassOperation
2. SetPseudoClassOperation
3. RemovePseudoClassOperation
Built in CSS Stylesheet
When Oxygen XML Editor renders content in the Author mode, it adds built-in CSS selectors (in addition to the CSS
stylesheets linked in the XML or specified in the document type associated to the XML document). These built-in CSS
selectors are processed before all other CSS content, but they can be overwritten if the CSS developer wants to modify
a default behavior.
List of CSS Selector Contributed by Oxygen XML Editor
@namespace
@namespace
@namespace
@namespace
@namespace
oxy "http://www.oxygenxml.com/extensions/author";
xi "http://www.w3.org/2001/XInclude";
xlink "http://www.w3.org/1999/xlink";
svg "http://www.w3.org/2000/svg";
mml "http://www.w3.org/1998/Math/MathML";
oxy|document {
display:block !important;
}
oxy|cdata {
display:-oxy-morph !important;
white-space:pre-wrap !important;
border-width:0px !important;
margin:0px !important;
padding: 0px !important;
}
oxy|processing-instruction {
display:-oxy-morph !important;
color: rgb(139, 38, 201) !important;
white-space:pre-wrap !important;
border-width:0px !important;
margin:0px !important;
padding: 0px !important;
}
oxy|processing-instruction[Pub],
oxy|processing-instruction[PubTbl],
oxy|processing-instruction[xm-replace_text],
oxy|processing-instruction[xm-deletion_mark],
oxy|processing-instruction[xm-insertion_mark_start],
oxy|processing-instruction[xm-insertion_mark_end],
!important;
To show all entities in the Author mode as transparent, without a gray background, first define in
your CSS after all imports the namespace:
@namespace oxy "http://www.oxygenxml.com/extensions/author";
File frameworksFolder The file path to the frameworks directory. It can point to a custom frameworks
directory where the custom framework resides.
File pluginsFolder The file path to the plugins directory. It can point to a custom plugins directory where
the custom plugins resides.
String licenseKey The license key used to license the test class.
6. Create test methods which use the API in the base class to open XML files and perform different actions on them.
Your test class could look something like:
public class MyTestClass extends PluginWorkspaceTCBase {
/**
* Constructor.
*/
public MyTestClass() throws Exception {
super(new File("frameworks"), new File("plugins"),
"------START-LICENSE-KEY------\n" +
"\n" +
"Registration_Name=Developer\n" +
"\n" +
"Company=\n" +
"\n" +
"Category=Enterprise\n" +
"\n" +
"Component=XML-Editor, XSLT-Debugger, Saxon-SA\n" +
"\n" +
"Version=14\n" +
"\n" +
"Number_of_Licenses=1\n" +
"\n" +
"Date=09-04-2012\n" +
"\n" +
"Trial=31\n" +
"\n" +
"SGN=MCwCFGNoEGJSeiC3XCYIyalvjzHhGhhqAhRNRDpEu8RIWb8icCJO7HqfVP4++A\\=\\=\n" +
"\n" +
"-------END-LICENSE-KEY-------");
}
/**
* <p><b>Description:</b> TC for opening a file and using the bold operation</p>
* <p><b>Bug ID:</b> EXM-20417</p>
*
* @author radu_coravu
*
* @throws Exception
*/
public void testOpenFileAndBoldEXM_20417() throws Exception {
WSEditor ed = open(new File("D:/projects/eXml/test/authorExtensions/dita/sampleSmall.xml").toURL());
//Move caret
moveCaretRelativeTo("Context", 1, false);
//Insert <b>
invokeAuthorExtensionActionForID("bold");
assertEquals("<?xml version=\"1.0\" encoding=\"utf-8\"?>\n" +
"<!DOCTYPE task PUBLIC \"-//OASIS//DTD DITA Task//EN\"
\"http://docs.oasis-open.org/dita/v1.1/OS/dtd/task.dtd\">\n" +
"<task id=\"taskId\">\n" +
"
<title>Task <b>title</b></title>\n" +
"
<prolog/>\n" +
"
<taskbody>\n" +
"
<context>\n" +
"
<p>Context for the current task</p>\n" +
"
</context>\n" +
"
<steps>\n" +
"
<step>\n" +
"
<cmd>Task step.</cmd>\n" +
"
</step>\n" +
"
</steps>\n" +
"
</taskbody>\n" +
"</task>\n" +
"", getCurrentEditorXMLContent());
}
}
You can find the online Javadoc for AuthorDocumentFilter API here:
http://www.oxygenxml.com/InstData/Editor/SDK/javadoc/ro/sync/ecss/extensions/api/AuthorDocumentFilter.html
An alternative to using a document filtering is the use of a
ro.sync.ecss.extensions.api.AuthorSchemaAwareEditingHandlerAdapter which has clear
callbacks indicating the source from where the API is called (Paste, Drag and Drop, Typing).
Highlight Content
Question
How can we add custom highlights to the document content in Author mode?
Answer
There are two types of highlights you can add:
1. Non-Persistent Highlights - Such highlights are removed when the document is closed and then re-opened.
You can use the following API method:
ro.sync.exml.workspace.api.editor.page.author.WSAuthorEditorPageBase.getHighlighter()
to obtain an AuthorHighlighter that allows you to add a highlight between certain offsets with a specified painter.
For example, you can use this support to implement your own spell checker with a custom highlight for the
unrecognized words.
2. Persistent Highlights - Such highlights are saved in the XML content as processing instructions.
You can use the following API method:
ro.sync.exml.workspace.api.editor.page.author.WSAuthorEditorPageBase.getPersistentHighlighter()
to obtain an AuthorPersistentHighlighter class that allows you to add a persistent highlight between certain offsets,
set new properties for a specific highlight, and render it with a specified painter.
For example, you can use this support to implement your own way of adding review comments.
2. Add a workbench listener and add the pop-up customizer when an editor is opened in the Author page:
Workbench.getInstance().getActiveWorkbenchWindow().getPartService().addPartListener(
new IPartListener() {
@Override
public void partOpened(IWorkbenchPart part) {
if(part instanceof ro.sync.exml.workspace.api.editor.WSEditor) {
WSEditorPage currentPage = ((WSEditor)part).getCurrentPage();
if(currentPage instanceof WSAuthorEditorPage) {
((WSAuthorEditorPage)currentPage).addPopUpMenuCustomizer(new OxygenAuthorPagePopupMenuCustomizer());
}
}
}
........
});
allows you to get the DOCTYPE of the current XML file opened in the Author mode.
There is also an API method available which would allow you to set the DOCTYPE back to the XML:
ro.sync.ecss.extensions.api.AuthorDocumentController.setDoctype(AuthorDocumentType)
Basically you could take the entire content from the existing DOCTYPE,
ro.sync.ecss.extensions.api.AuthorDocumentType.getContent()
modify it to your needs, and create another AuthorDocumentType object with the new content and with the same
public, system IDs.
For example you could use this API is you want to add unparsed entities in the XML DOCTYPE.
When the extension is deactivated you should remove the CaretListener in order to avoid adding multiple listeners
that perform the same functionality.
Signing the JNLP file is required by newer Java versions and means that it is impossible to automatically generate a
JNLP file containing some dynamic arguments. The solution is to use the signed JNLP template feature of Java 7, bundle
inside the JAR library a signed APPLICATION_TEMPLATE.JNLP instead of an APPLICATION.JNLP with a
wildcard command line argument:
<application-desc main-class="ro.sync.jws.JwsDeployer">
<argument>*</argument>
</application-desc>
Then you can replace the wildcard in the external placed JNLP to the actual, dynamic command line arguments value.
A different approach (more complicated though) would be to have the JNLP file signed and always referenced as a URL
argument a location like this:
http://path/to/server/redirectEditedURL.php
When the URL gets clicked on the client side you would also call a PHP script on the server side which would update
the redirect location for redirectEditedURL.php to point to the clicked XML resource. Then the opened Oxygen
XML Editor would try to connect to the redirect PHP and be redirected to open the XML.
2. Options - If the author name was not imposed from the API, it is determined from the Author option set from the
Review preferences page.
3. System properties - If the author name was not imposed from the API or from the application options then the
following system property is used:
System.getProperty("user.name")
So, to impose the Track Changes author, use one of the following approaches:
1. Use the API to impose the reviewer author name. Here is the online Javadoc of this method:
http://www.oxygenxml.com/InstData/Editor/SDK/javadoc/ro/sync/ecss/extensions/api/AuthorReviewController.html#setReviewerAuthorName(java.lang.String)
2. Customize the default options and set a specific value for the reviewer author name option.
3. Set the value of user.name system property when the applet is initialising and before any document is loaded.
If you open it, you will see that it imports the main CSS and then adds selectors of its own.
If you want to create the transformer from the plugins side, you can use this method instead:
ro.sync.exml.workspace.api.PluginWorkspace.getXMLUtilAccess().
oxy url('http://www.oxygenxml.com/extensions/author');
xi "http://www.w3.org/2001/XInclude";
xlink "http://www.w3.org/1999/xlink";
svg "http://www.w3.org/2000/svg";
mml "http://www.w3.org/1998/Math/MathML";
oxy|document {
display:block !important;
}
In the CSS used for rendering the XML in Author mode do the following:
Example:
@namespace oxy url('http://www.oxygenxml.com/extensions/author');
oxy|entity {
background-color: inherit !important;
margin:0px !important;
padding: 0px !important;
-oxy-display-tags:none;
}
You can overwrite styles in the predefined CSS in order to custom style comments, processing instructions and CData
sections. You can also customize the way in which xi:include elements are rendered.
Note: If you need to configure the plugin for , set the com.oxygenxml.app.descriptor to
ro.sync.exml.AuthorFrameDescriptor or ro.sync.exml.DeveloperFrameDescriptor,
respectively.
8. Add a break point in the source of one of your Java classes.
9. Debug the created configuration. When the code reaches your breakpoint, the debug perspective should take over.
In the Author Component, you can either bundle a fixed set of options, or use our Java API to set properties which
overwrite the default options:
//For not breaking the line
//Long line
AuthorComponentFactory.getInstance().setObjectProperty("editor.line.width", new Integer(100000));
//Do not break before inline elements
AuthorComponentFactory.getInstance().setObjectProperty("editor.format.indent.inline.elements", false);
//For forcing zero indent
//Force indent settings to be controlled by us
AuthorComponentFactory.getInstance().setObjectProperty("editor.detect.indent.on.open", false);
//Zero indent size
AuthorComponentFactory.getInstance().setObjectProperty("editor.indent.size.v9.2", 0);
How can I add a custom Outline view for editing XML documents in the Text mode?
Suppose that you have XML documents like:
<doc startnumber="15">
<sec counter="no">
<info/>
<title>Introduction</title>
</sec>
<sec>
<title>Section title</title>
<para>Content</para>
<sec>
<title>Section title</title>
<para>Content</para>
</sec>
</sec>
<sec>
<title>Section title</title>
<para>Content</para>
</sec>
</doc>
and you want to display the XML content in a simplified Outline view like:
doc
sec
sec
sec
sec
"15"
Introduction
15 Section title
15.1 Section title
16 Section title
The lazy evaluation approach can be used for the following form controls properties:
InplaceEditorArgumentKeys.PROPERTY_VALUES
InplaceEditorArgumentKeys.PROPERTY_LABELS
InplaceEditorArgumentKeys.PROPERTY_TOOLTIPS
The full source code for this example is available inside the oXygen SDK.
So you can create up a plugin that automatically opens one by one XML documents from a certain folder in the
application, makes modifications to them, saves the content by calling:
ro.sync.exml.workspace.api.editor.WSEditorBase.save()
Chapter
10
Transforming Documents
Topics:
Transformation Scenarios
Output Formats
Transformation Scenarios
A transformation scenario is a set of complex operations and settings that gives you the possibility to obtain outputs of
multiple types (XML, HTML, PDF, EPUB, etc.) from the same source of XML files and stylesheets.
Executing a transformation scenario implies multiple actions, such as:
Before transforming an XML document in Oxygen XML Editor, you need to define a transformation scenario to apply
to that document. A scenario is a set of values for various parameters that define a transformation. It is not related to a
particular document, but rather to a document type. Types of transformation scenarios include:
Scenarios that Apply to XML Files - This type of scenario contains the location of an XSLT stylesheet that is
applied on the edited XML document, as well as other transformation parameters.
Scenarios that Apply to XSLT Files - This type of scenario contains the location of an XML document, on which
the edited XSLT stylesheet is applied, as well as other transform parameters.
Scenarios that Apply to XQuery Files - This type of scenario contains the location of an XML source, on which
the edited XQuery file is applied, as well as other transform parameters. When the XML source is a native XML
database, the XML source field of the scenario is empty because the XML data is read with XQuery-specific functions,
such as document(). When the XML source is a local XML file, the URL of the file is specified in the XML input
field of the scenario.
Scenarios that Apply to SQL Files - This type of scenario specifies a database connection for the database server
that runs the SQL file that is associated with the scenario. The data processed by the SQL script is located in the
database.
Scenarios that Apply to XProc Files - This type of scenario contains the location of an XProc script, as well as
other transform parameters.
DITA-OT Scenarios - This type of scenario provides the parameters for an Ant transformation that executes a
DITA-OT build script. Oxygen XML Editor comes with a built-in version of Ant and a built-in version of DITA-OT,
although you can also set other versions in the scenario.
ANT Scenarios - This type of scenario contains the location of an Ant build script, as well as other transform
parameters.
Note:
Status messages generated during the transformation process are displayed in the Information view.
XML Transformation with XSLT - Specifies the transformation parameters and location of an XSLT stylesheet that
is applied to the edited XML document. This scenario is useful when you develop an XML document and the XSLT
document is in its final form.
XML Transformation with XQuery - Specifies the transform parameters and location of an XQuery file that is
applied to the edited XML document.
DITA-OT Transformation - Specifies the parameters for an Ant transformation that executes a DITA-OT build
script. Oxygen XML Editor comes with a built-in version of Ant and a built-in version of DITA-OT but different
versions can be set in the scenario.
ANT Transformation - Allows you to configure the options and parameters of an Ant build script.
XSLT Transformation - Specifies the transformation parameters and location of an XML document to which the
edited XSLT stylesheet is applied. This scenario is useful when you develop an XSLT document and the XML
document is in its final form.
XProc Transformation - Specified the transformation parameters and location of an XProc script.
Use the
Configure Transformation Scenario(s) (Ctrl Shift C (Meta Shift C on OS X)) action from the
Transformation toolbar or the Document > Transformation menu. Then click the New button and select XML
transformation with XSLT.
Use the
Apply Transformation Scenario(s) (Ctrl Shift T (Meta Shift T on OS X)) action from the
Transformation toolbar or the Document > Transformation menu. Then click the New button and select XML
transformation with XSLT.
Note: If a scenario is already associated with the edited document, selecting
Apply Transformation
Scenario(s) runs the associated scenario automatically. You can check whether transformation scenarios are
associated with the edited document by hovering your cursor over the
button.
All three methods open the New Scenario dialog box. This dialog box allows you to configure the options that control
the transformation.
The upper part of the dialog box contains the Name field and Storage options:
Global Options - The scenario is saved in the global options that are stored in the user home directory and is not
accessible to other users.
Project Options - The scenario is stored in the project file and can be shared with other users. For example, if your
project is saved on a source versioning/sharing system (CVS, SVN, Source Safe, etc.) or a shared folder, your team
can use the scenarios that you store in the project file.
The lower part of the dialog box contains the following tabs:
XSLT.
FO Processors.
Output.
XML URL - Specifies the source XML file. This URL is resolved through the catalog resolver. If the catalog does
not have a mapping for the URL, then the file is used directly from its remote location.
Note: If the transformer engine is Saxon 9 and a custom URI resolver is configured in Preferences for
Saxon 9, the XML input of the transformation is passed to that URI resolver.
Note: If the transformer engine is one of the built-in XSLT 2.0 / 3.0 engines and the name of an initial
template is specified in the scenario, the XML URL field can be empty. The XML URL field can also be
empty if you use external XSLT processors. Otherwise, a value is mandatory in the XML URL field.
XSL URL - Specifies the source XSL file that the transformation will use. This URL is resolved through the catalog
resolver. If the catalog does not have a mapping for the URL, the file is used directly from its remote location.
Use "xml-stylesheet" declaration - Use the stylesheet declared with an xml-stylesheet declaration instead
of the stylesheet specified in the XSL URL field. By default, this checkbox is not selected and the transformation
applies the XSLT stylesheet that is specified in the XSL URL field. If it is checked, the scenario applies the stylesheet
specified explicitly in the XML document with the xml-stylesheet processing instruction.
Transformer - This drop-down menu presents all the transformation engines available to Oxygen XML Editor for
performing a transformation. These are the built-in engines and the external engines defined in the Custom Engines
preferences page. The engine you choose in this dialog box is used as the default transformation engine. Also, if an
XSLT or XQuery document does not have an associated validation scenario, this transformation engine is used in
the validation process (if it provides validation support).
Advanced options - Allows you to configure the advanced options of the Saxon HE / PE / EE engine for the
current transformation scenario. To configure the same options globally, go to the Saxon-HE/PE/EE preferences
page. For the current transformation scenario, these Advanced options override the options configured in the
Saxon-HE/PE/EE preferences page. The Initial mode and template option is only available in the Advanced
options. It is a Saxon-specific option that sets the name of the first XSLT template that starts the XSLT
transformation or the initial mode of the transformation.
Parameters - Opens the Configure parameters dialog box, allowing you to configure the XSLT parameters used
in the current transformation. In this dialog box, you can also configure the parameters of additional stylesheets by
using the Additional XSLT stylesheets button. If the XSLT transformation engine is custom-defined, you can not
use this dialog box to configure the parameters sent to the custom engine. Instead, you can copy all parameters from
the dialog box using contextual menu actions and edit the custom XSLT engine to include the necessary parameters
in the command line that starts the transformation process.
Extensions - Opens the dialog box for configuring the XSLT/XQuery extension jars or classes that define extension
Java functions or extension XSLT elements used in the transformation.
Additional XSLT stylesheets - Opens the dialog box for adding XSLT stylesheets that are applied on the main
stylesheet that is specified in the XSL URL field. This is useful when a chain of XSLT stylesheets must be applied
to the input XML document.
Note:
1. The doc function solves the argument relative to the XSL stylesheet location. You can use full paths or editor
variables (such as ${cfdu} [current file directory]) to specify other locations:
doc('${cfdu}/test.xml')//*
2. You cannot use XSLT Functions. Only XPath functions are allowed.
The following actions are available for managing the parameters:
New
Opens the Add Parameter dialog box that allows you to add a new parameter to the list. An editor variable can be
inserted in the text box using the
Insert Editor Variables button. If the Evaluate as XPath option is enabled,
the parameter will be evaluated as an XPath expression.
Edit
Opens the Edit Parameter dialog box that allows you to edit the selected parameter. An editor variable can be
inserted in the text box using the
Insert Editor Variables button. If the Evaluate as XPath option is enabled,
the parameter will be evaluated as an XPath expression.
Unset
Resets the selected parameter to its default value. Available only for edited parameters with set values.
Delete
Removes the selected parameter from the list. It is enabled only for new parameters that have been added to the list.
The bottom panel presents the following:
XSLT/XQuery Extensions
The Libraries dialog box is used to specify the jars and classes that contain extension functions called from the XSLT
or XQuery file of the current transformation scenario. You can use the Add, Edit, and Remove buttons to configure
the extensions.
An extension function called from the XSLT or XQuery file of the current transformation scenario will be searched, in
the specified extensions, in the order displayed in this dialog box. To change the order of the items, select the item to
be moved and press the
Move up or
Move down buttons.
The FO Processor Tab
The FO Processor tab contains the following options:
Perform FO Processing - Specifies whether an FO processor is applied (either the built-in Apache FOP engine or
an external engine defined in Preferences) during the transformation.
Prompt for file - At the end of the transformation, a file browser dialog box is displayed for specifying the path and
name of the file that stores the transformation result.
Save As - The path of the file where the result of the transformation is stored. The path can include special Oxygen
XML Editor editor variables or custom editor variables by using the
Insert Editor Variables button.
Open in Browser/System Application - If enabled, Oxygen XML Editor automatically opens the result of the
transformation in a system application associated with the file type of the result (for example, .pdf files are usually
opened in the Acrobat Reader application).
Note: To set the web browser that is used for displaying HTML/XHTML pages, open the Preferences
dialog box, then go to Global and set it in the Default Internet browser field.
Saved file - When Open in Browser/System Application is selected, this button can be used to specify
that Oxygen XML Editor automatically opens the file specified in the Save As text field at the end of
the transformation.
Other location - When Open in System Application is selected, this option can be used to specify that
Oxygen XML Editor opens the file specified here. The file path can include special Oxygen XML Editor
editor variables or custom editor variables by using the
Insert Editor Variables button.
Open in editor - When this is enabled, the transformation result specified in the Save As field is opened in a new
editor panel with the appropriate built-in editor type (for example, if the result is an XML file it is opened in the
built-in XML editor, or if it is an XSL-FO file it is opened with the built-in FO editor).
Show in results view as
XHTML - Can only be enabled if Open in Browser/System Application is disabled. If this is checked, Oxygen
XML Editor displays the transformation result in a built-in XHTML browser panel at the bottom of the application
window.
Important: When transforming very large documents, you should be aware that enabling this feature
results in a very long processing time, necessary for rendering the transformation result in the XHTML
result viewer panel. This drawback is due to the built-in Java XHTML browser implementation. To avoid
delays for large documents, if you want to see the XHTML result of the transformation, you should use
an external browser by checking the Open in browser option.
XML - If this is checked, Oxygen XML Editor displays the transformation result in an XML viewer panel at the
bottom of the application window with syntax highlighting, specific for XML documents.
SVG - If this is checked, Oxygen XML Editor displays the transformation result in an integrated SVG viewer in
the results panel at the bottom of the application window and renders the result as an SVG image.
Image URLs are relative to - If Show in results view as XHTML is checked, this text field specifies the path used
to resolve image paths contained in the transformation result.
Use the
Configure Transformation Scenario(s) (Ctrl Shift C (Meta Shift C on OS X)) action from the
Transformation toolbar or the Document > Transformation menu. Then click the New button and select XML
transformation with XQuery.
Use the
Apply Transformation Scenario(s) (Ctrl Shift T (Meta Shift T on OS X)) action from the
Transformation toolbar or the Document > Transformation menu. Then click the New button and select XML
transformation with XQuery.
Note: If a scenario is already associated with the edited document, selecting
Apply Transformation
Scenario(s) runs the associated scenario automatically. You can check whether transformation scenarios are
associated with the edited document by hovering your cursor over the
button.
All three methods open the New Scenario dialog box. This dialog box allows you to configure the options that control
the transformation.
The upper part of the dialog box contains the Name field and Storage options:
Global Options - The scenario is saved in the global options that are stored in the user home directory and is not
accessible to other users.
Project Options - The scenario is stored in the project file and can be shared with other users. For example, if your
project is saved on a source versioning/sharing system (CVS, SVN, Source Safe, etc.) or a shared folder, your team
can use the scenarios that you store in the project file.
The lower part of the dialog box contains the following tabs:
XQuery.
FO Processor.
Output.
XML URL - Specifies the source XML file. This URL is resolved through the catalog resolver. If the catalog does
not have a mapping for the URL, then the file is used directly from its remote location.
Note: If the transformer engine is Saxon 9 and a custom URI resolver is configured in Preferences for
Saxon 9, the XML input of the transformation is passed to that URI resolver.
You can use the following browsing buttons to enter values in the XML URL and XQuery URL fields:
Insert Editor Variables
Opens a pop-up menu allowing you to introduce special Oxygen XML Editor editor variables or custom editor
variables in the XML URL field.
Browse for local file
Opens a local file browser dialog box allowing you to select a local file.
Browse for remote file
Opens an URL browser dialog box allowing you to select a remote file.
Browse for archived file
Opens a zip archive browser dialog box allowing you to select a file from a zip archive.
Browse Data Source Explorer
Opens the Data Source Explorer window.
Search for file
Allows you to find a file in the current project.
Open in editor
Opens the file in an editor panel with the path that is specified in the XML URL text box.
The rest of the options available in the XQuery tab allow you to further customize the transformation scenario:
Transformer - This drop-down menu presents all the transformation engines available to Oxygen XML Editor for
performing a transformation. These are the built-in engines and the external engines defined in the Custom Engines
preferences page. The engine you choose in this dialog box is used as the default transformation engine. Also, if an
XSLT or XQuery document does not have an associated validation scenario, this transformation engine is used in
the validation process (if it provides validation support).;
Advanced options - configure advanced options specific for the Saxon HE / PE / EE engine.
Parameters - Opens the Configure parameters dialog box for configuring the XQuery parameters. You can use
buttons in this dialog box you can add, edit, or remove parameters. If the XQuery transformation engine is
custom-defined you can not use this dialog box to set parameters. Instead, you can copy all parameters from the
dialog box using contextual menu actions and edit the custom XQuery engine to include the necessary parameters
in the command line that starts the transformation process.
Note: Use the Filter text box to search for a specific term in the entire parameters collection.
Extensions - Opens the dialog box for configuring the XSLT/XQuery extension jars or classes that define extension
Java functions or extension XSLT elements used in the transformation.
XSLT/XQuery Extensions
The Libraries dialog box is used to specify the jars and classes that contain extension functions called from the XSLT
or XQuery file of the current transformation scenario. You can use the Add, Edit, and Remove buttons to configure
the extensions.
An extension function called from the XSLT or XQuery file of the current transformation scenario will be searched, in
the specified extensions, in the order displayed in this dialog box. To change the order of the items, select the item to
be moved and press the
Move up or
Move down buttons.
The FO Processor Tab
The FO Processor tab contains the following options:
Present as a sequence - Enabling this option will reduce the time necessary to fetch the full result, as it will only
fetch the first chunk of the result.
Prompt for file - At the end of the transformation, a file browser dialog box is displayed for specifying the path and
name of the file that stores the transformation result.
Save As - The path of the file where the result of the transformation is stored. The path can include special Oxygen
XML Editor editor variables or custom editor variables by using the
Insert Editor Variables button.
Open in Browser/System Application - If enabled, Oxygen XML Editor automatically opens the result of the
transformation in a system application associated with the file type of the result (for example, .pdf files are usually
opened in the Acrobat Reader application).
Note: To set the web browser that is used for displaying HTML/XHTML pages, open the Preferences
dialog box, then go to Global and set it in the Default Internet browser field.
Saved file - When Open in Browser/System Application is selected, this button can be used to specify
that Oxygen XML Editor automatically opens the file specified in the Save As text field at the end of
the transformation.
Other location - When Open in System Application is selected, this option can be used to specify that
Oxygen XML Editor opens the file specified here. The file path can include special Oxygen XML Editor
editor variables or custom editor variables by using the
Insert Editor Variables button.
Open in editor - When this is enabled, the transformation result specified in the Save As field is opened in a new
editor panel with the appropriate built-in editor type (for example, if the result is an XML file it is opened in the
built-in XML editor, or if it is an XSL-FO file it is opened with the built-in FO editor).
Show in results view as
XHTML - Can only be enabled if Open in Browser/System Application is disabled. If this is checked, Oxygen
XML Editor displays the transformation result in a built-in XHTML browser panel at the bottom of the application
window.
Important: When transforming very large documents, you should be aware that enabling this feature
results in a very long processing time, necessary for rendering the transformation result in the XHTML
result viewer panel. This drawback is due to the built-in Java XHTML browser implementation. To avoid
delays for large documents, if you want to see the XHTML result of the transformation, you should use
an external browser by checking the Open in browser option.
XML - If this is checked, Oxygen XML Editor displays the transformation result in an XML viewer panel at the
bottom of the application window with syntax highlighting, specific for XML documents.
SVG - If this is checked, Oxygen XML Editor displays the transformation result in an integrated SVG viewer in
the results panel at the bottom of the application window and renders the result as an SVG image.
Image URLs are relative to - If Show in results view as XHTML is checked, this text field specifies the path used
to resolve image paths contained in the transformation result.
DITA OT Transformation
To create a DITA OT Transformation scenario, use one of the following methods:
Use the
Configure Transformation Scenario(s) (Ctrl Shift C (Meta Shift C on OS X)) action from the
Transformation toolbar or the Document > Transformation menu. Then click the New button and select DITA
OT Transformation.
Use the
Apply Transformation Scenario(s) (Ctrl Shift T (Meta Shift T on OS X)) action from the
Transformation toolbar or the Document > Transformation menu. Then click the New button and select DITA
OT Transformation.
All three methods open the DITA Transformation Type dialog box that presents the list of possible outputs.
Global Options - The scenario is saved in the global options that are stored in the user home directory and is not
accessible to other users.
Project Options - The scenario is stored in the project file and can be shared with other users. For example, if your
project is saved on a source versioning/sharing system (CVS, SVN, Source Safe, etc.) or a shared folder, your team
can use the scenarios that you store in the project file.
The lower part of the dialog box contains the following tabs (only those that are appropriate for the chosen output type
will be displayed):
Skins (Available for WebHelp and WebHelp with Feedback output types).
FO Processor (Available for PDF output types).
Parameters
Filters
Advanced
Output
For information about creating an entirely new DITA OT transformation, see Creating a DITA OT Customization Plugin
on page 545 and Installing a Plugin in the DITA Open Toolkit on page 547.
The Skins Tab
A skin is a collection of CSS properties that can alter the look of the output by changing colors, font types, borders,
margins, and paddings. This allows you to rapidly adapt the look and feel of the output for your organization.
Oxygen XML Editor provides a set of predefined skins for the DITA Map WebHelp and DITA Map WebHelp with
Feedback transformation scenarios.
Environment variable set by Antenna House installation (the newest installation version will be used).
Antenna House was added as an external FO Processor in the preferences pages.
To further customize the PDF output obtained from the Antenna House processor:
Use DITAVAL file - If you already have a DITAVAL file associated with the DITA map, you can specify the file
to be used when filtering content. An editor variable can be inserted for the file path by using the
Insert Editor
Variables button. You can find out more about constructing a DITAVAL file in the DITA OT Documentation.
Use profiling condition set - Sets the profiling condition set that will apply to your transformation.
Exclude from output all elements with any of the following attributes - By using the
New,
Edit, or
Delete buttons at the bottom of the pane, you can configure a list of attributes (name and value) to exclude all
elements that contain any of these attributes from the output.
Custom build file - If you use a custom DITA-OT build file, you can specify the path to the customized build file.
If empty, the build.xml file from the dita.dir parameter that is configured in the Parameters tab is used. An
editor variable can be inserted for the file path by using the
Insert Editor Variables button.
Build target - Optionally, you can specify a build target for the build file. If no target is specified, the default init
target is used.
Additional arguments - You can specify additional command-line arguments to be passed to the Ant transformation
(such as -verbose).
Ant Home - You can choose between the default or custom Ant installation to run the transformation. The default
path can be configured in the Ant preferences page.
Java Home - You can choose between the default or custom Java installation to run the transformation. The default
path is the Java installation that is used by Oxygen XML Editor.
Note: It may be possible that the used Java version is incompatible with the DITA Open Toolkit engine.
For example, DITA OT 1.8.5 and older requires Java 1.6 or later, while DITA OT 2.0 and newer requires
Java 1.7 or newer. Thus, if you encounter related errors running the publishing, consider installing a Java
VM that is supported by the DITA OT publishing engine and using it in the Java Home text field.
JVM Arguments - This parameter allows you to set specific parameters for the Java Virtual Machine used by Ant.
For example, if it is set to -Xmx384m, the transformation process is allowed to use 384 megabytes of memory. When
performing a large transformation, you may want to increase the memory allocated to the Java Virtual Machine.
This will help avoid Out of Memory error messages (OutOfMemoryError).
Libraries - By default, Oxygen XML Editor adds (as high priority) libraries that are not transformation-dependent
and also patches for certain DITA Open Toolkit bugs. You can use this button to specify additional libraries (jar
files or additional class paths) to be used by the Ant transformer.
Base directory - All the relative paths that appear as values in parameters are considered relative to the base directory.
The default value is the directory where the transformed map is located. An editor variable can be inserted for the
path by using the
Insert Editor Variables button.
Temporary files directory - This directory is used to store pre-processed temporary files until the final output is
obtained. An editor variable can be inserted for the path by using the
Insert Editor Variables button.
Output folder - The folder where the content of the final output is stored. An editor variable can be inserted for the
path by using the
Insert Editor Variables button.
Note: If the DITA map or topic is opened from a remote location or a ZIP file, the parameters must specify
absolute paths.
Open in Browser/System Application - If enabled, Oxygen XML Editor automatically opens the result of the
transformation in a system application associated with the file type of the result (for example, .pdf files are usually
opened in the Acrobat Reader application).
Note: To set the web browser that is used for displaying HTML/XHTML pages, open the Preferences
dialog box, then go to Global and set it in the Default Internet browser field.
Saved file - When Open in Browser/System Application is selected, this button can be used to specify
that Oxygen XML Editor automatically opens the file specified in the Save As text field at the end of
the transformation.
Other location - When Open in System Application is selected, this option can be used to specify that
Oxygen XML Editor opens the file specified here. The file path can include special Oxygen XML Editor
editor variables or custom editor variables by using the
Insert Editor Variables button.
Severity - The first column displays the following icons that indicate the severity of the problem:
5. Use this information or other resources from the online DITA-OT community to solve the transformation problems
before re-executing the transformation scenario.
ANT Transformation
An Ant transformation scenario is usually associated with an Ant build script. Oxygen XML Editor runs an Ant
transformation scenario as an external process that executes the Ant build script with the built-in Ant distribution (Apache
Ant version 1.8.2) that comes with the application, or optionally with a custom Ant distribution configured in the scenario.
To create an Ant transformation scenario, use one of the following methods:
Use the
Configure Transformation Scenario(s) (Ctrl Shift C (Meta Shift C on OS X)) action from the
Transformation toolbar or the Document > Transformation menu. Then click the New button and select ANT
transformation.
Use the
Apply Transformation Scenario(s) (Ctrl Shift T (Meta Shift T on OS X)) action from the
Transformation toolbar or the Document > Transformation menu. Then click the New button and select ANT
transformation.
Global Options - The scenario is saved in the global options that are stored in the user home directory and is not
accessible to other users.
Project Options - The scenario is stored in the project file and can be shared with other users. For example, if your
project is saved on a source versioning/sharing system (CVS, SVN, Source Safe, etc.) or a shared folder, your team
can use the scenarios that you store in the project file.
The lower part of the dialog box contains the following tabs:
Working directory - The path of the current directory of the Ant external process. An editor variable can be inserted
for the file path by using the
Insert Editor Variables button.
Build file - The Ant script file that is the input of the Ant external process. An editor variable can be inserted for
the file path by using the
Insert Editor Variables button.
Build target - Optionally, you can specify a build target for the Ant script file. If no target is specified, the Ant target
that is specified as the default in the Ant script file is used.
Additional arguments - You can specify additional command-line arguments to be passed to the Ant transformation
(such as -verbose).
Ant Home - You can choose between the default or custom Ant installation to run the transformation. The default
path can be configured in the Ant preferences page.
Java Home - You can choose between the default or custom Java installation to run the transformation. The default
path is the Java installation that is used by Oxygen XML Editor.
JVM Arguments - This parameter allows you to set specific parameters for the Java Virtual Machine used by Ant.
For example, if it is set to -Xmx384m, the transformation process is allowed to use 384 megabytes of memory. When
performing a large transformation, you may want to increase the memory allocated to the Java Virtual Machine.
This will help avoid Out of Memory error messages (OutOfMemoryError).
Libraries - By default, Oxygen XML Editor adds (as high priority) libraries that are not transformation-dependent
and also patches for certain DITA Open Toolkit bugs. You can use this button to specify additional libraries (jar
files or additional class paths) to be used by the Ant transformer.
Open - Allows you to specify the file to open automatically when the transformation is finished. Usually, this is the
output file of the Ant process. An editor variable can be inserted for the path by using the
Insert Editor Variables
button.
In System Application - The file specified in the Open text box is opened in the system application that is set
in the operating system as the default application for that type of file (for example, .pdf files are usually opened
in the Acrobat Reader application).
In Editor - The file specified in the Open text box is opened in a new editor panel with the appropriate built-in
editor type (for example, if the result is an XML file it is opened in the built-in XML editor).
The Show console output option allows you to specify when to display the console output log. The following options
are available:
When build fails - displays the console output log if the build fails.
Always - displays the console output log, regardless of whether or not the build fails.
XSLT Transformation
To create an XSLT transformation scenario, use one of the following methods:
Use the
Configure Transformation Scenario(s) (Ctrl Shift C (Meta Shift C on OS X)) action from the
Transformation toolbar or the Document > Transformation menu. Then click the New button and select XSLT
transformation.
Use the
Apply Transformation Scenario(s) (Ctrl Shift T (Meta Shift T on OS X)) action from the
Transformation toolbar or the Document > Transformation menu. Then click the New button and select XSLT
transformation.
All three methods open the New Scenario dialog box. This dialog box allows you to configure the options that control
the transformation.
The upper part of the dialog box contains the Name field and Storage options:
Global Options - The scenario is saved in the global options that are stored in the user home directory and is not
accessible to other users.
The lower part of the dialog box contains the following tabs:
XSLT
FO Processors
Output
XML URL - Specifies the source XML file. This URL is resolved through the catalog resolver. If the catalog does
not have a mapping for the URL, then the file is used directly from its remote location.
Note: If the transformer engine is Saxon 9 and a custom URI resolver is configured in Preferences for
Saxon 9, the XML input of the transformation is passed to that URI resolver.
Note: If the transformer engine is one of the built-in XSLT 2.0 / 3.0 engines and the name of an initial
template is specified in the scenario, the XML URL field can be empty. The XML URL field can also be
empty if you use external XSLT processors. Otherwise, a value is mandatory in the XML URL field.
XSL URL - Specifies the source XSL file that the transformation will use. This URL is resolved through the catalog
resolver. If the catalog does not have a mapping for the URL, the file is used directly from its remote location.
You can use the following browsing buttons to enter values in the XML URL and XSL URL fields:
Insert Editor Variables
Opens a pop-up menu allowing you to introduce special Oxygen XML Editor editor variables or custom editor
variables in the XML URL field.
Browse for local file
Opens a local file browser dialog box allowing you to select a local file.
Browse for remote file
Opens an URL browser dialog box allowing you to select a remote file.
Browse for archived file
Opens a zip archive browser dialog box allowing you to select a file from a zip archive.
Browse Data Source Explorer
Opens the Data Source Explorer window.
Search for file
Allows you to find a file in the current project.
Open in editor
Opens the file in an editor panel with the path that is specified in the XML URL text box.
The rest of the options available in the XSLT tab allow you to further customize the transformation scenario:
Use "xml-stylesheet" declaration - Use the stylesheet declared with an xml-stylesheet declaration instead
of the stylesheet specified in the XSL URL field. By default, this checkbox is not selected and the transformation
applies the XSLT stylesheet that is specified in the XSL URL field. If it is checked, the scenario applies the stylesheet
specified explicitly in the XML document with the xml-stylesheet processing instruction.
Transformer - This drop-down menu presents all the transformation engines available to Oxygen XML Editor for
performing a transformation. These are the built-in engines and the external engines defined in the Custom Engines
preferences page. The engine you choose in this dialog box is used as the default transformation engine. Also, if an
XSLT or XQuery document does not have an associated validation scenario, this transformation engine is used in
the validation process (if it provides validation support).
Parameters - Opens the Configure parameters dialog box, allowing you to configure the XSLT parameters used
in the current transformation. In this dialog box, you can also configure the parameters of additional stylesheets by
using the Additional XSLT stylesheets button. If the XSLT transformation engine is custom-defined, you can not
use this dialog box to configure the parameters sent to the custom engine. Instead, you can copy all parameters from
the dialog box using contextual menu actions and edit the custom XSLT engine to include the necessary parameters
in the command line that starts the transformation process.
Extensions - Opens the dialog box for configuring the XSLT/XQuery extension jars or classes that define extension
Java functions or extension XSLT elements used in the transformation.
Additional XSLT stylesheets - Opens the dialog box for adding XSLT stylesheets that are applied on the main
stylesheet that is specified in the XSL URL field. This is useful when a chain of XSLT stylesheets must be applied
to the input XML document.
Perform FO Processing - Specifies whether an FO processor is applied (either the built-in Apache FOP engine or
an external engine defined in Preferences) during the transformation.
XSLT result as input - The FO processor is applied to the result of the XSLT transformation that is defined in the
XSLT tab.
XML URL as input - The FO processor is applied to the input XML file.
Method - The output format of the FO processing. Available options depend on the selected processor type.
Processor - Specifies the FO processor. It can be the built-in Apache FOP processor or an external processor.
Prompt for file - At the end of the transformation, a file browser dialog box is displayed for specifying the path and
name of the file that stores the transformation result.
Save As - The path of the file where the result of the transformation is stored. The path can include special Oxygen
XML Editor editor variables or custom editor variables by using the
Insert Editor Variables button.
Open in Browser/System Application - If enabled, Oxygen XML Editor automatically opens the result of the
transformation in a system application associated with the file type of the result (for example, .pdf files are usually
opened in the Acrobat Reader application).
Note: To set the web browser that is used for displaying HTML/XHTML pages, open the Preferences
dialog box, then go to Global and set it in the Default Internet browser field.
Saved file - When Open in Browser/System Application is selected, this button can be used to specify
that Oxygen XML Editor automatically opens the file specified in the Save As text field at the end of
the transformation.
Other location - When Open in System Application is selected, this option can be used to specify that
Oxygen XML Editor opens the file specified here. The file path can include special Oxygen XML Editor
editor variables or custom editor variables by using the
Insert Editor Variables button.
Open in editor - When this is enabled, the transformation result specified in the Save As field is opened in a new
editor panel with the appropriate built-in editor type (for example, if the result is an XML file it is opened in the
built-in XML editor, or if it is an XSL-FO file it is opened with the built-in FO editor).
Show in results view as
XML - If this is checked, Oxygen XML Editor displays the transformation result in an XML viewer panel at the
bottom of the application window with syntax highlighting, specific for XML documents.
SVG - If this is checked, Oxygen XML Editor displays the transformation result in an integrated SVG viewer in
the results panel at the bottom of the application window and renders the result as an SVG image.
Image URLs are relative to - If Show in results view as XHTML is checked, this text field specifies the path used
to resolve image paths contained in the transformation result.
XProc Transformation
A sequence of transformations described by an XProc script can be executed with an XProc transformation scenario.
To create an XProc transformation scenario, use one of the following methods:
Use the
Configure Transformation Scenario(s) (Ctrl Shift C (Meta Shift C on OS X)) action from the
Transformation toolbar or the Document > Transformation menu. Then click the New button and select XProc
transformation.
Use the
Apply Transformation Scenario(s) (Ctrl Shift T (Meta Shift T on OS X)) action from the
Transformation toolbar or the Document > Transformation menu. Then click the New button and select XProc
transformation.
All three methods open the New Scenario dialog box. This dialog box allows you to configure the options that control
the transformation.
The upper part of the dialog box contains the Name field and Storage options:
Global Options - The scenario is saved in the global options that are stored in the user home directory and is not
accessible to other users.
Project Options - The scenario is stored in the project file and can be shared with other users. For example, if your
project is saved on a source versioning/sharing system (CVS, SVN, Source Safe, etc.) or a shared folder, your team
can use the scenarios that you store in the project file.
The lower part of the dialog box contains the following tabs:
XProc
Inputs
Parameters
Outputs
Options
XProc URL - Specifies the source XSL file that the transformation will use. This URL is resolved through the
catalog resolver. If the catalog does not have a mapping for the URL, the file is used directly from its remote location.
You can use the following browsing buttons to enter value in the XProc URL:
Insert Editor Variables
Opens a pop-up menu allowing you to introduce special Oxygen XML Editor editor variables or custom editor
variables in the XML URL field.
Browse for local file
Opens a local file browser dialog box allowing you to select a local file.
Browse for remote file
Opens an URL browser dialog box allowing you to select a remote file.
Browse for archived file
Opens a zip archive browser dialog box allowing you to select a file from a zip archive.
Browse Data Source Explorer
Opens the Data Source Explorer window.
Search for file
Allows you to find a file in the current project.
Processor - Allows you to select the XProc engine. You can select the built-in Calabash engine or a custom engine
that is configured in the Preferences dialog box.
List of Ports - In this section you can use the New and Delete buttons to add or remove ports.
List of Parameters - This section presents a list of parameters for each port and includes columns for the parameter
name, namespace URI, and its value. Use the Filter text box to search for a specific term in the entire parameters
collection. You can use the New and Delete buttons to add or remove parameters. You can edit the value of each
cell in this table by double-clicking the cell. You can also sort the parameters by clicking the column headers.
Editor Variable Information - The built-in editor variables and custom editor variables can be used for specifying
the URI. The message pane at the bottom of the dialog box provides more information about the editor variables
that can be used.
List of Options - This section presents a list of options and includes columns for the option name, namespace URI,
and its value. Use the Filter text box to search for a specific term in the entire options collection. You can use the
New and Delete buttons to add or remove options. You can edit the value of each cell in this table by double-clicking
the cell. You can also sort the parameters by clicking the column headers. The names of edited options are displayed
in bold.
Editor Variable Information - The built-in editor variables and custom editor variables can be used for specifying
the URI. This section provides more information about the editor variables that can be used.
Use the
Configure Transformation Scenario(s) (Ctrl Shift C (Meta Shift C on OS X)) action from the
Transformation toolbar or the Document > Transformation menu. Then click the New button and select XQuery
transformation.
Use the
Apply Transformation Scenario(s) (Ctrl Shift T (Meta Shift T on OS X)) action from the
Transformation toolbar or the Document > Transformation menu. Then click the New button and select XQuery
transformation.
Global Options - The scenario is saved in the global options that are stored in the user home directory and is not
accessible to other users.
Project Options - The scenario is stored in the project file and can be shared with other users. For example, if your
project is saved on a source versioning/sharing system (CVS, SVN, Source Safe, etc.) or a shared folder, your team
can use the scenarios that you store in the project file.
The lower part of the dialog box contains the following tabs:
XQuery
FO Processor
Output
XML URL - Specifies the source XML file. This URL is resolved through the catalog resolver. If the catalog does
not have a mapping for the URL, then the file is used directly from its remote location.
Note: If the transformer engine is Saxon 9 and a custom URI resolver is configured in Preferences for
Saxon 9, the XML input of the transformation is passed to that URI resolver.
XQuery URL - specifies the source XQuery file that the transformation will use. This URL is resolved through the
catalog resolver. If the catalog does not have a mapping for the URL, the file is used directly from its remote location.
You can use the following browsing buttons to enter values in the XML URL and XQuery URL fields:
Insert Editor Variables
Opens a pop-up menu allowing you to introduce special Oxygen XML Editor editor variables or custom editor
variables in the XML URL field.
Browse for local file
Opens a local file browser dialog box allowing you to select a local file.
Browse for remote file
Opens an URL browser dialog box allowing you to select a remote file.
Browse for archived file
Opens a zip archive browser dialog box allowing you to select a file from a zip archive.
Browse Data Source Explorer
Opens the Data Source Explorer window.
Search for file
Allows you to find a file in the current project.
Open in editor
Opens the file in an editor panel with the path that is specified in the XML URL text box.
The rest of the options available in the XQuery tab allow you to further customize the transformation scenario:
Transformer - This drop-down menu presents all the transformation engines available to Oxygen XML Editor for
performing a transformation. These are the built-in engines and the external engines defined in the Custom Engines
preferences page. The engine you choose in this dialog box is used as the default transformation engine. Also, if an
XSLT or XQuery document does not have an associated validation scenario, this transformation engine is used in
the validation process (if it provides validation support).;
Advanced options - configure advanced options specific for the Saxon HE / PE / EE engine.
Extensions - Opens the dialog box for configuring the XSLT/XQuery extension jars or classes that define extension
Java functions or extension XSLT elements used in the transformation.
Perform FO Processing - Specifies whether an FO processor is applied (either the built-in Apache FOP engine or
an external engine defined in Preferences) during the transformation.
XQuery result as input - the FO processor is applied to the result of the XQuery transformation defined in the
XQuery tab.
XML URL as input - The FO processor is applied to the input XML file.
Method - The output format of the FO processing. Available options depend on the selected processor type.
Processor - Specifies the FO processor. It can be the built-in Apache FOP processor or an external processor.
Present as a sequence - Enabling this option will reduce the time necessary to fetch the full result, as it will only
fetch the first chunk of the result.
Prompt for file - At the end of the transformation, a file browser dialog box is displayed for specifying the path and
name of the file that stores the transformation result.
Save As - The path of the file where the result of the transformation is stored. The path can include special Oxygen
XML Editor editor variables or custom editor variables by using the
Insert Editor Variables button.
Open in Browser/System Application - If enabled, Oxygen XML Editor automatically opens the result of the
transformation in a system application associated with the file type of the result (for example, .pdf files are usually
opened in the Acrobat Reader application).
Note: To set the web browser that is used for displaying HTML/XHTML pages, open the Preferences
dialog box, then go to Global and set it in the Default Internet browser field.
Saved file - When Open in Browser/System Application is selected, this button can be used to specify
that Oxygen XML Editor automatically opens the file specified in the Save As text field at the end of
the transformation.
Other location - When Open in System Application is selected, this option can be used to specify that
Oxygen XML Editor opens the file specified here. The file path can include special Oxygen XML Editor
editor variables or custom editor variables by using the
Insert Editor Variables button.
Open in editor - When this is enabled, the transformation result specified in the Save As field is opened in a new
editor panel with the appropriate built-in editor type (for example, if the result is an XML file it is opened in the
built-in XML editor, or if it is an XSL-FO file it is opened with the built-in FO editor).
Show in results view as
XHTML - Can only be enabled if Open in Browser/System Application is disabled. If this is checked, Oxygen
XML Editor displays the transformation result in a built-in XHTML browser panel at the bottom of the application
window.
Important: When transforming very large documents, you should be aware that enabling this feature
results in a very long processing time, necessary for rendering the transformation result in the XHTML
result viewer panel. This drawback is due to the built-in Java XHTML browser implementation. To avoid
XML - If this is checked, Oxygen XML Editor displays the transformation result in an XML viewer panel at the
bottom of the application window with syntax highlighting, specific for XML documents.
SVG - If this is checked, Oxygen XML Editor displays the transformation result in an integrated SVG viewer in
the results panel at the bottom of the application window and renders the result as an SVG image.
Image URLs are relative to - If Show in results view as XHTML is checked, this text field specifies the path used
to resolve image paths contained in the transformation result.
SQL Transformation
To create an SQL transformation scenario, use one of the following methods:
Use the
Configure Transformation Scenario(s) (Ctrl Shift C (Meta Shift C on OS X)) action from the
Transformation toolbar or the Document > Transformation menu. Then click the New button and select SQL
transformation.
Use the
Apply Transformation Scenario(s) (Ctrl Shift T (Meta Shift T on OS X)) action from the
Transformation toolbar or the Document > Transformation menu. Then click the New button and select SQL
transformation.
All three methods open the New Scenario dialog box. This dialog box allows you to configure the following options
that control the transformation:
Global Options - The scenario is saved in the global options that are stored in the user home directory and
is not accessible to other users.
Project Options - The scenario is stored in the project file and can be shared with other users. For example,
if your project is saved on a source versioning/sharing system (CVS, SVN, Source Safe, etc.) or a shared
folder, your team can use the scenarios that you store in the project file.
SQL URL - Allows you to specify the URL of the SQL script. You can use the following browsing buttons to
enter value in this field:
Insert Editor Variables
Opens a pop-up menu allowing you to introduce special Oxygen XML Editor editor variables or custom editor
variables in the XML URL field.
Browse for local file
Opens a local file browser dialog box allowing you to select a local file.
Browse for remote file
Opens an URL browser dialog box allowing you to select a remote file.
Browse for archived file
Opens a zip archive browser dialog box allowing you to select a file from a zip archive.
Connection - Allows you to select a connection from a drop-down list. To configure a connection, use the
Advanced options button to open the data source preferences page.
Parameters - Allows you to configure the parameters of the transformation.
Settings
Show all scenarios - Select this option to display all the available scenarios, regardless of the document they are
associated with.
Show only the scenarios available for the editor - Select this option to only display the scenarios that Oxygen
XML Editor can apply for the current document type.
Show associated scenarios - Select this option to only display the scenarios associated with the document you are
editing.
Import scenarios - This option opens the Import scenarios dialog box that allows you to select the scenarios
file that contains the scenarios you want to import. If one of the scenarios you import is identical to an existing
Export selected scenarios - Use this option to export transformation and validation scenarios individually.
Oxygen XML Editor creates a scenarios file that contains the scenarios that you export.
The middle section of the dialog box displays the scenarios that you can apply to the current document. You can view
both the scenarios associated with the current document type and the scenarios defined at project level. The following
columns are used to display the transformation scenarios:
Association - The check-boxes in this column mark whether a transformation scenario is associated with the current
document.
Scenario - This column presents the names of the transformation scenarios.
Type - Displays the type of the transformation scenario. For further details about the different types of transformation
scenarios available in Oxygen XML Editor see the Defining a New Transformation Scenario section.
Storage - Displays where a transformation scenario is stored (the Show Storage option must be enabled.)
To sort each column you can left-click its header. The contextual menu of each header allows you to do the following:
Show Type - Use this option to display the transformation type of each scenario.
Show Storage - Use this option to display the storage location of the scenarios.
Group by Association - Select this option to group the scenarios depending on whether or not they are associated
with the current document.
Group by Type - Select this option to group the scenarios by their type.
Group by Storage - Select this option to group the scenarios by their storage location.
Ungroup all - Select this option to ungroup all the scenarios.
Reset Layout - Select this option to restore the default settings of the layout.
The bottom section of the dialog box contains the following actions:
Association follows selection - Enable this check-box to automatically associate selected transformation scenarios
with the current document. This option can also be used for multiple selections.
Note: When this option is enabled, the Association column is hidden.
New - This button allows you to create a new transformation scenario, depending upon its type.
Edit - This button opens the Edit Scenario dialog box that allows you to configure the options of the transformations
scenario.
Note: If you try to edit a transformation scenario associated with a defined document type, Oxygen XML
Editor displays a warning message to inform you that this is not possible and gives you the option to create
a duplicate transformation scenario to edit instead.
Edit button.
Use the
Configure Transformation Scenario(s) (Ctrl Shift C (Meta Shift C on OS X)) action from the
Transformation toolbar or the Document > Transformation menu. Then select the scenario and click the Edit
button.
Use the
Apply Transformation Scenario(s) (Ctrl Shift T (Meta Shift T on OS X)) action from the
Transformation toolbar or the Document > Transformation menu. Then select the scenario and click the Edit
button.
Note: If a scenario is already associated with the edited document, selecting
Apply Transformation
Scenario(s) runs the associated scenario automatically. You can check whether transformation scenarios are
associated with the edited document by hovering your cursor over the
button.
You can edit transformation scenarios that are defined at project level only. To edit a transformation scenario that is
associated with a defined document type, duplicate it and edit the duplicated scenario.
Selecting Global Options stores the scenario in the global options that are stored in the user home directory.
Selecting Project Options stores the scenario in the project file and can be shared with other users that have access to
the project. If your project is saved on a source versioning system (CVS, SVN, Source Safe, etc.) then your team will
have access to the scenarios that you define. When you create a scenario at the project level, the URLs from the scenario
become relative to the project URL.
You can also change the storage options on existing transformation scenarios by using the Change storage action from
the contextual menu of the list of scenarios.
Show all scenarios - Select this option to display all the available scenarios, regardless of the document they are
associated with.
Show only the scenarios available for the editor - Select this option to only display the scenarios that Oxygen
XML Editor can apply for the current document type.
Show associated scenarios - Select this option to only display the scenarios associated with the document you are
editing.
Change storage - Use this option to change the storage location of the selected scenario to Global Options or
Project Options. You are also able to keep the original storage location and make a copy of the selected scenario
in the new storage location.
Import scenarios - This option opens the Import scenarios dialog box that allows you to select the scenarios
file that contains the scenarios you want to import. If one of the scenarios you import is identical to an existing
scenario, Oxygen XML Editor ignores it. If a conflict appears (an imported scenario has the same name as an existing
one), you can choose between two options:
Export selected scenarios - Use this option to export transformation and validation scenarios individually.
Oxygen XML Editor creates a scenarios file that contains the scenarios that you export.
Show Type - Use this option to display the transformation type of each scenario.
Show Storage - Use this option to display the storage location of the scenarios.
Group by Association - Select this option to group the scenarios depending on whether or not they are associated
with the current document.
Group by Type - Select this option to group the scenarios by their type.
Group by Storage - Select this option to group the scenarios by their storage location.
Ungroup all - Select this option to ungroup all the scenarios.
Reset Layout - Select this option to restore the default settings of the layout.
Oxygen XML Editor supports multiple scenarios association. To associate multiple scenarios with a document, enable
the check-boxes in front of each scenario. You can also associate multiple scenarios with a document from the Configure
Transformation Scenario(s) or Configure Validation Scenario(s) dialog boxes.
Group by Association - Select this option to group the scenarios depending on whether or not they are associated
with the current document.
Group by Type - Select this option to group the scenarios by their type.
Group by Storage - Select this option to group the scenarios by their storage location.
XSLT Processors
This section explains how to configure an XSLT processor and extensions for such a processor in Oxygen XML Editor.
Supported XSLT Processors
Oxygen XML Editor includes the following XSLT processors:
Xalan 2.7.1 - Xalan-Java is an XSLT processor for transforming XML documents into HTML, text, or other XML
document types. It implements XSL Transformations (XSLT) Version 1.0 and XML Path Language (XPath) Version
1.0.
Saxon 6.5.5 - Saxon 6.5.5 is an XSLT processor that implements the Version 1.0 XSLT and XPath with a number
of powerful extensions. This version of Saxon also includes many of the new features that were first defined in the
XSLT 1.1 working draft, but for conformance and portability reasons these are not available if the stylesheet header
specifies version="1.0".
Saxon 9.6.0.7 Home Edition (HE), Professional Edition (PE) - Saxon-HE/PE implements the basic conformance
level for XSLT 2.0 / 3.0 and XQuery 1.0. The term basic XSLT 2.0 / 3.0 processor is defined in the draft XSLT 2.0
/ 3.0 specifications. It is a conformance level that requires support for all features of the language other than those
that involve schema processing. The HE product remains open source, but removes some of the more advanced
features that are present in Saxon-PE.
Saxon 9.6.0.7 Enterprise Edition (EE) - Saxon EE is the schema-aware edition of Saxon and it is one of the built-in
processors included in Oxygen XML Editor. Saxon EE includes an XML Schema processor, and schema-aware
XSLT, XQuery, and XPath processors.
Saxon-CE (Client Edition) is Saxonica's implementation of XSLT 2.0 for use on web browsers. Oxygen XML
Editor provides support for editing stylesheets that contain Saxon-CE extension functions and instructions. This
support improves the validation, content completion, and syntax highlighting.
Note: Saxon-CE, being JavaScript-based, was designed to run inside a web browser. This means that you
will use Oxygen XML Editor only for developing the Saxon-CE stylesheet, leaving the execution part to a
web browser. See more details about executing such a stylesheet on Saxonica's website.
Note: A specific template, named Saxon-CE stylesheet, is available in the New Document wizard.
Xsltproc (libxslt) - Libxslt is the XSLT C library developed for the Gnome project. Libxslt is based on libxml2,
the XML C library developed for the Gnome project. It also implements most of the EXSLT set of processor-portable
extensions, functions, and some of Saxon's evaluate and expression extensions. The libxml2 version included in
Oxygen XML Editor is 2.7.6 and the Libxslt version is 1.1.26.
Oxygen XML Editor uses Libxslt through its command line tool (Xsltproc). The XSLT processor is included
in the distribution kit of the stand-alone version for Windows and Mac OS X. Since there are differences between
various Linux distributions, on Linux you must install Libxslt on your machine as a separate application and set
the PATH variable to contain the Xsltproc executable.
Note: The Xsltproc processor can be configured from the XSLTPROC options page.
Caution: Known problem: file paths containing spaces are not handled correctly in the LIBXML processor.
For example, the built-in XML catalog files of the predefined document types (DocBook, TEI, DITA, etc)
are not handled properly by LIBXML if Oxygen XML Editor is installed in the default location on Windows
(C:\Program Files). This is because the built-in XML catalog files are stored in the
[OXYGEN_DIR]/frameworks subdirectory of the installation directory, which in this case contains at
least a space character.
MSXML 4.0 - MSXML 4.0 is available only on Windows platforms. It can be used for transformation and validation
of XSLT stylesheets.
Oxygen XML Editor uses the Microsoft XML parser through its command line tool msxsl.exe.
MSXML .NET - MSXML .NET is available only on Windows platforms. It can be used for transformation and
validation of XSLT stylesheets.
Oxygen XML Editor performs XSLT transformations and validations using .NET Framework's XSLT implementation
(System.Xml.Xsl.XslTransform class) through the nxslt command line utility. The nxslt version included
in Oxygen XML Editor is 1.6.
You should have the .NET Framework version 1.0 already installed on your system. Otherwise, you will get the
following warning: MSXML.NET requires .NET Framework version 1.0 to be installed.
Exit code: 128.
You can get the .NET Framework version 1.0 from the Microsoft website.
.NET 1.0 - A transformer based on the System.Xml 1.0 library available in the .NET 1.0 and .NET 1.1 frameworks
from Microsoft (http://msdn.microsoft.com/xml/). It is available only on Windows.
You should have the .NET Framework version 1.0 or 1.1 already installed on your system. Otherwise, you will get
the following warning: MSXML.NET requires .NET Framework version 1.0 to be installed.
Exit code: 128.
You can get the .NET Framework version 1.0 from the Microsoft website.
.NET 2.0 - A transformer based on the System.Xml 2.0 library available in the .NET 2.0 framework from Microsoft.
It is available only on Windows.
You should have the .NET Framework version 2.0 already installed on your system. Otherwise, you will get the
following warning: MSXML.NET requires .NET Framework version 2.0 to be installed.
Exit code: 128.
You can get the .NET Framework version 2.0 from the Microsoft website.
For information about configuring the XSLT preferences, see the XSLT options section.
Configuring Custom XSLT Processors
You can configure and run XSLT and XQuery transformations with processors other than the ones which come with the
Oxygen XML Editor distribution.
Note: You can not use these custom engines in the Debugger perspective.
The output messages of a custom processor are displayed in an output view at the bottom of the application window. If
an output message follows the format of an Oxygen XML Editor linked message, clicking it highlights the location of
the message in an editor panel containing the file referenced in the message.
Configuring the XSLT Processor Extensions Paths
The Xalan and Saxon processors support the use of extension elements and extension functions. Unlike a literal result
element, which the stylesheet simply transfers to the result tree, an extension element performs an action. The extension
is usually used because the XSLT stylesheet fails in providing adequate functions for accomplishing a more complex
task.
The DocBook extensions for Xalan and Saxon are included in the
[OXYGEN_DIR]\frameworks\docbook\xsl\extensions folder.
For more information about how to use extensions, see the following links:
Xalan - http://xml.apache.org/xalan-j/extensions.html
Saxon 6.5.5 - http://saxon.sourceforge.net/saxon6.5.5/extensions.html
Saxon 9.6.0.7 - http://www.saxonica.com/documentation9.5/index.html#!extensibility
XSL-FO Processors
This section explains how to apply XSL-FO processors when transforming XML documents to various output formats
in Oxygen XML Editor.
The Built-in XSL-FO Processor
The Oxygen XML Editor installation package is distributed with the Apache FOP that is a Formatting Objects processor
for rendering your XML documents to PDF. FOP is a print and output independent formatter driven by XSL Formatting
Objects. FOP is implemented as a Java application that reads a formatting object tree and renders the resulting pages
to a specified output.
Other FO processors can be configured in the Preferences dialog box.
Add a Font to the Built-in FO Processor - The Simple Version
If the font that must be set to Apache FOP is one of the fonts that are installed in the operating system you should follow
the next steps for creating and setting a FOP configuration file that looks for the font that it needs in the system fonts.
It is a simplified version of the procedure for setting a custom font in Apache FOP.
1. Register the font in FOP configuration. (This is not necessary for DITA PDF transformations, skip to the next step)
a) Create a FOP configuration file that specifies that FOP should look for fonts in the installed fonts of the operating
system.
<fop version="1.0">
<renderers>
<renderer mime="application/pdf">
<fonts>
<auto-detect/>
</fonts>
</renderer>
</renderers>
</fop>
b) Open the Preferences dialog box, go to XML > XSLT/FO/XQuery > FO Processors, and enter the path of the
FOP configuration file in the Configuration file text field.
2. Set the font on the document content.
This is done usually with XSLT stylesheet parameters and depends on the document type processed by the stylesheet.
For DocBook documents you can start with the predefined scenario called DocBook PDF, edit the XSLT parameters
and set the font name (in our example the font family name is Arial Unicode MS) to the parameters
body.font.family and title.font.family.
For TEI documents you can start with the predefined scenario called TEI PDF, edit the XSLT parameters and
set the font name (in our example Arial Unicode MS) to the parameters bodyFont and sansFont.
For DITA transformations to PDF using DITA-OT you should modify the following two files:
LIB=lib
CP=$LIB/fop.jar
CP=$CP:$LIB/avalon-framework-4.2.0.jar
CP=$CP:$LIB/xercesImpl.jar
CP=$CP:$LIB/commons-logging-1.1.1.jar
CP=$CP:$LIB/commons-io-1.3.1.jar
CP=$CP:$LIB/xmlgraphics-commons-1.5.jar
CP=$CP:$LIB/xml-apis.jar
CMD="java -cp $CP org.apache.fop.fonts.apps.TTFReader"
FONT_DIR='.'
The paths specified in the file are relative to the Oxygen XML Editor installation directory. If you decide to create
it in other directory, change the file paths accordingly.
The FONT_DIR can be different on your system. Check that it points to the correct font directory. If the Java
executable is not in the PATH, specify the full path of the executable.
If the font has bold and italic variants, convert them too by adding two more lines to the script file:
for Windows:
%CMD% %FONT_DIR%\Arialuni-Bold.ttf Arialuni-Bold.xml
%CMD% %FONT_DIR%\Arialuni-Italic.ttf Arialuni-Italic.xml
The embed-url attribute points to the font file to be embedded. Specify it using the URL convention. The
metrics-url attribute points to the font metrics file with a path relative to the base element. The triplet
refers to the unique combination of name, weight, and style (italic) for each variation of the font. In our case is
just one triplet, but if the font had variants, you would have to specify one for each variant. Here is an example
for Arial Unicode if it had italic and bold variants:
<fop version="1.0">
...
<fonts>
<font metrics-url="Arialuni.xml" kerning="yes"
embed-url="file:/Library/Fonts/Arialuni.ttf">
<font-triplet name="Arialuni" style="normal"
weight="normal"/>
</font>
<font metrics-url="Arialuni-Bold.xml" kerning="yes"
embed-url="file:/Library/Fonts/Arialuni-Bold.ttf">
<font-triplet name="Arialuni" style="normal"
weight="bold"/>
</font>
<font metrics-url="Arialuni-Italic.xml" kerning="yes"
embed-url="file:/Library/Fonts/Arialuni-Italic.ttf">
<font-triplet name="Arialuni" style="italic"
weight="normal"/>
</font>
</fonts>
...
</fop>
More details about the FOP configuration file are available on the FOP website.
b) Open the Preferences dialog box, go to XML > XSLT/FO/XQuery > FO Processors, and enter the path of the
FOP configuration file in the Configuration file text field.
4. Set the font on the document content.
Adding Libraries to the Built-in FO Processor (XML with XSLT and FO)
Adding Hyphenation Support for XML with XSLT Transformation Scenarios
You can extend the functionality of the built-in FO processor by dropping additional libraries in the
[OXYGEN_DIR]/lib/fop directory. To add support for hyphenation:
1. Download the pre-compiled JAR from OFFO .
2. Copy the fop-hyph.jar file into the [OXYGEN_DIR]/lib/fop folder.
3. Restart Oxygen XML Editor.
Adding Support for PDF Images
1. Download the fop-pdf-images JAR libraries.
2. Copy the libraries into the [OXYGEN_DIR]/lib folder.
3. Restart Oxygen XML Editor.
Adding Libraries to the Built-in FO Processor (DITA-OT)
To use additional libraries with the DITA-OT publishing engine, you need to edit the transformation scenario and add
the path to the new libraries in the Libraries section of the Advanced tab.
Adding Hyphenation Support for DITA-OT Transformation Scenarios
1. Download the pre-compiled JAR from OFFO .
2. Edit the DITA-OT transformation scenario and switch to the Advanced tab. Click the Libraries button and add the
path to the fop-hyph.jar library.
Adding Support for PDF Images
1. Download the fop-pdf-images JAR libraries.
2. Edit the DITA-OT transformation scenario and switch to the Advanced tab. Click the Libraries button and add the
path to the libraries.
Output Formats
Oxygen XML Editor allows you to use transformation scenarios to publish XML content in various output formats (such
as WebHelp, PDF, CHM, EPUB, JavaHelp, Eclipse Help, XHTML, etc.)
For transformations that are not included in your installed version of Oxygen XML Editor, simply install the tool chain
required to perform the specific transformation and process the files in accordance with the processor instructions. A
multitude of target formats are possible. The basic condition for transformation to any format is that your source document
is well-formed.
Note: You need to use the appropriate stylesheet according to the source definition and the desired output. For
example, if you want to transform into an HTML format using a DocBook stylesheet, your source XML document
should conform with the DocBook DTD.
For more information, see the Transformation Scenarios on page 788 section.
The left section that contains separate tabs for Content, Search, and Index.
Note: If your documents contain no indexterm elements, the Index tab is not generated.
Note: You can enhance the appearance of the selected item in the Table of Contents. See the Customizing
WebHelp chapter for more details.
You can navigate through the content of your output using the arrows in the upper-right part of the page. These arrows
allow you to move to the parent, previous, and next topic. The parents of the currently opened topic are also presented
at the top of the page.
Note: You can edit the args.hide.parent.link parameter to hide the Parent, Next, and Previous links.
You can use the
Collapse all button that is displayed in the Content tab to collapse all the topics presented in the
Table of Contents.
The top-right corner of the page contains the following options:
With Frames - Displays the output using HTML frames to render two separate sections (a section that displays the
Table of Contents in the left side and a section that displays the content of a topic in the right side).
Print this page - Opens a dialog box with various printing options and a print preview.
The number of keywords found in a single page (the higher the number, the better).
The context (for example, a word found in a title scores better than a word found in unformatted text). The search
ranking order, sorted by relevance is as follows:
Boolean searches are supported using the following operators: and, or, not. When there are two adjacent search terms
without an operator, or is used as the default search operator (for example, grow flowers is the same as grow or
flowers).
The space character separates keywords (an expression such as grow flowers counts as two separate keywords: grow
and flowers).
Do not use quotes to perform an exact search for multiple word expressions (an expression such as "grow flowers",
returns no results since it searches for two separate words).
indexterm and keywords DITA elements are an effective way to increase the ranking of a page (for example,
content inside keywords elements weighs twice as much as content inside an H1 HTML element).
Words composed by merging two or more words with colon (":"), minus ("-"), underline ("_"), or dot (".") characters
count as a single word.
Always search for words containing three or more characters (shorter words, such as to or of are ignored). This rule
does not apply to CJK (Chinese, Japanese, Korean) languages.
HTML tag elements are also assigned a scoring value and these values are evaluated for the search results. For information
about editing these values, see the Editing Scoring Values of Tag Elements in Search Results on page 852 topic.
This output format is compatible with most of the most recent versions of the following common browsers:
Safari
Opera
Important: Due to some security restrictions in Google Chrome, WebHelp pages loaded from the local system
(through URLs of the file:///... format) may not work properly. We recommend that you load WebHelp
pages in Google Chrome only from a web server (with a URL such as
http://your.server.com/webhelp/index.html or
http://localhost/web_pages/index.html).
Warning: Due to some restrictions in web browsers in regards to JavaScript code, the frameless version
(index.html start page) of the WebHelp system should only be loaded from a web server (with a URL such
as http://your.server.com/webhelp/index.html or
http://localhost/web_pages/index.html). When loading WebHelp pages from the local file
system, the frameset version (index_frames.html start page) of the WebHelp system should be used instead
(file:///...).
Your Name - You can use this field to edit the initial name that you used to create your user profile.
Your email address - You can use this field to edit the initial email address that you used to create your profile.
You can choose to receive an email in the following situations:
New Password - Allows you to enter a new password for your user account.
Note: The Current Password field from the top of the User Profile is mandatory if you want to save the
changes you make.
Search Feature
The Search feature is enhanced with a rating mechanism that computes scores for every page that matches the search
criteria. These scores are then translated into a 5-star rating scheme. The search results are sorted depending on the
following:
The number of keywords found in a single page (the higher the number, the better).
The context (for example, a word found in a title scores better than a word found in unformatted text). The search
ranking order, sorted by relevance is as follows:
Boolean searches are supported using the following operators: and, or, not. When there are two adjacent search terms
without an operator, or is used as the default search operator (for example, grow flowers is the same as grow or
flowers).
The space character separates keywords (an expression such as grow flowers counts as two separate keywords: grow
and flowers).
Do not use quotes to perform an exact search for multiple word expressions (an expression such as "grow flowers",
returns no results since it searches for two separate words).
indexterm and keywords DITA elements are an effective way to increase the ranking of a page (for example,
content inside keywords elements weighs twice as much as content inside an H1 HTML element).
Words composed by merging two or more words with colon (":"), minus ("-"), underline ("_"), or dot (".") characters
count as a single word.
Always search for words containing three or more characters (shorter words, such as to or of are ignored). This rule
does not apply to CJK (Chinese, Japanese, Korean) languages.
HTML tag elements are also assigned a scoring value and these values are evaluated for the search results. For information
about editing these values, see the Editing Scoring Values of Tag Elements in Search Results on page 852 topic.
Oxygen XML WebHelp system supports most of the recent versions of the following browsers: Chrome, Firefox, Internet
Explorer, Safari, Opera.
Create WebHelp with Feedback Database
The WebHelp system needs a database to store user details and the actual feedback, and a user added to it with all
privileges. After this is created, you should have the following information:
Database name
Username
Password
Exactly how you create the database and user depends on your web host and your particular needs.
For example, the following procedure uses phpMyAdmin to create a MySQL database for the feedback
system and a MySQL user with privileges for that database. The feedback system uses these credentials
to connect to the database.
Using phpMyAdmin to create a database:
1. Type localhost in your browser.
2. In the left area, select: phpMyAdmin.
3. Click Databases (in the right frame) and then create a database. You can give it any name you
want (for example comments).
4. Create a user with connection privileges for this database.
5. Under localhost, in the right frame, click Privileges and then at the bottom of the page click the
reload the privileges link.
Open the log.js file, locate the var log= new Log(Level.NONE); line, and change the logging
level to: Level.INFO, Level.DEBUG, Level.WARN, or Level.ERROR.
Append ?log=true to the WebHelp URL.
Execute the transformation scenario that produces the WebHelp with Feedback output directory.
Locate the oxygen-webhelp\resources\php\config\config.php file and delete it.
Locate the oxygen-webhelp\install directory and delete it.
Copy the remaining structure of the output folder and paste it into your WebHelp with Feedback system installation
directory, overwriting the existing content.
User - Regular user, able to post comments and receive e-mail notifications.
Moderator - In addition to the regular User rights, this type of user has access to the Admin Panel where a
moderator can view, delete, export comments, and set the version of the feedback-enabled WebHelp system.
Admin - Full administrative privileges. Can manage WebHelp-specific settings, users, and their comments.
Company
The name of the organization associated with the user.
E-Mail
The contact email address for the user. This is also the address where the WebHelp system sends notifications.
WebHelp Notification
When enabled, the user receives notifications when comments are posted anywhere in your feedback-enabled
WebHelp system.
Reply Notification
When enabled, the user receives notifications when comments are posted as a reply to one of their comments.
Page Notification
When enabled, the user receives notifications when comments are posted on a topic where they previously posted
a comment.
Date
The date the user registered is displayed.
Status
Use this drop-down list to change the status of the user. You can choose from the following:
Created - The user is created but does not yet have any rights for the feedback-enabled WebHelp system.
Validated - The user is able to use the feedback-enabled WebHelp system.
Suspended - The user has no rights for the feedback-enabled WebHelp system.
Warning: The key used for identifying the page a comment is attached to is the relative file path to the output
page. Since the output file and folder names mirror the source, any change to the file name (or its folder) in the
source will affect the comments associated with that WebHelp page. If you change the file name or path, the
comment history for that topic will become orphaned (a change to the topic ID does not affect the comment
history).
Note: If you need different parts of the application (for instance, dialog boxes, views, or editing modes)
to open the same contextual help topic, all of the context ID values should be included in the same DITA
topic file. For example, if you need both a dialog box and a view to open the same WebHelp page, you
can assign different resource IDs in the same DTIA topic.
<prolog>
<resourceid id="dialog1"/>
<resourceid id="view1"/>
</prolog>
The XML mapping file can be loaded by a PHP script on the server side. The script receives the contextId value
and will look it up in the XML file.
Invoke one of the WebHelp system files index.html or index_frames.html and pass the contextId
parameter with a specific value. The WebHelp system will automatically open the help page associated with the
value of the contextId parameter.
The following example will open a frameless version of the WebHelp system showing the page
associated with the id dialog1ID:
index.html?contextId=dialog1ID
The following example will open a frameset version of the WebHelp system showing the page
associated with the id view1ID:
index_frames.html?contextId=view1ID
Settings - Includes a Highlight selection option that helps you identify the areas affected by a particular element
customization.
When hovering an item in the customizable elements menu, the affected sample area is highlighted with a dotted
blue border.
When an item in the customizable elements menu is selected, the affected sample area is highlighted with a solid
red border.
Customize - Provides a series of customizable elements organized under four main categories:
Header
TOC Area
Vertical Splitter
Content
For each customizable element, you can alter properties such as background color or font face. Any alteration made
in the customizable elements menu is applied in real time over the sample area.
Create a Customization Skin
1. The starting point can be either one of the predefined skins or a CSS stylesheet applied over the sample using the
Import button.
2. Use the elements in the Customize section to set properties that modify the look of the skin. By default, all
customizable elements display a single property, but you can make more visible by clicking the
Add button and
choosing from the available properties.
Note: If you want to revert a particular property to its initial value, press the
Reset button.
3. When you are happy with the skin customizations you have made, press the Export button. All settings will be saved
in a CSS file.
Apply a Customization Skin to a DITA Map to WebHelp Transformation Scenario
1. Start Oxygen XML Editor.
2. Load the DITA map you want to produce as a WebHelp output.
3. Edit a DITA Map to WebHelp-type transformation scenario. Set the previously exported CSS file in the Custom
section of the Skins tab.
4. Run the transformation to obtain the WebHelp output.
Apply a Customization Skin to a DocBook to WebHelp Transformation Scenario
1.
2.
3.
4.
4. Save the Tracking Code (obtained in the previous step) in a new HTML file called googleAnalytics.html.
5. In Oxygen XML Editor, click the
Configure Transformation Scenario(s) action from the toolbar (or the
Document > Transformation menu.
6. Select an existing WebHelp transformation scenario (depending on your needs, it may be with or without feedback,
or the mobile variant) and click the Duplicate button to open the Edit Scenario dialog box.
7. Switch to the Parameters tab and edit the webhelp.footer.file parameter to reference the
googleAnalytics.html file that you created earlier.
8. Click Ok.
9. Run the transformation scenario.
Localizing the Interface of WebHelp Output
You can localize the interface of WebHelp output for DITA or DocBook transformations.
How to Localize the Interface of WebHelp Output (for DITA Map Transformations)
Static labels that are used in the WebHelp output are kept in translation files in the
DITA_OT_DIR/plugins/com.oxygenxml.webhelp/oxygen-webhelp/resources/localization
folder. Translation files have the strings-lang1-lang2.xml name format, where lang1 and lang2 are ISO language codes.
For example, the US English text is kept in the strings-en-us.xml file.
To localize the interface of the WebHelp output for DITA map transformations, follow these steps:
1. Look for the strings-[lang1]-[lang2].xml file in
DITA_OT_DIR/plugins/com.oxygenxml.webhelp/oxygen-webhelp/resources/localization
directory (for example, the Canadian French file would be: strings-fr-ca.xml). If it does not exist, create one starting
from the strings-en-us.xml file.
2. Translate all the labels from the above language file. Labels are stored in XML elements that have the following
format: <str name="Label name">Caption</str>.
Integrating the Oxygen XML WebHelp Plugin with the DITA Open Toolkit
This topic includes the procedure for integrating the Oxygen XML WebHelp plugin with the DITA Open Toolkit.
The requirements of the Oxygen XML WebHelp plugin for the DITA Open Toolkit are as follows:
To integrate the Oxygen XML WebHelp plugin with the DITA Open Toolkit, follow these steps:
1.
2.
3.
4.
5. If you are using DITA-OT version 2.x, the WebHelp plugin contains a plugin_2.x.xml which needs to be
renamed to plugin.xml.
6. In the home directory of the DITA Open Toolkit, run ant -f integrator.xml.
7. Go to http://sourceforge.net/projects/saxon/files/Saxon-B/9.1.0.8/, download the
processor.saxonb9-1-0-8j.zip file (contains the Saxon 9.1.0.8), and unzip it to a destination of your
choosing.
Licensing the Oxygen XML WebHelp Plugin for DITA OT
This topic explains how to register the license for the Oxygen XML WebHelp plugin for the DITA Open Toolkit.
To register the license for the Oxygen XML WebHelp plugin for the DITA Open Toolkit, follow these steps:
1. Open the [OXYGEN_DIR]/frameworks/dita/DIT-OT/plugins/com.oxygenxml.webhelp directory
and create a file called licensekey.txt.
2. In this file, copy your license key which you purchased for your Oxygen XML WebHelp plugin.
The WebHelp transformation process reads the Oxygen XML Editor license key from this file. In case the file does
not exit, or it contains an invalid license, an error message will be displayed.
Upgrading the Oxygen XML WebHelp Plugin for DITA OT
This topic describes the procedure for upgrading a Oxygen XML WebHelp plugin for the DITA Open Toolkit.
To upgrade your Oxygen XML WebHelp plugin for the DITA Open Toolkit, follow these steps:
1. Navigate to the plugins directory of your DITA OT distribution and delete the old Oxygen XML WebHelp plugin
files (oxygen_custom.xsl, oxygen_custom_html.xsl) and directories (com.oxygenxml.highlight,
com.oxygenxml.webhelp).
2. Go to Oxygen XML WebHelp website, download the latest installation kit, and unzip it.
3. Copy the com.oxygenxml.webhelp and com.oxygenxml.highlight directories inside the plugins
directory of the DITA OT distribution. The com.oxygenxml.highlight directory adds syntax highlight
capabilities to your WebHelp output for codeblock sections that contain source code snippets (XML, Java,
JavaScript etc.).
4. If you are using DITA-OT version 2.x, the WebHelp plugin contains a plugin_2.x.xml which needs to be
renamed to plugin.xml.
5. In the home directory of the DITA Open Toolkit, run ant -f integrator.xml.
Running an External DITA Transformation Using the Oxygen XML WebHelp Plugin
This topic explains how to run an external DITA to WebHelp transformation using the Oxygen XML WebHelp plugin.
To run a DITA to WebHelp (webhelp, webhelp-feedback, webhelp-mobile) transformation using the Oxygen XML
WebHelp plugin, use:
JVM_INSTALL_DIR - Specifies the path to the Java Virtual Machine installation directory on your disk.
DITA_OT_INSTALL_DIR - Specifies the path to DITA Open Toolkit installation directory on your disk.
Note: The dita.bat and dita.sh scripts reference the dost-patches-DITA-1.8.jar JAR file
containing DITA OT 1.8-specific patches. If you use DITA OT 1.7, update that reference to
dost-patches-DITA-1.7.jar. If you use DITA OT 2.0, no patches are needed, so just remove the
reference.
SAXON_9_DIR - Specifies the path to the directory on your disk where you unzipped the Saxon 9 archive files.
Note: If you are integrating the WebHelp plugin in a DITA OT distribution that comes with the included
Saxon libraries, you can point directly to the Saxon libraries in the DITA OT distribution like this:
set SAXON_9_DIR=C:\path\to\DITA-OT1.8.5\lib\saxon
Otherwise, you can download the Saxon 9.1 JAR files from
https://sourceforge.net/projects/saxon/files/Saxon-B/9.1.0.8/saxonb9-1-0-8j.zip/download.
TRANSTYPE - Specifies the type of the transformation you want to apply. You can set it to webhelp,
webhelp-feedback and webhelp-mobile.
DITA_MAP_BASE_DIR - Specifies the path to the directory where the input DITA map file is located.
DITAMAP_FILE - Specifies the input DITA map file.
DITAVAL_FILE - Specifies the .ditaval input filter that the transformation process applies to the input DITA
map file.
DITAVAL_DIR - Specifies the path to the directory where the .ditaval file is located.
-Doutput.dir - Specifies the output directory of the transformation.
The optional parameter -Dargs.filter can be used to specify a filter file to be used to include, exclude, or flag
content.
Additional Oxygen XML WebHelp Plugin Parameters for DITA
You are able to append the following parameters to the command line that runs the transformation:
-Dwebhelp.sitemap.base.url
Base URL for all the loc elements in the generated sitemap.xml file. The value of a loc element is computed
as the relative file path from the href attribute of a topicref element from the DITA map, appended to this
base URL value. The loc element is mandatory in sitemap.xml. If you leave this parameter set to its default
empty value, then the sitemap.xml file is not generated.
-Dwebhelp.sitemap.change.frequency
The value of the changefreq element in the generated sitemap.xml file. The changefreq element is
optional in sitemap.xml. If you leave this parameter set to its default empty value, then the changefreq
element is not added in sitemap.xml. Allowed values: <empty string> (default), always, hourly, daily,
weekly, monthly, yearly, never.
-Dwebhelp.sitemap.priority
The value of the priority element in the generated sitemap.xml file. It can be set to any fractional number
between 0.0 (least important priority) and 1.0 (most important priority), such as: 0.3, 0.5, 0.8, etc. The priority
element is optional in sitemap.xml. If you leave this parameter set to its default empty value, then the priority
element is not added in sitemap.xml.
-Dwebhelp.footer.include
Specifies whether or not to include footer in each WebHelp page. Possible values: yes, no. If set to no, no footer
is added to the WebHelp pages. If set to yes and the webhelp.footer.file parameter has a value, then the
content of that file is used as footer. If the webhelp.footer.file has no value then the default Oxygen XML
Editor footer is inserted in each WebHelp page.
-Dwebhelp.logo.image (not available for the WebHelp Mobile transformation)
Specifies a path to an image displayed as a logo in the left side of the output header.
-Dwebhelp.logo.image.target.url (not available for the WebHelp Mobile transformation)
Specifies a target URL that is set on the logo image. When you click the logo image, you will be redirected to this
address.
-Dwebhelp.search.ranking (not available for the WebHelp Mobile transformation)
If this parameter is set to false then the 5-star rating mechanism is no longer included in the search results that
are displayed on the Search tab (default setting is true).
-Dwebhelp.search.japanese.dictionary
The file path of the dictionary that will be used by the Kuromoji morphological engine that Oxygen XML Editor
uses for indexing Japanese content in the WebHelp pages. This indexer does not come bundled with Oxygen XML
Editor or the Oxygen XML WebHelp plugin. To use it, you need to download it from
http://mvnrepository.com/artifact/org.apache.lucene/lucene-analyzers-kuromoji/4.0.0 and add it in the
DITA_OT_DIR/plugins/com.oxygenxml.webhelp/lib directory.
-Dwebhelp.google.search.script
Specifies the location of a well-formed XHTML file containing the Custom Search Engine script from Google. The
value must be an URL.
-Dwebhelp.google.search.results
URL value that specifies the location of a well-formed XHTML file containing the Google Custom Search Engine
element gcse:searchresults-only. You can use all supported attributes for this element. It is recommend
to set the linkTarget attribute to frm for frameless (iframe) version of WebHelp or to contentWin for the
frameset version of WebHelp. The default value for this attribute is _blank and the search results will be loaded
in a new window. If this parameter is not specified, the following code will be used
<gcse:searchresults-only linkTarget="frm"></gcse:searchresults-only>
-Dwebhelp.product.id (available only for the WebHelp with Feedback transformation)
This parameter specifies a short name for the documentation target, or product (for example,
mobile-phone-user-guide, hvac-installation-guide).
Note: You can deploy documentation for multiple products on the same server.
where [HEADER_FILE_DIR] is the location of the directory that contains the header file.
Database Configuration for DITA WebHelp with Feedback
This topic explains where to find instructions for configuring the database that contains the user comments for a DITA
WebHelp with Feedback system.
If you run the webhelp-feedback transformation using the WebHelp plugin, you need to configure the database that
holds the user comments. The instructions for configuring the database are presented in the installation.html
file, located at [DITA_MAP_BASE_DIR]/out/[TRANSFORM_TYPE]/oxygen-webhelp/resources. The
installation.html file is created by the transformation process.
Oxygen XML WebHelp Plugin for DocBook
To transform DocBook documents using the Oxygen XML WebHelp plugin, first integrate the plugin with the DocBook
XSL distribution. The purpose of the integration is to add the following transformation types to the DocBook XSL
distribution:
Integrating the Oxygen XML WebHelp Plugin with the DocBook XSL Distribution
This topic includes the procedure for integrating the Oxygen XML WebHelp plugin with the DocBook XSL Distribution.
The WebHelp plugin transformations run as an Ant build script. The requirements are:
To integrate the Oxygen XML WebHelp plugin with the DocBook XSL distribution, follow these steps:
The docbook.bat and the docbook.sh files are located in the home directory of the Oxygen XML WebHelp
Plugin. Before using them to generate an WebHelp system, customize them to match the paths to the JVM, DocBook
XSL distribution and Saxon engine, and also to set the transformation type. To do this, open a script file and edit the
following variables:
JVM_INSTALL_DIR - Specifies the path to the Java Virtual Machine installation directory on your disk.
ANT_INSTALL_DIR - Specifies the path to the installation directory of Ant.
SAXON_6_DIR - Specifies the path to the installation directory of Saxon 6.5.5.
SAXON_9_DIR - Specifies the path to the installation directory of Saxon 9.1.0.8.
DOCBOOK_XSL_DIR - Specifies the path to the installation directory of the DocBook XSL distribution.
TRANSTYPE - Specifies the type of the transformation you want to apply. You can set it to webhelp,
webhelp-feedback and webhelp-mobile.
INPUT_DIR - Specifies the path to the input directory, containing the input XML file.
XML_INPUT_FILE - Specifies the name of the input XML file.
-Dwebhelp.copyright - the copyright note (a text string value) that is added in the footer of the table of contents
frame (the left side frame of the WebHelp output).
-Dwebhelp.footer.file - specifies the location of a well-formed XHTML file containing your custom footer
for the document body. Corresponds to the WEBHELP_FOOTER_FILE XSLT parameter . The fragment must be
an well-formed XHTML, with a single root element. As a common practice, place all the content inside a <div>
element.
-Dwebhelp.footer.include - specifies whether the content of file set in the -Dwebhelp.footer.file
is used as footer in the WebHelp pages. Its values can be yes, or no.
-Dwebhelp.product.id - the value of this parameter is a text string, that the webhelp-feedback transformation
requires. It represents a short name of the documentation target (product). All the user comments that are posted in
the WebHelp output pages and are added in the comments database are bound to this product ID.
Note: You can deploy documentation for multiple products on the same server.
-Dwebhelp.product.version - the value of this parameter is a text string, that the webhelp-feedback
transformation requires. It specifies the documentation version number (for example, 1.0, 2.5, etc.) New user comments
are bound to this version.
Note: Multiple documentation versions can be deployed on the same server.
If you need to further customize your transformation, other DocBook XSL parameters can be appended. Any parameter
that you want to append must follow the -D model of the above parameters. For example, you can append the
html.stylesheet parameter in the following form:
-Dhtml.stylesheet=/path/to/directory/of/stylesheet.css
2. Apply a WebHelp or WebHelp with Feedback transformation scenario to obtain the output.
Adding Videos to WebHelp Generated from DocBook
1. Edit the DocBook document and reference the video using an mediaobject element, as in the following example:
<mediaobject>
<videoobject>
<videodata fileref="http://www.youtube.com/watch/v/VideoName"/>
</videoobject>
</mediaobject>
2. Apply a WebHelp or WebHelp with Feedback transformation scenario to obtain the output.
Changing the Icons in a WebHelp Table of Contents
You can change the icons that appear in a WebHelp table of contents by assigning new image files in a custom CSS
file. By default, the icons for the WebHelp table of contents are defined with the following CSS codes (the first example
is the icon that appears for a collapsed menu and the second for an expanded menu):
.hasSubMenuClosed{
background: url('../img/book_closed16.png') no-repeat;
padding-left: 16px;
cursor: pointer;
}
.hasSubMenuOpened{
background: url('../img/book_opened16.png') no-repeat;
padding-left: 16px;
cursor: pointer;
}
.hasSubMenuOpened{
background: url('TOC-my-opened-button.png') no-repeat;
}
2. It is recommended that you store the image files in the same directory as the default icons.
In the example above, myLogoImage.gif is an image file that you need to store in an images directory from which it
will be copied automatically by the WebHelp transformation to the output directory.
It is recommended that you store the image files in the same directory as the default icons.
Then you need to specify the path of your custom CSS in the transformation scenario.
Edit the WebHelp transformation scenario and open the Parameters tab.
For a DITA transformation, set the args.css parameter to the path of your custom CSS file. Also, set the
args.copycss parameter to yes to automatically copy your custom CSS in the output folder when the
transformation scenario is processed.
For a DocBook transformation, set the html.stylesheet parameter to the path of your custom CSS file.
2. Edit the WebHelp transformation scenario and open the Parameters tab.
a. For a DITA transformation, set the args.css parameter to the path of your custom CSS file. Also, set the
args.copycss parameter to yes to automatically copy your custom CSS in the output folder when the
transformation scenario is processed.
b. For a DocBook transformation, set the html.stylesheet parameter to the path of your custom CSS file.
3. Run the transformation scenario.
Customizing the Header and Footer
In the transformation scenario, you can use the args.hdr and args.ftr parameters to point to resources that contain
your custom HTML <div> blocks. These are included in the header and footer of each generated topic.
As a practical example, to hide the horizontal separator line between the content and footer, follow these steps:
1. Create a custom CSS file that contains the following snippet:
.footer_separator {
display:none;
}
2. Edit the WebHelp transformation scenario and open the Parameters tab.
a. For a DITA transformation, set the args.css parameter to the path of your custom CSS file. Also, set the
args.copycss parameter to yes to automatically copy your custom CSS in the output folder when the
transformation scenario is processed.
b. For a DocBook transformation, set the html.stylesheet parameter to the path of your custom CSS file.
3. Run the transformation scenario.
Adding a Favicon in WebHelp Systems
You can add a custom favicon to your WebHelp system by simply editing a template in an XSL file. To add a favicon,
follow these steps:
1. Edit the following XSL file for DITA or DocBook WebHelp systems:
a) For DITA WebHelp systems, edit the following file:
DITA_OT_DIR\plugins\com.oxygenxml.webhelp\xsl\createMainFiles.xsl.
b) For DocBook WebHelp system, edit the following file:
[OXYGEN_DIR]\frameworks\docbook\xsl\com.oxygenxml.webhelp\xsl\createMainFiles.xsl.
2. Locate the following template in the XSL file: <xsl:template name-"create-toc-common-file">.
3. Add two link elements inside the head element, as in the following example:
<link rel="icon" href="/favicon.ico" type="image/x-icon" />
<link rel="shortcut icon" href="/favicon.ico" type="image/x-icon" />
3. Edit the WebHelp transformation scenario and open the Parameters tab.
a. For a DITA transformation, set the args.css parameter to the path of your custom CSS file. Also, set the
args.copycss parameter to yes to automatically copy your custom CSS in the output folder when the
transformation scenario is processed.
b. For a DocBook transformation, set the html.stylesheet parameter to the path of your custom CSS file.
4. Run the transformation scenario.
WebHelp Runtime Additional Parameters
A deployed WebHelp system can accept the following GET parameters:
log - The value can be true or false (default value). When set to true, it enables JavaScript debugging.
contextId - The WebHelp JavaScript engine will look up the value of this parameter in the mapping file and load
the corresponding HTML help page. For more information, see the Context-Sensitive WebHelp System topic.
Note: You can use an anchor in the contextId parameter to jump to a specific section in a document.
For example, contextId=topicID#anchor.
toc.visible - The value can be true (default value) or false. When set to false, the table of contents will
be collapsed when you load the WebHelp page.
searchQuery - You can use this parameter to perform a search operation when WebHelp is loaded. For example,
if you want to open WebHelp showing all search results for growing flowers, the URL should look like this:
http://localhost/webhelp/index.html?searchQuery=growing%20flowers.
Note that for an element to be flagged, at least one attribute-value pair needs to have a property declared in the
DITAVAL file.
3. Specify the DITAVAL file in the Filters tab of the transformation scenario.
4. Run the transformation scenario.
Chapter
11
Querying Documents
Topics:
This chapter shows how to query XML documents in Oxygen XML Editor with
XPath expressions and the XQuery language.
What is XPath
XPath is a language for addressing specific parts of an XML document. XPath, like the Document Object Model (DOM),
models an XML document as a tree of nodes. An XPath expression is a mechanism for navigating through and selecting
nodes from the XML document. An XPath expression is, in a way, analogous to an SQL query used to select records
from a database.
There are different types of nodes, including element nodes, attribute nodes and text nodes. XPath defines a way to
compute a string-value for each type of node.
XPath defines a library of standard functions for working with strings, numbers and boolean expressions.
Current DITA Map hierarchy - All resources referenced in the currently selected DITA map, opened in the
DITA Maps Manager view.
At the bottom of the scope menu there are available the following scope configuration actions:
Configure XPath working sets - Allows you to configure and manage collections of files and folders,
encapsulated in logical containers called working sets.
XPath file filter - You can filter the files from the selected scope on which the XPath expression will be executed.
By default the XPath expression will be executed only on XML files, but you can also define a set of patterns that
will filter out files from the current scope. If you select the Include archive option, the XPath expression will be
also executed on the files in any archive (including EPUB and DocX) found at the current scope.
Update on caret move - When enabled and you navigate through a document, the XPath expression corresponding
to the XML node at the current cursor position is displayed.
Evaluate as you type - When you select this option, the XPath expression you are composing is evaluated in
real time.
Note: The
Evaluate as you type option and the automatic validation are disabled when you edit huge
documents or when the scope is other than Current file.
Options - Opens the Preferences page of the currently selected processing engine.
Note: During the execution of an XPath expression, the XPath toolbar displays a stop button
button to stop the XPath execution.
. Press this
When you type expressions longer than 60 characters, a dialog box opens that offers you the possibility to switch to the
XPath builder view.
A drop-down menu that allows you to select the type of the expression you want to execute. You can choose between:
Execute XPath button - Press this button to start the execution of the XPath or XQuery expression you are
editing. The result of the execution is displayed in the Results view in a separate tab
Favorites button - Allows you to save certain expressions that you can later reuse. To add an expression as favorite,
press the star button and enter a name under which the expression is saved. The star turns yellow to confirm that the
expression was saved. Expand the drop-down menu next to the star button to see all your favorites. Oxygen XML
Editor automatically groups favorites in folders named after the method of execution
History drop-down menu - Keeps a list of the last 15 executed XPath or XQuery expressions. Use the
history action from the bottom of the list to remove them
Clear
Update on caret move - When enabled and you navigate through a document, the XPath expression
corresponding to the XML node at the current cursor position is displayed.
Evaluate as you type - When you select this option, the XPath expression you are composing is evaluated
in real time.
Note: The
Evaluate as you type option and the automatic validation are disabled when you edit
huge documents or when the scope is other than Current file.
Options - Opens the Preferences page of the currently selected processing engine.
XPath scope menu - Oxygen XML Editor allows you to define a scope on which the XPath operation will be
executed. You can choose where the XPath expression will be executed:
Current DITA Map hierarchy - All resources referenced in the currently selected DITA map, opened in
the DITA Maps Manager view.
At the bottom of the scope menu there are available the following scope configuration actions:
Configure XPath working sets - Allows you to configure and manage collections of files and folders,
encapsulated in logical containers called working sets.
XPath file filter - You can filter the files from the selected scope on which the XPath expression will be
executed. By default the XPath expression will be executed only on XML files, but you can also define a set of
patterns that will filter out files from the current scope. If you select the Include archive option, the XPath
expression will be also executed on the files in any archive (including EPUB and DocX) found at the current
scope.
Content Completion Assistant - It offers context-dependent proposals and takes into account the cursor position in
the document you are editing. The set of functions proposed by the Content Completion Assistant also depends
on the engine version. Select the engine version from the drop-down menu available in the toolbar.
Syntax Highlight - Allows you to identify the components of an expression. To customize the colors of the components
of the expression, open the Preferences dialog box and go to Editor > Syntax Highlight.
Function signature and documentation balloon, when the cursor is located inside a function.
The usual edit actions Cut, Copy, Paste, Select All, Undo, Redo are available in the contextual menu of the top editable
part of the view.
Description - Holds the result thatOxygen XML Editor displays when you run an XPath expression.
Resource - Holds the name of the document on which you run the XPath expression.
Location - Holds the location of the result in the document.
To arrange the results depending on a column, click its header. To group the results by their resource, or by their system
id, right click the header of any column in the results view and select Group by "Resource" or Group by "System
Figure 342: XPath results highlighted in editor panel with character precision
The following snippets are taken from a DocBook book based on the DocBook XML DTD. The book
contains a number of chapters. To return all the chapter nodes of the book, enter //chapter in the
XPath expression field and press (Enter). This action returns all the chapter nodes of the DocBook
book in the Results View. Click a record in the Results View to locate and highlight its corresponding
chapter element and all its children nodes in the document you are editing.
To find all example nodes contained in the sect2 nodes of a DocBook XML document, use the
following XPath expression: //chapter/sect1/sect2/example. Oxygen XML Editor adds
a result in the Results View for each example node found in any sect2 node.
For example, if the result of the above XPath expression is:
- /chapter[1]/sect1[3]/sect2[7]/example[1]
it means that in the edited file the example node is located in the first chapter, third section level
one, seventh section level 2.
Catalogs
The evaluation of the XPath expression tries to resolve the locations of documents referenced in the expression through
the XML catalogs. These catalogs are configured in the Preferences pages and the current XInclude preferences.
As an example, consider the evaluation of the collection(URIofCollection) function (XPath
2.0). To resolve the references from the files returned by the collection() function with an XML
What is XQuery
XQuery is the query language for XML and is officially defined by a W3C Recommendation document. The many
benefits of XQuery include:
XQuery allows you to work in one common model no matter what type of data you're working with: relational,
XML, or object data.
XQuery is ideal for queries that must represent results as XML, to query XML stored inside or outside the database,
and to span relational and XML sources.
XQuery allows you to create many different types of XML representations of the same data.
XQuery allows you to query both relational sources and XML sources, and create one XML result.
The edited file has a transformation scenario associated that uses as transformation engine Saxon 9.6.0.7 PE or Saxon
9.6.0.7 EE.
The edited file has a validation scenario associated that use as validation engine Saxon 9.6.0.7 PE or Saxon 9.6.0.7
EE.
If the Saxon namespace (http://saxon.sf.net) is mapped to a prefix the functions are presented using this prefix, the
default prefix for the Saxon namespace (saxon) is used otherwise.
If you want to use a function from a namespace mapped to a prefix, just type that prefix and the content completion
displays all the XQuery functions from that namespace. When the default namespace is mapped to a prefix the XQuery
functions from this namespace offered by content completion are also prefixed, only the function name being used
otherwise.
The content completion popup window presents all the variables and functions from both the edited XQuery file and its
imports.
* - any string
? - any character
, - patterns separator
If no wildcards are specified, the string to search is used as a partial match (like *textToFind*).
The upper part of the Outline view contains a filter box that allows you to focus on the relevant components. Type a
text fragment in the filter box and only the components that match it are presented. For advanced usage you can use
wildcard characters (*, ?) and separate multiple patterns with commas.
and
<reviews>
<review id="100" movie-id="1">
<rating>5</rating>
<comment>It is made after a great Stephen King book.
</comment>
<author>Paul</author>
</review>
<review id="101" movie-id="1">
<rating>3</rating>
<comment>Tom Hanks does a really nice acting.</comment>
<author>Beatrice</author>
</review>
<review id="104" movie-id="2">
<rating>4</rating>
<comment>Robert De Niro is my favorite actor.</comment>
<author>Maria</author>
</review>
</reviews>
if you drag the review element and drop it between the braces, a pop-up menu will be displayed.
XQuery Validation
With Oxygen XML Editor, you can validate your documents before using them in your transformation scenarios. The
validation uses the Saxon 9.6.0.7 PE processor or the 9.6.0.7 EE, IBM DB2, eXist, Berkeley DB XML, Documentum
xDb (X-Hive/DB) 10, or MarkLogic (version 5 or newer) if you installed them. Any other XQuery processor that offers
an XQJ API implementation can also be used. This is in conformance with the XQuery Working Draft. The processor
is used in two cases: validation of the expression and execution. Although the execution implies a validation, it is faster
to check the expression syntactically, without executing it. The errors that occurred in the document are presented in
the messages view at the bottom of editor window, with a full description message. As with all error messages, if you
click an entry, the line where the error appeared is highlighted.
Recoverable errors ("-warnings")- Allows you to choose how dynamic errors are handled. The following options
can be selected:
All ("all") - Strips all whitespace text nodes from source documents before any further processing, regardless
of any xml:space attributes in the source document.
Optimization level ("-opt") - This option allows optimization to be suppressed when reducing the compiling time
is important, optimization conflicts with debugging, or optimization causes extension functions with side-effects to
behave unpredictably.
Use linked tree model ("-tree:linked") - This option activates the linked tree model.
Enable XQuery 3.0 support ("-qversion:(1.0|3.0)") - If checked, Saxon runs the XQuery transformation with the
XQuery 3.0 support (this option is enabled by default).
Initializer class - Equivalent to the -init Saxon command-line argument. The value is the name of a user-supplied
class that implements the net.sf.saxon.lib.Initializer interface. This initializer is called during the
initialization process, and may be used to set any options required on the configuration programmatically. It is
particularly useful for tasks such as registering extension functions, collations, or external object models, especially
in Saxon-HE where the option cannot be set via a configuration file. Saxon only calls the initializer when running
from the command line, but the same code may be invoked to perform initialization when running user application
code.
Important: The advanced Saxon-HE/PE/EE options configured in a transformation scenario override the
Saxon-HE/PE/EE options defined globally.
The following advanced options are specific for Saxon 9.6.0.7 Professional Edition (PE) and Enterprise Edition (EE)
only:
Use a configuration file ("-config") - Sets a Saxon 9 configuration file that is used for XQuery transformation and
validation
Allow calls on extension functions ("-ext") - If checked, calls on external functions are allowed. Checking this
option is recommended in an environment where untrusted stylesheets may be executed. It also disables user-defined
extension elements and the writing of multiple output files, both of which carry similar security risks.
The advanced options that are specific for Saxon 9.6.0.7 Enterprise Edition (EE) are as follows:
Validation of the source file ("-val") - Requests schema-based validation of the source file and of any files read
using the document() or similar functions. It can have the following values:
Schema validation ("strict") - This mode requires an XML Schema and enables parsing the source documents
with strict schema-validation enabled.
Lax schema validation ("lax") - If an XML Schema is provided, this mode enables parsing the source documents
with schema-validation enabled but the validation will not fail if, for example, element declarations are not found.
Disable schema validation - This specifies that the source documents should be parsed with schema-validation
disabled.
Validation errors in the results tree treated as warnings ("-outval") - Normally, if validation of result documents
is requested, a validation error is fatal. Enabling this option causes such validation failures to be treated as warnings.
Generate bytecode ("--generateByteCode:(on|off)") - If you enable this option, Saxon-EE attempts to generate
Java bytecode for evaluation of parts of a query or stylesheet that are amenable to such an action. For further details
regarding this option, go to http://www.saxonica.com/documentation9.5/index.html#!javadoc.
Enable XQuery update ("-update:(on|off)") - This option controls whether or not XQuery update syntax is accepted.
The default value is off.
Backup files updated by XQuery ("-backup:(on|off)") - If checked, backup versions for any XML files updated
with XQuery Update are generated. This option is available when the Enable XQuery update option is enabled.
Chapter
12
Debugging XSLT Stylesheets and XQuery Documents
Topics:
XSLT/XQuery Debugging
Overview
Layout
Working with the XSLT / XQuery
Debugger
Debugging Java Extensions
Supported Processors for XSLT
/ XQuery Debugging
This chapter explains the user interface and how to use the debugger with XSLT
and XQuery transformations.
Oxygen XML Editor | Debugging XSLT Stylesheets and XQuery Documents | 876
Support for XSLT 1.0 stylesheets (using Saxon 6.5.5 and Xalan XSLT engines), XSLT 2.0 / 3.0 stylesheets and
XPath 2.0 / 3.0 expressions that are included in the stylesheets (using Saxon 9.6.0.7 XSLT engine) and XQuery 1.0
/ 3.0 (using Saxon 9.6.0.7 XQuery engine).
Stepping capabilities: step in, step over, step out, run, run to cursor, run to end, pause, stop.
Output to source mapping between every line of output and the instruction element / source context that generated
it.
Breakpoints on both source and XSLT/XQuery documents.
Call stack on both source and XSLT/XQuery documents.
Trace history on both source and XSLT/XQuery documents.
Support for XPath expression evaluation during debugging.
Step into imported/included stylesheets as well as included source entities.
Available templates and hits count.
Variables view.
Dynamic output generation.
Layout
The XML and XSL files are displayed in Text mode. The other modes (Author mode, Grid mode) are available only in
the Editor perspective.
The debugger perspective contains four sections:
Source document view (XML) - Displays and allows the editing of XML files (documents).
XSLT/XQuery document view (XSLT/XQuery) - Displays and allows the editing of XSL files(stylesheets) or
XQuery documents.
Output document view - Displays the output that results from inputting a document (XML) and a stylesheet (XSL)
or XQuery document in the transformer. The transformation result is written dynamically while the transformation
is processed. There are two types of output views: a text view (with XML syntax highlight) and an XHTML view.
For large outputs, the XHTML view can be disabled (see Debugger Settings).
Control view - The control view is used to configure and control the debugging operations. It also provides a set of
Information views types. This pane has two sections:
Control toolbar
Information views
Oxygen XML Editor | Debugging XSLT Stylesheets and XQuery Documents | 877
Control Toolbar
The Control toolbar contains all the actions that you need to configure and control the debugging process. The following
actions are described as they appear in the toolbar from left to right.
Oxygen XML Editor | Debugging XSLT Stylesheets and XQuery Documents | 878
documents. In an XQuery debugging session this selection field can be set to the default value NONE, because
usually XQuery documents do not require an input source.
XSL / XQuery selector
The current selection represents the stylesheet or XQuery document to be used by the transformation engine. The
selection list contains all opened files (XSLT / XQuery files being emphasized).
Link with editor
When enabled, the XML and XSLT/XQuery selectors display the names of the files opened in the central editor
panels. This button is disabled by default.
Output selector
The selection represents the output file specified in the associated transformation scenario.
XSLT / XQuery parameters
XSLT / XQuery parameters to be used by the transformation.
Libraries
Add and remove the Java classes and jars used as XSLT extensions.
Turn on profiling
Enables / Disables current transformation profiling.
Enable XHTML output
Enables the rendering of the output in the XHTML output view during the transformation process. For performance
issues, disable XHTML output when working with very large files. Note that only XHTML conformant documents
can be rendered by this view. In order to view the output result of other formats, such as HTML, save the Text
output area to a file and use an external browser for viewing.
When starting a debug session from the editor perspective using the Debug Scenario action, the state of this toolbar
button reflects the state of the Show as XHTML output option from the scenario.
Turn on/off output to source mapping
Enables or disables the output to source mapping between every line of output and the instruction element / source
context that generated it.
Debugger preferences
Quick link to Debugger preferences page.
XSLT / XQuery engine selector
Lists the processors available for debugging XSLT and XQuery transformations.
XSLT / XQuery engine advanced options
Advanced options available for Saxon 9.6.0.7.
Step into
Starts the debugging process and runs until the next instruction is encountered.
Step over
Run until the current instruction and its sub-instructions are over. Usually this will advance to the next sibling
instruction.
Oxygen XML Editor | Debugging XSLT Stylesheets and XQuery Documents | 879
Entering (
) or leaving (
Entering (
) or leaving (
Entering (
) or leaving (
Note: When you set a MarkLogic server as a processor, the Show current execution nodes button is
named Refresh current session context from server. Click this button to refresh the information in
all the views.
Oxygen XML Editor | Debugging XSLT Stylesheets and XQuery Documents | 880
Note: For some of the XSLT processors (Saxon-HE/PE/EE) the debugger could be configured to step into the
XPath expressions affecting the behavior of the following debugger actions: Step into, Step over or Step Out.
Stack view
Output Mapping Stack view
Trace view
Templates view (XSLT only)
Nodes/Values Set view
Hotspots view
Oxygen XML Editor | Debugging XSLT Stylesheets and XQuery Documents | 881
The title bar displays the current element index and the number of elements that compose the current context (this
information is not available if you choose Xalan or Saxon 6 as processing engine).
XPath Watch (XWatch) View
The XWatch view shows XPath expressions evaluated during the debugging process. Expressions are evaluated
dynamically as the processor changes its source context.
When you type an XPath expression in the Expression column, Oxygen XML Editor supports you with syntax highlight
and content completion assistance.
Description
Expression
Value
Breakpoints View
This view lists all breakpoints that are set on opened documents. Once you insert a breakpoint it is automatically added
in this list. Breakpoints can be set in XSLT/XQuery documents and XML documents in XSLT/XQuery debugging
sessions. A breakpoint can have an associated break condition that represents an XPath expression evaluated in the
current debugger context. In order to be processed, their evaluation result should be a boolean value. A breakpoint with
an associated condition only stops the execution of the Debugger if the breakpoint condition is evaluated as true.
Oxygen XML Editor | Debugging XSLT Stylesheets and XQuery Documents | 882
Enabled - If checked, the current condition is evaluated and taken into account.
Resource - Resource file and number of the line where the breakpoint is set. The Entire path of resource file is
available as tooltip.
Condition - XSLT/XQuery expression to be evaluated during debugging. The expression will be evaluated at every
debug step.
Oxygen XML Editor | Debugging XSLT Stylesheets and XQuery Documents | 883
Description
Message
Message content.
Terminate
Resource
Clicking a record from the table highlights the xsl:message declaration line.
Message table values can be sorted by clicking the corresponding column header. Clicking the column header
switches the sorting order between: ascending, descending, no sort.
Stack View
This view shows the current execution stack of both source and XSLT/XQuery nodes. During transformation two stacks
are managed: one of source nodes being processed and the other for XSLT/XQuery nodes being processed. Oxygen
XML Editor shows both node types into one common stack. The source (XML) nodes are preceded by a red color icon
while XSLT/XQuery nodes are preceded by a green color icon. The advantage of this approach is that you can always
see the source scope on which a XSLT/XQuery instruction is executed (the last red color node on the stack). The stack
is oriented upside down.
Oxygen XML Editor | Debugging XSLT Stylesheets and XQuery Documents | 884
Table 12: Stack columns
Column
Description
XML/XSLT/XQuery Node
Attributes
Resource
Important: Remarks:
Clicking a record from the stack highlights that node's location inside resource.
Using Saxon, the stylesheet elements are qualified with XSL proxy, while using Xalan you only see their
names. (example: xsl:template using Saxon and template using Xalan).
Only the Saxon processor shows element attributes.
The Xalan processor shows also the built-in rules.
Description
XSL/XQuery Node
Attributes
Oxygen XML Editor | Debugging XSLT Stylesheets and XQuery Documents | 885
Column
Description
Resource
Important: Remarks:
Clicking a record highlights that XSLT template definition/XQuery element inside the resource (XSLT
stylesheet file/XQuery file).
Saxon only shows the applied XSLT templates having at least one hit from the processor. Xalan shows all
defined XSLT templates, with or without hits.
The table can be sorted by clicking the corresponding column header. When clicking a column header the
sorting order switches between: ascending, descending, no sort.
Xalan shows also the built-in XSLT rules.
The trace history catches all these events, so you can see how the process evolved. The red icon lines denote source
nodes while the green icon lines denote XSLT/XQuery nodes.
It is possible to save the element trace in a structured XML document. The action is available on the contextual menu
of the view. In this way you have the possibility to compare the trace results from different debug sessions.
Oxygen XML Editor | Debugging XSLT Stylesheets and XQuery Documents | 886
Table 14: Trace History columns
Column
Description
Depth
XML/XSLT/XQuery Node
Attributes
Resource
Important: Remarks:
Templates View
The xsl:template is the basic element for stylesheets transformation. This view is only available during XSLT
debugging sessions and shows all xsl:template instructions used by the transformation. Being able to see the
number of hits for each of the templates allows you to get an idea of the stylesheet coverage by template rules with
respect to the input source.
Description
Match
Hits
Priority
Mode
Name
Oxygen XML Editor | Debugging XSLT Stylesheets and XQuery Documents | 887
Column
Description
Resource
Important: Remarks:
You click a variable having a node set value in one of the above 2 views.
You click a tree fragment in one of the above 2 views.
You click an XPath expression evaluated to a node set in one of the above 2 views.
For longer values in the right side panel, the interface displays it with an ellipsis (...) at the end. A more
detailed value is available as a tooltip when hovering over it.
Clicking a record highlights the location of that node in the source or stylesheet view.
Variables View
Variables and parameters play an important role during an XSLT/XQuery transformation. Oxygen XML Editor uses
the following icons to differentiate variables and parameters:
- Global variable.
- Local variable.
- Global parameter.
- Local parameter.
Oxygen XML Editor | Debugging XSLT Stylesheets and XQuery Documents | 888
Boolean
String
Date - XSLT 2.0 / 3.0 only.
Number
Set
Object
Fragment - Tree fragment.
Any
Undefined - The value was not yet set, or it is not accessible.
Note:
When Saxon 6.5 is used, if the value is unavailable, then the following message is displayed in the Value
field: "The variable value is unavailable".
When Saxon 9 is used:
If the variable is not used, the Value field displays "The variable is declared but never used".
If the variable value cannot be evaluated, the Value field displays "The variable value is unavailable".
Document
Element
Attribute
ProcessingInstruction
Comment
Text
Namespace
Evaluating - Value under evaluation.
Not Known - Unknown types.
Description
Name
Value type
Type of variable/parameter.
Value
The value of a variable (the Value column) can be copied to the clipboard for pasting it to other editor area with the
action Copy value from the contextual menu of the table from the view. This is useful in case of long and complex
values which are not easy to remember by looking at them once.
Oxygen XML Editor | Debugging XSLT Stylesheets and XQuery Documents | 889
Important: Remarks:
Local variables and parameters are the first entries presented in the table.
Clicking a record highlights the variable definition line.
Variable values could differ depending on the transformation engine used or stylesheet version set.
If the value of the variable is a node set or a tree fragment, clicking it causes the Node Set view to be shown
with the corresponding set of values.
Variable table values can be sorted by clicking the corresponding column header. Clicking the column header
switches between the orders: ascending, descending, no sort.
Menu Window > Open perspective > XSLT Debugger or the toolbar button
Menu Document > XML Document > Debug Scenario or the toolbar button
Debug Scenario. This action
initializes the Debugger perspective with the parameters of the transformation scenario. Any modification applied
to the scenario parameters (the transformer engine, the XSLT parameters, the transformer extensions, etc.) will
be saved back in the scenario when exiting from the Debugger perspective.
XSLT Debugger
3. Select the source XML document in the XML source selector of the Control toolbar. In the case of XQuery debugging,
if your XQuery document has no implicit source, set the source selector value to NONE.
4. Select the XSLT/XQuery document in the XSLT/XQuery selector of the Control toolbar.
5. Set XSLT/XQuery parameters from the button available on the Control toolbar.
6. Set one or more breakpoints.
7. Step through the stylesheet using the buttons available on the Control toolbar:
Step into
Step over
Step out
Run
Run to cursor
Run to end
Pause
Stop
Oxygen XML Editor | Debugging XSLT Stylesheets and XQuery Documents | 890
8. Examine the information in the Information views to find the bug in the transformation process.
You may find the procedure for determining the XSLT template/XQuery element that generated an output section
useful for fixing bugs in the transformation.
Using Breakpoints
The Oxygen XML Editor XSLT/XQuery Debugger allows you to interrupt XSLT/XQuery processing to gather information
about variables and processor execution at particular points. To ensure breakpoints are persistent between work sessions,
they are saved at project level. You can set a maximum of 100 breakpoints per project.
Inserting Breakpoints
To insert a breakpoint, follow these steps:
1. Click the line where you want to insert the breakpoint in the XML source document or the XSLT/XQuery document.
You can only set breakpoints on the XML source in XSLT or XQuery debugging sessions.
Breakpoints are automatically created on the ending line of a start tag, even if you click a different line.
2. Click the vertical stripe on the left side of the editor panel or select
Edit > Breakpoints menu.
Breakpoints
Removing Breakpoints
Only one action is required to remove a breakpoint:
Click the breakpoint icon in the vertical stripe on the left side of the editor panel or select Remove all from the Edit >
Breakpoints menu.
Go to Window > Open perspective > XSLT Debugger or the toolbar button
Go to Document > XML Document > Debug scenario or the toolbar button
Debug scenario . This action
initializes the Debugger perspective with the parameters of the transformation scenario. Any modification applied
to the scenario parameters (the transformer engine, XSLT parameters, transformer extensions, etc.) will be saved
back in the scenario when exiting from the Debugger perspective.
XSLT Debugger
Oxygen XML Editor | Debugging XSLT Stylesheets and XQuery Documents | 891
2. Select the source XML document in the XML source selector of the Control toolbar. In the case of XQuery debugging
without an implicit source choose the NONE value.
3. Select the XSLT / XQuery document in the XSLT / XQuery selector of the Control toolbar.
4. Select the XSLT / XQuery engine in the XSLT / XQuery engine selector of the Control toolbar.
5. Set XSLT / XQuery parameters from the button available on the Control toolbar.
6. Apply the XSLT stylesheet or XQuery transformation using the
Run to end button that is available on the Control
toolbar.
7. Inspect the mapping by clicking a section of the output from the Text view tab or from the XHTML view tab of the
Output document view .
Oxygen XML Editor | Debugging XSLT Stylesheets and XQuery Documents | 892
Oxygen XML Editor | Debugging XSLT Stylesheets and XQuery Documents | 893
c) Set the class ro.sync.exml.Oxygen as the main Java class of the configuration.
The main Java class ro.sync.exml.Oxygen is located in the oxygen.jar file.
2. Start the debug configuration.
Now you can set breakpoints and inspect Java variables as in any Java debugging process executed in the selected
IDE (Eclipse SDK, and so on.).
Saxon 9.6.0.7 HE (Home Edition) - a limited version of the Saxon 9 processor, capable of running XSLT 1.0, XSLT
2.0 / 3.0 basic and XQuery 1.0 transformations, available in both the XSLT debugger and the XQuery one,
Saxon 9.6.0.7 PE (Professional Edition) - capable of running XSLT 1.0 transformations, XSLT 2.0 basic ones and
XQuery 1.0 ones, available in both the XSLT debugger and the XQuery one,
Saxon 9.6.0.7 EE (Enterprise Edition) - a schema aware processor, capable of running XSLT 1.0 transformations,
XSLT 2.0 /3.0 basic ones, XSLT 2.0 / 3.0 schema aware ones and XQuery 1.0 / 3.0 ones, available in both the XSLT
debugger and the XQuery debugger,
Saxon 6.5.5 - capable of running only XSLT 1.0 transformations, available only in the XSLT debugger,
Xalan 2.7.1 - capable of running only XSLT 1.0 transformations, available only in the XSLT debugger.
Chapter
13
Performance Profiling of XSLT Stylesheets and XQuery
Documents
Topics:
XSLT/XQuery Performance
Profiling Overview
Viewing Profiling Information
Working with XSLT/XQuery
Profiler
This chapter explains the user interface and how to use the profiler for finding
performance problems in XSLT transformations and XQuery ones.
Oxygen XML Editor | Performance Profiling of XSLT Stylesheets and XQuery Documents | 896
- Points to a call whose inherent time is insignificant compared to its total time.
- Points to a call whose inherent time is significant compared to its total time (greater than 1/3rd of its total time).
Every entry in the invocation tree includes textual information that depends on the XSLT/XQuery profiler settings:
A percentage number of the total time that is calculated with respect to either the root of the tree or the calling
instruction.
A total time measurement in milliseconds or microseconds. This is the total execution time that includes calls into
other instructions.
A percentage number of the inherent time that is calculated with respect to either the root of the tree or the calling
instruction.
An inherent time measurement in milliseconds or microseconds. This is the inherent execution time of the instruction.
An invocation count that shows how often the instruction has been invoked on this call-path.
An instruction name that contains also the attributes description.
Oxygen XML Editor | Performance Profiling of XSLT Stylesheets and XQuery Documents | 897
Hotspots View
The Hotspots view displays a list of all instruction calls that lie above the threshold defined in the XSLT/XQuery profiler
settings.
Every entry in the backtrace tree has textual information attached to it that depends on the XSLT/XQuery profiler
settings:
A percentage number that is calculated with respect to either the total time or the called instruction.
A time measured in milliseconds or microseconds of how much time has been contributed to the parent hotspot on
this call-path.
An invocation count that shows how often the hotspot has been invoked on this call-path.
Note: This is not the number of invocations of this instruction.
Oxygen XML Editor | Performance Profiling of XSLT Stylesheets and XQuery Documents | 898
Looking to the right side (Hotspots view), you can immediately spot the time the processor spent in each instruction.
As an instruction usually calls other instructions the used time of the called instruction is extracted from the duration
time of the caller (the hotspot only presents the inherent time of the instruction).
Looking to the left side (Invocation tree view), you can examine how style instructions are processed. This result view
is also named call-tree, as it represents the order of style processing. The profiling result shows the duration time for
each of the style-instruction including the time needed for its called children.
Chapter
14
Working with Archives
Topics:
Oxygen XML Editor offers the means to manipulate files directly from ZIP type
archives. By manipulation one should understand opening and saving files
directly in archives, browsing and modifying archive structures. The archive
support is available for all ZIP-type archives, which includes:
ZIP archives
EPUB books
JAR archives
Office Open XML (OOXML) files
Open Document Format (ODF) files
IDML files
This means that you can modify, transform, validate files directly from OOXML
or ODF packages. The structure and content of an EPUB book, OOXML file
or ODF file can be opened, edited and saved as for any other ZIP archive.
You can transform, validate and perform many other operations on files directly
from an archive. When selecting an URL for a specific operation like
transformation or validation you can click the
Browse for archived file
button to navigate and choose the file from a certain archive.
When displaying an archive, the Archive Browser view locks the archive file. It is then automatically unlocked when
the Archive Browser view is closed.
Important: If a file is not recognized by Oxygen XML Editor as a supported archive type, you can add it from
the Archive preferences page.
Create an EPUB
To begin writing an EPUB file from scratch, do the following:
1. Go to File > New , press Ctrl N (Meta N on OS X) on your keyboard. or click
New on the main toolbar.
2. Choose EPUB Book template. Click Create. Choose the name and location of the file. Click Save.
A skeleton EPUB file is saved on disk and open in the Archive Browser view.
3. Use the Archive Browser view specific actions to edit, add and remove resources from the archive.
4. Use the
Validate and Check for Completeness action to verify the integrity of the EPUB archive.
Publish to EPUB
Oxygen XML Editor comes with built-in support for publishing DocBook and DITA XML documents directly to EPUB.
1. Open the Configure Transformation Scenario(s) dialog box and select a predefined transformation scenario. To
publish from DITA, select the DITA Map EPUB transformation scenario. To publish from DocBook select the
DocBook EPUB transformation scenario.
2. Click Apply associated to run the transformation scenario.
Chapter
15
Working with Databases
Topics:
XML is a storage and interchange format for structured data and is supported
by all major database systems. Oxygen XML Editor offers the means for
managing the interaction with some of the most commonly used databases (both
relational and Native XML Databases). Through this interaction, Oxygen XML
Editor helps users to understand browsing, querying, SQL execution support,
content editing, importing from databases, and generating XML Schema from
database structure.
Browsing the tables of these types of databases in the Data Source Explorer view
Executing SQL queries against them
Calling stored procedures with input and output parameters
Oxygen XML Editor offers generic support (table browsing and execution of SQL queries) for any JDBC-compliant
database (for example, MariaDB).
To watch our video demonstration about the integration between the relational databases and Oxygen XML Editor, go
to http://www.oxygenxml.com/demo/Author_Database_Integration.html.
IBM DB2
Microsoft SQL Server
Generic JDBC
MySQL
Oracle 11g
PostgreSQL 8.3
IBM DB2
Microsoft SQL Server
JDBC-ODBC
MySQL
Generic ODBC
Oracle 11g
PostgreSQL 8.3
db2jcc.jar
db2jcc_license_cisuz.jar
db2jcc_license_cu.jar
The Driver files section lists download links for database drivers that are necessary for accessing IBM DB2 databases
in Oxygen XML Editor.
6. Select the most appropriate Driver class.
7. Click the OK button to finish the data source configuration.
To watch our video demonstration about running XQuery against an IBM DB2 Pure XML database, go to
http://www.oxygenxml.com/demo/DB2.html.
How to Configure an IBM DB2 Connection
The support to create an IBM DB2 connection is available in the Enterprise edition only.
To configure a connection to an IBM DB2 server, follow these steps:
1. Open the Preferences dialog box and go to Data Sources.
New button.
Note: For integrated authentication, leave the User and Password fields empty.
b) Enter the user name for the connection to the SQL Server.
c) Enter the password for the connection to the SQL Server.
6. Click the OK button to finish the configuration of the database connection.
How to Configure Generic JDBC Support
To configure the support for a generic JDBC database follow this procedure:
1. Configure a Generic JDBC Data Source driver.
2. Configure a Generic JDBC Connection.
3. Use the Data Source Explorer view from the Window > Show View > Data Source Explorer menu or switch to
the Database Perspective (available from Window > Open Perspective > Database).
How to Configure a Generic JDBC Data Source
Starting with version 17, Oxygen XML Editor comes bundled with Java 8, which does not provide built-in access to
JDBC-ODBC data sources. To access such sources, you need to find an alternative JDBC-ODBC bridge or use a
platform-independent distribution of Oxygen XML Editor along with a Java VM version 7 or 6. The following procedure
shows you how to configure a generic JDBC data source:
1. Open the Preferences dialog box and go to Data Sources.
2. Click the
New button in the Data Sources panel.
3. Enter a unique name for the data source.
Go to the Oracle website and download the Oracle 11g JDBC driver called ojdbc6.jar.
Configure a Oracle 11g Data Source driver.
Configure a Oracle 11g Connection.
Use the Data Source Explorer view from the Window > Show View > Data Source Explorer menu or switch to
the Database Perspective (available from Window > Open Perspective > Database).
New button.
Resource Management
This section explains resource management actions for relational databases.
Data Source Explorer View
The Data Source Explorer view displays your database connections. You can connect to a database simply by expanding
the connection node. The database structure can be expanded to the column level. Oxygen XML Editor supports multiple
simultaneous database connections and the connection tree provides an easy method for browsing them.
Connection
Collection (Catalog)
Schema
Table
System Table
Table Column
A
Collection (called catalog in some databases) is a hierarchical container for resources and sub-collections. There
are two types of resources:
XML resource - An XML document or document fragment, selected by a previously executed XPath query.
Connection node in the tree from the Data Source Explorer view contains the following
Refresh
Performs a refresh for the sub-tree of the selected node.
Disconnect
Closes the current database connection. If a table is already open, you are warned to close it before proceeding.
Configure Database Sources
Opens the Data Sources preferences page where you can configure both data sources and connections.
Actions Available at Catalog Level in Data Source Explorer View
The contextual menu of a
actions:
Catalog node in the tree from the Data Source Explorer view contains the following
Refresh
Performs a refresh for the sub-tree of the selected node.
Actions Available at Schema Level in Data Source Explorer View
The contextual menu of a
actions:
Schema node in the tree from the Data Source Explorer view contains the following
Refresh
Performs a refresh for the sub-tree of the selected node.
Actions Available at Table Level in Data Source Explorer View
The contextual menu of a
Table node in the tree from the Data Source Explorer view contains the following actions:
Refresh
Performs a refresh for the sub-tree of the selected node.
Edit
Opens the selected table in the Table Explorer view.
Export to XML
Opens the Export Criteria dialog box (a thorough description of this dialog box can be found in the Import from
Database chapter) .
XML Schema Repository Level
This section explains the actions available at the XML Schema Repository level.
Oracle XML Schema Repository Level
The Oracle database supports XML schema repository (XSR) in the database catalogs. The contextual menu of a
Schema Repository node in the tree from the Data Source Explorer view contains the following actions:
XML
Refresh
Performs a refresh for the sub-tree of the selected node.
Register
Opens a dialog box for adding a new schema file in the XML repository. To add an XML Schema, enter the schema
URI and location on your file system. Local scope means that the schema is visible only to the user who registers
it. Global scope means that the schema is public.
To avoid having to grant all these privileges to the schema owner, Oracle recommends that the registration
be performed by a DBA if there are XML schema-based XMLType table or columns in other user database
schemas.
IBM DB2 XML Schema Repository Level
The contextual menu of a
the following actions:
XML Schema Repository node in the tree from the Data Source Explorer view contains
Refresh
Performs a refresh for the sub-tree of the selected node.
Register
Opens a dialog box for adding a new schema file in the XML Schema repository. In this dialog box, the following
fields can be set:
Decomposition means that parts of the XML documents are stored in relational tables. Which parts map to which
tables and columns are specified in the schema annotations. Schema dependencies management is done by using
the Add and Remove buttons.
The actions available at
Refresh
Performs a refresh of the selected node (and its sub-tree).
Unregister
Removes the selected schema from the XML Schema Repository.
View
Opens the selected schema in Oxygen XML Editor.
XML Schema Repository node in the tree from the Data Source Explorer view contains
Refresh
Performs a refresh for the sub-tree of the selected node.
Register
Opens a dialog box for adding a new schema file in the DB XML repository. In this dialog box, you enter a collection
name and the necessary schema files. XML Schema files management is done by using the Add and Remove
buttons.
The actions available at
Refresh
Performs a refresh of the selected node (and its sub-tree).
Add
Adds a new schema to the XML Schema files.
Unregister
Removes the selected schema from the XML Schema Repository.
View
Opens the selected schema in Oxygen XML Editor.
Table Explorer View
Every table from the Data Source Explorer view can be displayed and edited in the Table Explorer view by pressing
the Edit button from the contextual menu or by double-clicking one of its fields. To modify the content of a cell,
double-click it and start typing. When editing is complete, Oxygen XML Editor attempts to update the database with
the new cell content.
If the content of the edited cell does not belong to the data type of the column, the cell is marked by a red square and
remains in an editing state until a correct value is inserted. For example, in the following figure propID contains
LONG values. If a character or string is inserted, the cell will look like this:
If the constraints of the database are not met (for instance, primary key constraints), an information dialog box will
appear, notifying you of the reason the database has not been updated. For example, in the table below, trying to set
the second record in the primary key propID column to 8, results in a duplicate entry error since that value has
already been used in the first record:
Depending on your choice, dragging a column results in one of the following statements being inserted into the
document:
SELECT `field` FROM `catalog`. `table` (for example: SELECT `DEPT` FROM `camera`.`cameraDesc`
)
UPDATE `catalog`. `table` SET `field`= (for example: UPDATE `camera`.`cameraDesc` SET `DEPT`=)
INSERT INTO`catalog`. `table` ( `field1) VALUES () (for example: INSERT INTO
`camera`.`cameraDesc` (`DEPT`) VALUES ())
DELETE FROM `catalog`. `table` (for example: DELETE FROM `camera`.`cameraDesc` WHERE
`DEPT`=)
Berkeley DB XML
eXist
MarkLogic
Documentum xDb (X-Hive/DB) 10
Oracle XML DB
To watch our video demonstration about the integration between the XML native databases and Oxygen XML Editor,
go to http://www.oxygenxml.com/demo/Author_Database_XML_Native.html.
Berkeley DB XML
eXist
MarkLogic
Documentul xDB (X-Hive/DB) 10
Berkeley DB XML
eXist
MarkLogic
Documentum xDb (X-Hive/DB) 10
Where [DBXML_DIR] is the Berkeley DB XML database root directory. For example, in Windows it is:
C:\Program Files\Oracle\Berkeley DB XML <version>.
6. Click the OK button to finish the data source configuration.
How to Configure a Berkeley DB XML Connection
Oxygen XML Editor supports Berkeley DB XML versions 2.3.10, 2.4.13, 2.4.16 & 2.5.16. The steps for configuring a
connection to a Berkeley DB XML database are as follows:
1.
2.
3.
4.
5.
exist.jar
lib/core/xmldb.jar
lib/core/xmlrpc-client-3.1.x.jar
lib/core/xmlrpc-common-3.1.x.jar
lib/core/ws-commons-util-1.0.x.jar
lib/core/slf4j-api-1.x.x.jar (if available)
lib/core/slf4j-log4j12-1.x.x.jar (if available)
The version number from the driver file names may be different for your eXist server installation.
6. Click the OK button to finish the connection configuration.
To watch our video demonstration about running XQuery against an eXist XML database, go to
http://www.oxygenxml.com/demo/eXist_Database.html.
How to Configure an eXist Connection
The steps for configuring a connection to an eXist database are as follows:
1.
2.
3.
4.
5.
antlr-runtime.jar
aspectjrt.jar
icu4j.jar
xhive.jar
google-collect.jar
Set the user name to access the Documentum xDb (X-Hive/DB) 10 engine in the User field.
Set the password to access the Documentum xDb (X-Hive/DB) 10 engine in the Password field.
Set the name of the database to access from the Documentum xDb (X-Hive/DB) 10 engine in the Database field.
Check the Run XQuery in read / write session (with committing) checkbox if you want to end the session
with a commit. Otherwise, the session ends with a rollback.
Connection
Collection (Catalog)
Schema
Table
System Table
Table Column
XML resource - An XML document or document fragment, selected by a previously executed XPath query.
Node container - XML documents are stored as individual nodes in the container. Each record in the
underlying database contains a single leaf node, its attributes and attribute values (if any), and its text nodes
(if any). Berkeley DB XML also keeps the information it requires to reassemble the document from the
individual nodes stored in the underlying databases. This is the default, and preferred, container type.
Whole document container - The container contains entire documents. The documents are stored without
any manipulation of line breaks or whitespace.
Allow validation - If checked, it causes documents to be validated when they are loaded into the container. The
default behavior is to not validate documents.
Index nodes - If checked, it causes indices for the container to return nodes rather than documents. The default
is to index at the document level. This property has no meaning if the container type is Whole document
container.
Properties
Displays a dialog box that contains a list of the Berkeley connection properties (version, home location, default
container type, compression algorithm, etc.)
Actions Available at Container Level
In a Berkeley DB XML repository, the actions available at container level in the Data Source Explorer view are as
follows:
Add Resource
Adds a new XML resource to the selected container.
Rename
Allows you to specify a new name for the selected container.
Delete
Removes the selected container from the database tree.
Edit indices
Allows you to edit the indices for the selected container.
Refresh
Performs a refresh for the sub-tree of the selected node.
Granularity:
Index type:
Uniqueness - Indicates whether the indexed value must be unique within the container.
Path type:
Node type:
node - Indicates that you want to index a single node in the path.
edge - Indicates that you want to index the portion of the path where two nodes meet.
Key type:
Syntax types - The syntax describes the type of data the index contains and is mostly used to determine how
indexed values are compared.
DOM Level 3 parser configuration parameters. More about each parameter can be found here: DOM Level 3
Configuration.
Documentum xDb (X-Hive/DB) 10 specific parser parameters (for more information, consult the Documentum xDb
(X-Hive/DB) 10 manual):
xhive-store-schema - If checked, the corresponding DTD or XML schemas are stored in the catalog during
validated parsing.
xhive-store-schema-only-internal-subset - Stores only the internal sub-set of the document (not an external
sub-set). This option modifies the xhive-store-schema (only has a function when that parameter is set to true,
and when a DTD is involved). Select this option if you only want to store the internal sub-set of the document
(not the external sub-set).
xhive-ignore-catalog - Ignores the corresponding DTD and XML schemas in the catalog during validated parsing.
xhive-psvi - Stores psvi information about elements and attributes. Documents parsed with this feature turned
on give access to psvi information and enable support of data types by XQuery queries.
xhive-sync-features - With this convenience setting turned on, parameter settings of XhiveDocumentIf are
synchronized with the parameter settings of LSParser. Note that parameter settings xhive-psvi and
schema-location are always synchronized.
Since the driver was configured to use xhive.jar directly from the xDB installation (where many other jars are
located), core/xercesImpl.jar from the xDB installation directory is loaded even though it is not specified in
the list of jars from the data source driver configuration (it is in the classpath from xhive.jar's MANIFEST.MF). A
simple workaround for this issue is to copy ONLY the jar files used in the driver configuration to a separate folder and
configure the data source driver to use them from there.
Berkeley DB XML
eXist
MarkLogic (validation support available starting with version 5)
Documentum xDb (X-Hive/DB) 10
Relational Databases:
IBM DB2
Microsoft SQL Server (validation support not available)
Oracle (validation support not available)
Build Queries with Drag and Drop from the Data Source Explorer View
When a query is edited in the XQuery editor, the XPath expressions can be composed quickly by dragging them from
the Data Source Explorer view and dropping them into the editor panel.
1. Configure the data source to the relational database.
2. Configure the connection to the relational database.
3. Browse the connection in the Data Source Explorer view, expanded to the table or column that you want to insert
in the query.
4. Drag the table or column name to the XQuery editor panel.
5. Drop the table or column name where the XPath expression is needed.
An XPath expression that selects the dragged name is inserted in the XQuery document at the cursor position.
XQuery Transformation
XQuery is designed to retrieve and interpret XML data from any source, whether it is a database or document. Data is
stored in relational databases but it is often required that the data be extracted and transformed as XML when interfacing
to other components and services. Also, it is an XPath-based querying language supported by most NXD vendors. To
perform a query, you need an XQuery transformation scenario.
1. Configure a data source for the database.
The data source can be relational or XML native.
2. Configure an XQuery transformation scenario.
a) Click the
Configure Transformation Scenario toolbar button or go to menu Document > Transformation >
Configure Transformation Scenario.
The Configure Transformation Scenario dialog box is opened.
Debugging support is available only for MarkLogic server versions 4.0 or newer.
For MarkLogic server versions 4.0 or newer, there are three XQuery syntaxes that are supported: '0.9-ml' (inherited
from MarkLogic 3.2), '1.0-ml', and '1.0'.
The local debugger user interface presents all the debugging steps that the MarkLogic server executes and the results
or possible errors of each step.
All declared variables are presented as strings. The Value column of the Variables view contains the expression
from the variable declaration. It can be evaluated by copying the expression with the Copy value action from the
contextual menu of the Variables view and pasting it in the XWatch view.
There is no support for Output to Source Mapping.
There is no support for showing the trace.
You can set Breakpoints in imported modules in one of the following cases:
When you open the module from the context of the application server involved in the debugging, using the data
source explorer.
When the debugger automatically opens the modules in the Editor.
No breakpoints are set in modules from the same server that are not involved in the current debugging session.
No support for profiling when an XQuery transformation is executed in the debugger.
XQuery
WebDAV Connection
This section explains how to work with a WebDAV connection in the Data Source Explorer view.
BaseX Support
This section explains how to configure the BaseX XML database support. The BaseX support is composed of two parts:
Resource Management
Resource management is available by creating a WebDAV connection to the BaseX server.
First of all, make sure the BaseX HTTP Server is started. For details about starting the BaseX HTTP server, go to
http://docs.basex.org/wiki/Startup#BaseX_HTTP_Server. The configuration file for the HTTP server is named .basex
and is located in the BaseX installation directory. This file helps you to find out the port on which the HTTP server is
running. The default port for BaseX WebDAV is 8984.
To ensure that everything is functioning, open a WebDAV URL inside a browser and check to see if it works. For
example, the following URL retrieves a document from a database named TEST:
http://localhost:8984/webdav/TEST/etc/factbook.xml.
Once you are sure that the BaseX WebDAV service is working, you can configure the WebDAV connection in Oxygen
XML Editor as described in How to Configure a WebDAV Connection on page 948. The WebDAV URL should resemble
this: http://{hostname }:{port}/webdav/. If the BaseX server is running on your own machine and it has
the default configuration, the data required by the WebDAV connection is:
User: admin
Password: admin
Once the WebDAV connection is created, you can start browsing using the Data Source Explorer view.
XQuery Execution
XQuery execution is possible through an XQJ connection.
Port: 1984
serverName: localhost
user: admin
password: admin
XQuery Execution
Now that the XQJ connection is configured, open the XQuery file you want to execute in Oxygen XML Editor and
create a Transformation Scenario as described in XQuery Transformation on page 811. In the Transformer drop-down
menu, select the name of the XQJ connection you created. Apply the transformation scenario and the XQuery will be
executed.
Chapter
16
Importing Data
Topics:
Computer systems and databases contain data in incompatible formats and one
of the most time-consuming activities has been to exchange data between these
systems. Converting the data to XML can greatly reduce complexity and create
data that can be read by different types of applications.
Oxygen XML Editor offers support for importing text files, MS Excel files,
Database Data, and HTML files into XML documents. The XML documents
can be further converted into other formats using the Transform features.
dom4j-1.6.1.jar
poi-ooxml-3.10-FINAL-20140208.jar
poi-ooxml-schemas-3.10-FINAL-20140208.jar
xmlbeans-2.3.0.jar
The previous example first applies a processor called excel on a target identified by the identifier
urn:files:sample.xls and converts the Excel resource to XML. The second applied processor (xslt) applies
an XSLT stylesheet identified using the identifier urn:processors:excel2d.xsl over the content resulting from
the first applied processor. These identifiers are all mapped to real resources on disk via an XML catalog that is configured
in the application, as in the following example:
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<rewriteURI uriStartString="urn:files:" rewritePrefix="./resources/"/>
This type of URL can be opened in the application by using the Open URL action from the File menu. It can also be
referenced from existing XML resources via xi:include or from DITA maps as topic references.
A GitHub project that contains various dynamic conversion samples for producing DITA content from various sources
(and then publishing it) can be found here: https://github.com/oxygenxml/dita-glass.
Conversion Processors
A set of predefined conversion processors is provided in Oxygen XML Editor out-of-the box. Each processor has its
own parameters that can be set to control the behavior of the conversion process. All parameters that are resolved to
resources are passed through the XML catalog mapping.
The following predefined conversion processors are included:
xslt Processor - Converts an XML input using XSLT 2.0 processing. The ss parameter indicates the stylesheet
resource to be loaded. All other specified parameters will be set as parameters to the XSLT transformation.
convert:/processor=xslt;ss=urn:processors:convert.xsl;p1=v1!/urn:files:sample.xml
xquery Processor - Converts an XML input using XQuery processing. The ss parameter indicates the XQuery
script to be loaded. All other specified parameters will be set as parameters to the XSLT transformation.
convert:/processor=xquery;ss=urn:processors:convert.xquery;p1=v1!/urn:files:sample.xml
excel Processor - Converts an Excel input to an XML format that can be later converted by other piped processors.
It has a single parameter sn, which indicates the name of the sheet that needs to be converted. If this parameter is
missing, the XML will contain the combined content of all sheets included in the Excel document.
convert:/processor=excel;sn=test!/urn:files:sample.xls
java Processor - Converts an input to another format by applying a specific Java method. The jars parameter is
a comma separated list of JAR libraries or folders, from which libraries will be loaded. The ccn parameter is the
fully qualified name of the conversion class that will be instantiated. The conversion class needs to have a method
with the following signature:
public void convert(String systemID, String originalSourceSystemID, InputStream is,
OutputStream os, LinkedHashMap<String, String> properties) throws IOException
convert:/processor=java;jars=libs;ccn=test.JavaToXML!/
urn:files:java/WSEditorBase.java
js Processor - Converts an input to another format by applying a JavaScript method. The js parameter indicates
the script that will be used. The fn parameter is the name of the method that will be called from the script. The
method must take a string as an argument and return a string. If any of the parameters are missing, an error is thrown
and the conversion stops.
convert:/processor=js;js=urn:processors:md.js;fn=convertExternal!/urn:files:sample.md
wrap Processor - Wraps content in a tag name making it well-formed XML. The rn parameter indicates the name
of the root tag to use. By default, it is wrapper. The encoding parameter specifies the encoding that should be
used to read the content. By default, it is UTF8. As an example, this processor can be used if you want to process a
Important: If you are publishing a DITA map that has such conversion URL references inside, you need to
edit the transformation scenario and set the value of the parameter fix.external.refs.com.oxygenxml to true. This
will instruct Oxygen XML Editor to resolve such references during a special pre-processing stage. Depending
on the conversion, you may also require additional libraries to be added using the Libaries button in the Advanced
tab of the transformation scenario.
Chapter
17
Content Management System (CMS) Integration
Topics:
This chapter explains how you can use Oxygen XML Editor with Documentum
CMS and Microsoft SharePoint. You can use the plugin support to develop your
own integration with other content management systems..
All the major CMS vendors that are listed in the CMS Solution Partners section
of our website also provide CMS integration with Oxygen XML Editor.
lib/java/emc-bpm-services-remote.jar
lib/java/emc-ci-services-remote.jar
lib/java/emc-collaboration-services-remote.jar
lib/java/emc-dfs-rt-remote.jar
lib/java/emc-dfs-services-remote.jar
lib/java/emc-dfs-tools.jar
lib/java/emc-search-services-remote.jar
lib/java/ucf/client/ucf-installer.jar
lib/java/commons/*.jar (multiple jar files)
lib/java/jaxws/*.jar (multiple jar files)
lib/java/utils/*.jar (multiple jar files)
Note: If for some reason the jar files are not found, you can add them manually by using the Add Files and
Add Recursively buttons and navigating to the lib/java folder from the DFS SDK.
Refresh
Refreshes the connection.
Actions Available on Cabinets / Folders
The actions available on a Documentum (CMS) cabinet in the Data Source Explorer view are the following:
New Folder
Creates a new folder in the current cabinet / folder. The folder properties are the following:
Path - Shows the path where the new folder will be created.
Type - The type of the new folder (default is dm_folder).
Name - The name of the new folder.
Title - The title property of the folder.
Subject - The subject property of the folder.
Path - Shows the path where the new document will be created.
Name - The name of the new document.
Type - The type of the new document (default is dm_document).
Format - The document content type format.
Import
Imports local files / folders in the selected cabinet / folder of the repository. Actions available when performing an
import:
Add Files - Opens a file browse dialog box and allows you to select files to add to the list.
Add Folders - Opens a folder browse dialog box that allows you to select folders to add to the list. The subfolders
will be added recursively.
Edit - Opens a dialog box where you can change the properties of the selected file / folder from the list.
Remove - Removes the selected files / folders from the list.
Rename
Changes the name of the selected cabinet / folder.
Copy
Copies the selected folder to a different location in the tree (available only upon folders). This action can also be
performed with drag and drop while holding the (Ctrl (Meta on Mac OS)) key pressed.
Move
Moves the selected folder to a different location in the tree (available only upon folders). This action can also be
performed with drag and drop.
Delete
Deletes the selected cabinet / folder from the repository. The following options are available:
Folder(s) - Allows you to delete only the selected folder or to delete recursively the folder and all subfolders
and objects.
Version(s) - Allows you to specify what versions of the resources will be deleted.
Virtual document(s) - Here you can specify what happens when virtual documents are encountered. They can
be either deleted either by themselves or together with their descendants.
Refresh
Performs a refresh of the selected node's sub-tree.
Properties
Displays the list of properties of the selected cabinet / folder.
Actions Available on Resources
The actions available on a Documentum (CMS) resource in the Data Source Explorer view are the following:
Edit
Checks out (if not already checked out) and opens the selected resource in the editor.
Edit with
Checks out (if not already checked out) and opens the selected resource in the specified editor / tool.
Open (Read-only)
Opens the selected resource in the editor. The resources are marked as read-only in the editor using a lock icon on
the file tab. If you want to edit those resources, enable the Can edit read only files option.
Open with
Opens the selected resource in the specified editor / tool.
Cancel Checkout
Cancels the checkout process and loses all modifications since the checkout. Action is only available if the resource
is checked out.
Export
Allows you to export the resource and save it locally.
Rename
Changes the name of the selected resource.
Copy
Copies the selected resource in a different location in the tree. Action is not available on virtual document descendants.
This action can also be performed with drag and drop while holding the Ctrl (Meta on OS X) key pressed.
Move
Moves the selected resource in a different location in the tree. Action is not available on virtual document descendants
and on checked out resources. This action can also be performed with drag and drop.
The Site combo box allows you to select and connect to an already defined SharePoint connection.
The
Settings drop-down menu contains actions that help you to quickly define a new connection or manage
the existing ones from the Data Source options page: New SharePoint Connection and Configure Database
Sources. Also, here you can choose one of the predefined view layouts.
The
Depending on the type of node, a contextual menu offers customized actions that can be performed on that node. The
contextual menu of a folder allows you to create new folders and documents, import folders and files, and to rename
and delete the folder.
Note: The rename and delete actions are not available for library root folders (folders located at first level in a
SharePoint library).
Each library node display next to its name a drop down box where you can select the current library view. This functionality
is also available on the node's contextual menu, under the Current View submenu.
Description
folders
documents
Rename
Import
Delete
Copy Location
Check Out
Check In
Refresh
Reserves the current document for your use so that other users
cannot change it while you are editing it.
You can filter and sort the displayed items. To display the available filters of a column, click the filter widget located
on the column's header. You can apply multiple filters at the same time.
Note: A column can be filtered or sorted only if it was configured this way on the server side.
Minor Version - Increments the minor version of the file on the server.
Major Version - Increments the major version of the file on the server.
Overwrite - Overwrites the latest version of the file on the server.
Comment - Allows you to comment on a file that you check in.
Chapter
18
Extending Oxygen XML Editor Using the SDK
Topics:
Oxygen XML Editor has an SDK that can be used as a base to develop
frameworks and plugins. It can be also used to create projects that use the Author
Component. The SDK is available on our website at
http://www.oxygenxml.com/oxygen_sdk.html.
This chapter includes information about extending Oxygen XML Editor with
plugins and the Author Component.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 976
Introduction to Plugins
A plugin can have multiple plugin extensions. The following plugin extensions are available (in the order of importance).
Plugins that are used in the entire workspace:
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 977
The plugin descriptor is an XML file that defines how the plugin is integrated in Oxygen XML Editor and what libraries
are loaded. The structure of the plugin descriptor file is fully described in a DTD grammar located in
[OXYGEN_DIR]/plugins/plugin.dtd. Here is a sample plugin descriptor used by the Capitalize Lines sample
plugin:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plugin SYSTEM "../plugin.dtd">
<plugin
name="Capitalize Lines"
description="Capitalize the first character on each line"
version="1.0.0"
vendor="SyncRO"
class="ro.sync.sample.plugin.caplines.CapLinesPlugin">
<runtime>
<library name="lib/caplines.jar"/>
</runtime>
<extension type="selectionProcessor"
class="ro.sync.sample.plugin.caplines.CapLinesPluginExtension" keyboardShortcut="ctrl shift EQUALS"/>
</plugin>
If your plugin is of type Selection, Document or General, and thus contributes an action either to the contextual menu
or to the main menu of the Text editing mode, then you can assign a keyboard shortcut for it. You can use the
keyboardShortcut attribute for each extension element to specify the desired shortcut.
Tip: To compose string representations of the desired shortcut keys you can go to the Oxygen XML Editor
Menu Shortcut Keys preferences page, press Edit on any action, press the desired key sequence and use the
representation that appears in the Edit dialog box.
Referencing libraries
To reference libraries, use either of the following elements:
Both elements support the scope attribute that defines the loading priority. It can have one of the following three values:
local - the library is loaded in the plugin's own class loader. This is the default behavior
global - the library is loaded in the main application class loader as the last library in the list (as if it would be present
in the application lib directory)
globalHighPriority - the library is loaded in the main application class loader as the first library in the list (useful to
patch certain resources located in other JARs of the application)
Installation
To install a plugin in Oxygen XML Editor, follow these steps:
1. Go to the Oxygen XML Editor installation directory and locate the plugins directory.
The plugins directory contains all the plugins available to Oxygen XML Editor.
2. In the plugins directory create a subfolder to store the plugin files.
3. In the new folder, place the plugin descriptor file (plugin.xml), the Java classes of the plugin and the other files
that are referenced in the descriptor file.
4. Restart Oxygen XML Editor.
Alternatively, you can go to Help > Manage Addons and use the Manage Add-ons dialog box. This dialog allows
you to install available plugins and manage the ones that are currently in use.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 978
Workspace Access Plugin Extension
This plugin type allows you to contribute actions to the main menu and toolbars of Oxygen XML Editor, to create custom
views and interact with the application workspace, make modifications to opened documents and add listeners for various
events.
Many complex integrations (such as integrations with Content Management Systems) usually requires access to some
workspace resources such as toolbars, menus, views, and editors. This type of plugin is also useful because it allows
you to make modifications to the XML content of an opened editor.
The plugin must implement the ro.sync.exml.plugin.workspace.WorkspaceAccessPluginExtension
interface. The callback method applicationStarted of this interface allows access to a parameter of the
ro.sync.exml.workspace.api.standalone.StandalonePluginWorkspace type (allows for API
access to the application workspace).
The StandalonePluginWorkspace interface has three methods that can be called to customize toolbars, menus,
and views:
The toolbar element adds a toolbar in the Oxygen XML Editor interface and allows you to contribute your own
plugin-specific actions. The following attributes are supported:
The view element adds a view in the Oxygen XML Editor interface and allows you to contribute your own
plugin-specific UI components. The following attributes are supported:
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 979
initialRow - Specifies the initial row on the specified side where the view is displayed. For example, in
Oxygen XML Editor, the Project view has an initial row of 0 and the Outline view has an initial row of 1. Both
views are in the WEST part of the workbench.
initialState - Specifies the initial state of the view. The allows values are: hidden, docked, autohide,
and floating. By default, the view is visible and docked.
Access to the opened editors can be done by first getting access to all URLs opened in the workspace using the
StandalonePluginWorkspace.getAllEditorLocations(int editingArea) API method. There are
two available editing areas: the DITA Maps Manager editing area and the main editing area. Using the URL of an
opened resource, you can gain access to it using the StandalonePluginWorkspace.getEditorAccess(URL
location, int editingArea) API method. A ro.sync.exml.workspace.api.editor.WSEditor
then allows access to the current editing page.
A special editing API is supported for the Text mode
(ro.sync.exml.workspace.api.editor.page.text.WSTextEditorPage) and the Author mode
(ro.sync.exml.workspace.api.editor.page.author.WSAuthorEditorPage).
To be notified when editors are opened, selected, and closed, you can use the
StandalonePluginWorkspace.addEditorChangeListener API method to add a listener.
JavaScript-based Workspace Access Plugin Extension
This is a JavaScript-based plugin extension that allows you to contribute actions to the main menu and toolbars of
Oxygen XML Editor, create custom views, interact with the application workspace, make modifications to opened
documents, and add listeners for various events.
This extension can use the same API as the Workspace Access Plugin Extension on page 978, but the implementation is
JavaScript-based and uses the bundled Rhyno library to create and work with Java API from the JavaScript code.
The plugin descriptor file plugin.xml needs to point to a JavaScript file, as in the following example:
<!DOCTYPE plugin PUBLIC "-//Oxygen Plugin" "../plugin.dtd">
<plugin
id="unique.id.value"
name="Add Action To DITA Maps Manager popup-menu"
description="Plugin adds contextual menu action to DITA Maps Manager pop-up menu."
version="1.0"
vendor="Syncro Soft"
class="ro.sync.exml.plugin.Plugin"
classLoaderType="preferReferencedResources">
<extension type="WorkspaceAccessJS" href="wsAccess.js"/>
</plugin>
In the example above, the JavaScript file wsAccess.js, located in the plugin folder, will be called. This JavaScript
file needs to have two JavaScript methods defined inside. Methods that will be called when the application starts and
when it ends:
function applicationStarted(pluginWorkspaceAccess) {
..........
}
function applicationClosing(pluginWorkspaceAccess) {
..........
}
Below is a much larger example with a JavaScript Workspace Access plugin extension implementation that adds a new
action in the contextual menu of the DITA Maps Manager view. The action starts the notepad.exe application and
passes the reference to the currently selected topicref to it.
function applicationStarted(pluginWorkspaceAccess) {
Packages.java.lang.System.err.println("Application started " + pluginWorkspaceAccess);
edChangedListener = {
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 980
/*Called when a DITA Map is opened*/
editorOpened: function (editorLocation) {
Packages.java.lang.System.err.println("\nrunning " + editorLocation);
/*Get the opened DITA Map*/
editor = pluginWorkspaceAccess.getEditorAccess(editorLocation,
Packages.ro.sync.exml.workspace.api.PluginWorkspace.DITA_MAPS_EDITING_AREA);
ditaMapPage = editor.getCurrentPage();
/*Add listener called when right click is performed in the DITA Maps manager view*/
customizerObj = {
customizePopUpMenu: function (popUp, ditaMapDocumentController) {
Packages.java.lang.System.err.println("RIGHT CLICK" + popUp);
tree = ditaMapPage.getDITAMapTreeComponent();
/*Selected tree path*/
sel = tree.getSelectionPath();
if (sel != null) {
selectedElement = sel.getLastPathComponent();
/*Reference attribute*/
href = selectedElement.getAttribute("href");
if (href != null) {
try {
/*Create absolute reference*/
absoluteRef = new Packages.java.net.URL(selectedElement.getXMLBaseURL(), href.getValue());
Packages.java.lang.System.err.println("Computed absolute reference " + absoluteRef);
mi = new Packages.javax.swing.JMenuItem("Run notepad");
popUp.add(mi);
actionPerfObj = {
actionPerformed: function (e) {
try {
Packages.java.lang.Runtime.getRuntime().exec("notepad.exe " +
pluginWorkspaceAccess.getUtilAccess().locateFile(absoluteRef));
}
catch (e1) {
e1.printStackTrace();
}
}
}
mi.addActionListener(new JavaAdapter(Packages.java.awt.event.ActionListener, actionPerfObj));
}
catch (e1) {
Packages.java.lang.System.err.println(e1);
}
}
}
}
}
ditaMapPage.setPopUpMenuCustomizer(new
Packages.ro.sync.exml.workspace.api.editor.page.ditamap.DITAMapPopupMenuCustomizer(customizerObj));
}
}
edChangedListener = new JavaAdapter(Packages.ro.sync.exml.workspace.api.listeners.WSEditorChangeListener,
edChangedListener);
pluginWorkspaceAccess.addEditorChangeListener(
edChangedListener,
Packages.ro.sync.exml.workspace.api.PluginWorkspace.DITA_MAPS_EDITING_AREA);
}
function applicationClosing(pluginWorkspaceAccess) {
Packages.java.lang.System.err.println("Application closing " + pluginWorkspaceAccess);
}
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 981
getComponentsValidator() - Returns a ro.sync.exml.ComponentsValidator implementation
class used for validating the menus, toolbars, and their actions.
The ComponentsValidator interface provides methods to filter various features from being added to the GUI
of Oxygen XML Editor:
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 982
This type of plugin extension can be usually combined with a Workspace Access Plugin Extension on page 978 which
can add a custom toolbar with custom actions for opening documents from a certain source.
As an alternative, two older plugin extensions can also be used to add a toolbar action for showing a custom URL
chooser:
With the help of the URLChooserPluginExtension2 interface, it is possible to create your own dialog box
that works with the custom protocol. This interface provides two methods:
With the help of the URLChooserToolbarExtension interface, it is possible to provide a toolbar entry which
is used for launching the custom URLs chooser from the URLChooserPluginExtension implementation. This
interface provides two methods:
getLockHandler() - Returns a LockHandler implementation class with the implementation of the lock
specific methods from the plugin.
isLockingSupported(String protocol) - Returns a boolean that is true if the plugin accepts to
manage locking for a certain URL protocol scheme like ftp, http, https, or customName.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 983
Open Redirect Plugin Extension
This type of plugin is useful for opening more than one file with only one open action.
For example when a zip archive or an ODF file or an OOXML file is open in the Archive Browser view a plugin of
this type can decide to open a file also from the archive in an XML editor panel. This file can be the document.xml
main file from an OOXML file archive or a specific XML file from a zip archive.
The plugin must implement the interface OpenRedirectExtension. It has only one callback: redirect(URL)
that receives the URL of the file opened by the Oxygen XML Editor user. If the plugin decides to open also other files
it must return an array of information objects (OpenRedirectInformation[]) that correspond to these files. Such
an information object must contain the URL that is opened in a new editor panel and the content type, for example
text/xml. The content type is used for determining the type of editor panel. A null content type allows auto-detection
of the file type.
Targeted URL Stream Handler Plugin Extension
This type of plugin can be used when it is necessary to impose custom URL stream handlers for specific URLs.
This plugin extension can handle the following protocols: http, https, ftp or sftp, for which Oxygen XML Editor
usually provides specific fixed URL stream handlers. If it is set to handle connections for a specific protocol, this
extension will be asked to provide the URL stream handler for each opened connection of an URL having that protocol.
To use this type of plugin, you have to implement the
ro.sync.exml.plugin.urlstreamhandler.TargetedURLStreamHandlerPluginExtension
interface, that provides the following methods:
To use this type of extension in your plugin, create an extension of TargetedURLHandler type in your plugin.xml
and specify the class that implements TargetedURLStreamHandlerPluginExtension:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plugin SYSTEM "../plugin.dtd">
<plugin name="CustomTargetedURLStreamHandlerPlugin" ..............>
<runtime>
........
</runtime>
<extension type="TargetedURLHandler" class="CustomTargetedURLStreamHandlerPluginExtension"/>
...............
</plugin>
This extension can be useful in situations when connections opened from a specific host must be handled in a particular
way. For example, the Oxygen XML Editor HTTP URLStreamHandler may not be compatible for sending and
receiving SOAP using the SUN Web Services implementation. In this case you can override the stream handler set by
Oxygen XML Editor for HTTP to use the default SUN URLStreamHandler which is more compatible with sending
and receiving SOAP requests.
public class CustomTargetedURLStreamHandlerPluginExtension
implements TargetedURLStreamHandlerPluginExtension {
@Override
public boolean canHandleProtocol(String protocol) {
boolean handleProtocol = false;
if ("http".equals(protocol) || "https".equals(protocol)) {
// This extension handles both HTTP and HTTPS protocols
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 984
handleProtocol = true;
}
return handleProtocol;
}
@Override
public URLStreamHandler getURLStreamHandler(URL url) {
// This method is called only for the URLs with a protocol
// for which the canHandleProtocol(String) method returns true (HTTP and HTTPS)
URLStreamHandler handler = null;
String host = url.getHost();
String protocol = url.getProtocol();
if ("some_host".equals(host)) {
// When there are connections opened from some_host, the SUN HTTP(S)
// handlers are used
if ("http".equals(protocol)) {
handler = new sun.net.www.protocol.http.Handler();
} else {
handler = new sun.net.www.protocol.https.Handler();
}
}
return handler;
}
}
LockHandler getLockHandler()
Gets the lock handler for the current handled protocol. Might be null if not supported.
To use this type of extension in your plugin, create an extension of LockHandlerFactory type in your
plugin.xml and specify the class implementing LockHandlerFactoryPluginExtension:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plugin SYSTEM "../plugin.dtd">
<plugin name="CustomLockHandler" ..............>
<runtime>
........
</runtime>
<extension type="LockHandlerFactory" class="LockHandlerFactoryPluginExtensionImpl"/>
...............
</plugin>
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 985
AuthorStylesheet Plugin Extension
This plugin type allows the developer to add a stylesheet (CSS or LESS) that renders elements in Author mode.
In order to specify additional stylesheets, edit the plugin descriptor and add extension elements that point to them,
like in the following example:
<extension type="AuthorStylesheet" href="showTables.css"/>
<extension type="AuthorStylesheet" href="hideButtons.css"/>
Using this mechanism, you can add one or more CSS stylesheets to merge with the existing ones. Whenever you add a
new stylesheet using this plugin, it will have priority over all other stylesheets applied on the file edited in Author mode.
If your implementation requires more flexibility (such as a dynamic change of the stylesheet), you should consider using
the StylesFilter plugin extension.
Plugin Extensions Designed to Work only in the Text Editing Mode
These plugin extensions operate only when editing documents in the Text mode. They are mounted automatically by
the application on the contextual menu in the Plugins submenu.
General Plugin Extension
This plugin type allows the developer to invoke custom code and to interact with the workspace of Oxygen XML Editor.
This plugin is the most general plugin type. It provides a limited API:
The interface GeneralPluginExtension - Intended for general-purpose plugins, kind of external tools but
triggered from the Plugins menu. The implementing classes must provide the method
process(GeneralPluginContext) which must provide the plugin processing. This method takes as a
parameter a GeneralPluginContext object.
The class GeneralPluginContext - Represents the context in which the general plugin extension does its
processing. The getPluginWorkspace() method allows you access to the workspace of Oxygen XML Editor.
The interface SelectionPluginExtension - The context containing the selected text is passed to the extension
and the processed result is going to replace the initial selection. The process(GeneralPluginContext)
method must return a SelectionPluginResult object which contains the result of the processing. The String
value returned by the SelectionPluginResult object can include editor variables such as ${caret} and
${selection}.
The SelectionPluginContext object represents the context. It provides four methods:
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 986
The interface DocumentPluginExtension - Receives the context object containing the current document in
order to be processed. The process(GeneralPluginContext) method can return a
DocumentPluginResult object containing a new document.
The DocumentPluginContext object represents the context. It provides three methods:
How to
Different tutorials about how to implement complex plugins.
How to Write a CMS Integration Plugin
In order to have a complete integration between Oxygen XML Editor and any CMS you usually have to write a plugin
which combines two available plugin extensions:
Workspace Access
Custom protocol
The usual set of requirements for an integration between Oxygen XML Editor and the CMS are the following:
Contribute to the Oxygen XML Editor toolbars and main menu with your custom Check Out and Check In actions:
Check Out triggers your custom dialog boxes that allow you to browse the remote CMS and choose the resources
you want to open.
Check In allows you to send the modified content back to the server.
You can use the Workspace Access plugin extension (and provided sample Java code) for all these operations.
When Check Out is called, use the Oxygen XML Editor API to open your custom URLs (URLs created using your
custom protocol). It is important to implement and use a Custom Protocol extension in order to be notified when
the files are opened and saved and to be able to provide the content for the relative references the files may contain
to Oxygen XML Editor . Your custom java.net.URLStreamHandler implementation checks out the resource
content from the server, stores it locally and provides its content. Sample Check Out implementation:
/**
* Sample implementation for the "Check Out" method.
*
* @param pluginWorkspaceAccess The plugin workspace access (Workspace Access plugin).
* @throws MalformedURLException
*/
private void checkOut(StandalonePluginWorkspace pluginWorkspaceAccess) throws MalformedURLException {
//TODO Show the user a custom dialog box for browsing the CMS
//TODO after the user selected the resource create an URL with a custom protocol
// which will uniquely map to the resource on the CMS using the URLHandler
//something like:
URL customURL = new URL("mycms://host/path/to/file.xml");
//Ask Oxygen to open the URL
pluginWorkspaceAccess.open(customURL);
//Oxygen will then your custom protocol handler to provide the contents for the resource
"mycms://host/path/to/file.xml"
//Your custom protocol handler will check out the file in a temporary directory for example and provide
the content from it.
//Oxygen will also pass through your URLHandler if you have any relative references which need to be
opened/obtained.
}
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 987
Contribute a special Browse CMS action to every dialog box in Oxygen XML Editor where a URL can be chosen
to perform a special action (such as the Reuse Content or Insert Image action). Sample code:
//Add an additional browse action to all dialog boxes/places where Oxygen allows selecting an URL.
pluginWorkspaceAccess.addInputURLChooserCustomizer(new InputURLChooserCustomizer() {
public void customizeBrowseActions(List<Action> existingBrowseActions, final InputURLChooser chooser)
{
//IMPORTANT, you also need to set a custom icon on the action for situations when its text is not
used for display.
Action browseCMS = new AbstractAction("CMS") {
public void actionPerformed(ActionEvent e) {
URL chosenResource = browseCMSAndChooseResource();
if (chosenResource != null) {
try {
//Set the chosen resource in the combo box chooser.
chooser.urlChosen(chosenResource);
} catch (MalformedURLException e1) {
//
}
}
}
};
existingBrowseActions.add(browseCMS);
}
});
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 988
When inserting references to other resources using the actions already implemented in Oxygen XML Editor, the
reference to the resource is made by default relative to the absolute location of the edited XML file. You can gain
control over the way in which the reference is made relative for a specific protocol like:
//Add a custom relative reference resolver for your custom protocol.
//Usually when inserting references from one URL to another Oxygen makes the inserted path relative.
//If your custom protocol needs special relativization techniques then it should set up a custom relative
//references resolver to be notified when resolving needs to be done.
pluginWorkspaceAccess.addRelativeReferencesResolver(
//Your custom URL protocol for which you already have a custom URLStreamHandlerPluginExtension set
up.
"mycms",
//The relative references resolver
new RelativeReferenceResolver() {
public String makeRelative(URL baseURL, URL childURL) {
//Return the referenced path as absolute for example.
//return childURL.toString();
//Or return null for the default behavior.
return null;
}
});
Write the plugin.xml descriptor. Your plugin combines the two extensions using a single set of libraries. The
descriptor would look like:
<!DOCTYPE plugin SYSTEM "../plugin.dtd">
<plugin
name="CustomCMSAccess"
description="Test"
version="1.0.0"
vendor="ACME"
class="custom.cms.CMSAccessPlugin">
<runtime>
<library name="lib/cmsaccess.jar"/>
</runtime>
<!--Access to add actions to the main menu and toolbars or to add custom views.-->
<!--See the "ro.sync.sample.plugin.workspace.CustomWorkspaceAccessPluginExtension" Java sample for more
details-->
<extension type="WorkspaceAccess"
class="custom.cms.CustomWorkspaceAccessPluginExtension"/>
<!--The custom URL handler which will communicate with the CMS implementation-->
<!--See the "ro.sync.sample.plugin.workspace.customprotocol.CustomProtocolURLHandlerExtension" Java sample
for more details-->
<extension type="URLHandler"
class="custom.cms.CustomProtocolURLHandlerExtension"/>
</plugin>
Copy your new plugin directory in the plugins subfolder of the Oxygen XML Editor install folder and start Oxygen
XML Editor.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 989
If you experience additional problems like the following:
java.lang.LinkageError: ClassCastException: attempting to cast
jar:file:/C:/jdk1.6.0_06/jre/lib/rt.jar!/javax/xml/ws/spi/Provider.classtojar:file:/D:/Program
Files/Oxygen XML Editor
12/plugins/wspcaccess/../../xdocs/lib/jaxws/jaxws-api.jar!/javax/xml/ws/spi/Provider.class
at javax.xml.ws.spi.Provider.provider(Provider.java:94) at
javax.xml.ws.Service.<init>(Service.java:56)
......................................................................
The cause could be the fact that some classes are instantiated using the context class loader of the current thread. The
most straightforward fix is to write your code in a try/finally statement:
ClassLoader oldClassLoader = Thread.currentThread().getContextClassLoader();
try {
//This is the implementation of the WorkspaceAccessPluginExtension plugin interface.
Thread.currentThread().setContextClassLoader(
CustomWorkspaceAccessPluginExtension.this.getClass().getClassLoader());
//WRITE YOUR CODE HERE
} finally {
Thread.currentThread().setContextClassLoader(oldClassLoader);
}
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 990
line tool inside Oracle's Java Development Kit. ([JDK_DIR]/bin/jarsigner.exe) or, if you are working
with Ant, you can use the signjar task (which is just a front for the jarsigner command line tool).
Note: The benefit of having a signed add-on is that you can verify the integrity of the add-on issuer. If you
do not have such a certificate you can generate one yourself using the keytool command line tool. This
approach is mostly recommended for tests since anyone can create a self signed certificate.
3. Create a descriptor file. You can use a template that Oxygen XML Editor provides. To use this template, go to File >
New and select the Oxygen add-ons update site template. Once deployed, this descriptor file is referenced as update
site.
Alternatively, you can use the Add-ons Packager plugin by following this procedure:
1. Install the Add-ons Packager plugin from http://www.oxygenxml.com/InstData/Addons/optional/updateSite.xml as
described in the Installing Add-ons procedure.
2. Restart Oxygen XML Editor. If the add-on is correctly installed, the Add-ons packager toolbar action is available.
3. Invoke the Add-ons packager toolbar action and input the required information in the displayed dialog box.
4. Press OK to complete the packaging process.
Deploying an Add-on
To deploy an add-on, copy the ZIP/JAR file and the descriptor file to an HTTP server. The URL to this location serves
as the Update Site URL.
How to Share the Classloader Between a Framework and a Plugin
In some cases you may need to extend the functionality of Oxygen XML Editor both through a framework and through
a plugin. Normally, a framework and a plugin both run in their own private classloader. If the framework and the plugin
use the same JAVA extensions/classes, it is recommended that they share the same classloader. This way, the common
classes are loaded by only one classloader and they will both use the same static objects and have the ability to cast
objects between one another.
To do this, open the Preferences dialog box, go to Document Type Association, select the document type, go to the
Classpath tab, and in the Use parent classloader from plugin with ID fields introduce the ID of the plugin. This ID
is declared in the configuration file of the plugin.
Important: The shared classed must be specified only in the configuration files of the plugin, and not in the
configuration file and the document type class path at the same time.
UppercasePlugin.java:
package ro.sync.sample.plugin.uppercase;
import ro.sync.exml.plugin.Plugin;
import ro.sync.exml.plugin.PluginDescriptor;
public class UppercasePlugin extends Plugin {
/**
* Plugin instance.
*/
private static UppercasePlugin instance = null;
/**
* UppercasePlugin constructor.
*
* @param descriptor Plugin descriptor object.
*/
public UppercasePlugin(PluginDescriptor descriptor) {
super(descriptor);
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 991
if (instance != null) {
throw new IllegalStateException("Already instantiated !");
}
instance = this;
}
/**
* Get the plugin instance.
*
* @return the shared plugin instance.
*/
public static UppercasePlugin getInstance() {
return instance;
}
}
UppercasePluginExtension.java:
package ro.sync.sample.plugin.uppercase;
import
import
import
import
ro.sync.exml.plugin.selection.SelectionPluginContext;
ro.sync.exml.plugin.selection.SelectionPluginExtension;
ro.sync.exml.plugin.selection.SelectionPluginResult;
ro.sync.exml.plugin.selection.SelectionPluginResultImpl;
plugin.xml:
<!DOCTYPE plugin SYSTEM "../plugin.dtd">
<plugin
name="UpperCase"
description="Convert the selection to uppercase"
version="1.0.0"
vendor="SyncRO"
class="ro.sync.sample.plugin.uppercase.UppercasePlugin">
<runtime>
<library name="lib/uppercase.jar"/>
</runtime>
<extension type="selectionProcessor"
class="ro.sync.sample.plugin.uppercase.UppercasePluginExtension"/>
</plugin>
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 992
File frameworksFolder The file path to the frameworks directory. It can point to a custom frameworks
directory where the custom framework resides.
File pluginsFolder The file path to the plugins directory. It can point to a custom plugins directory where
the custom plugins resides.
String licenseKey The license key used to license the test class.
6. Create test methods which use the API in the base class to open XML files and perform different actions on them.
Your test class could look something like:
public class MyTestClass extends PluginWorkspaceTCBase {
/**
* Constructor.
*/
public MyTestClass() throws Exception {
super(new File("frameworks"), new File("plugins"),
"------START-LICENSE-KEY------\n" +
"\n" +
"Registration_Name=Developer\n" +
"\n" +
"Company=\n" +
"\n" +
"Category=Enterprise\n" +
"\n" +
"Component=XML-Editor, XSLT-Debugger, Saxon-SA\n" +
"\n" +
"Version=14\n" +
"\n" +
"Number_of_Licenses=1\n" +
"\n" +
"Date=09-04-2012\n" +
"\n" +
"Trial=31\n" +
"\n" +
"SGN=MCwCFGNoEGJSeiC3XCYIyalvjzHhGhhqAhRNRDpEu8RIWb8icCJO7HqfVP4++A\\=\\=\n" +
"\n" +
"-------END-LICENSE-KEY-------");
}
/**
* <p><b>Description:</b> TC for opening a file and using the bold operation</p>
* <p><b>Bug ID:</b> EXM-20417</p>
*
* @author radu_coravu
*
* @throws Exception
*/
public void testOpenFileAndBoldEXM_20417() throws Exception {
WSEditor ed = open(new File("D:/projects/eXml/test/authorExtensions/dita/sampleSmall.xml").toURL());
//Move caret
moveCaretRelativeTo("Context", 1, false);
//Insert <b>
invokeAuthorExtensionActionForID("bold");
assertEquals("<?xml version=\"1.0\" encoding=\"utf-8\"?>\n" +
"<!DOCTYPE task PUBLIC \"-//OASIS//DTD DITA Task//EN\"
\"http://docs.oasis-open.org/dita/v1.1/OS/dtd/task.dtd\">\n" +
"<task id=\"taskId\">\n" +
"
<title>Task <b>title</b></title>\n" +
"
<prolog/>\n" +
"
<taskbody>\n" +
"
<context>\n" +
"
<p>Context for the current task</p>\n" +
"
</context>\n" +
"
<steps>\n" +
"
<step>\n" +
"
<cmd>Task step.</cmd>\n" +
"
</step>\n" +
"
</steps>\n" +
"
</taskbody>\n" +
"</task>\n" +
"", getCurrentEditorXMLContent());
}
}
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 993
Note: The extracted folder name depends on which product variant you have downloaded. For the purpose
of this procedure the folder will be referred to as [OXYGEN_DIR].
2. Set up the oXygen SDK following this set of instructions.
3. Create an Eclipse Java Project (for example, MyPluginProject) from one of the sample plugins (the Workspace
Access plugin for example).
4. In the MyPluginProject folder, create a folder called myPlugin. In this new folder copy the plugin.xml
from the sample plugin. Modify the added plugin.xml to add a library reference to the directory where Eclipse
copies the compiled output. To find out where this directory is located, invoke the contextual menu of the project
(in the Project view), and go to Build Path > Configure Build Path. Then inspect the value of the Default output
folder text box.
Example: If the compiled output folder is classes, then the you need to add in the plugin.xml the following
library reference:
<library name="../classes"/>
5. Copy the plugin.dtd from the [OXYGEN_DIR]/plugins folder in the root MyPluginProject folder.
6. In the MyPluginProject's build path add external JAR references to all the JAR libraries in the
[OXYGEN_DIR]/lib folder. Now your MyPluginProject should compile successfully.
7. In the Eclipse IDE, create a new Java Application configuration for debugging. Set the Main class box to
ro.sync.exml.Oxygen. Click the Arguments tab and add the following code snippet in the VM arguments
input box, making sure that the path to the plugins directory is the correct one:
-Dcom.oxygenxml.app.descriptor=ro.sync.exml.EditorFrameDescriptor -Xmx1024m
-XX:MaxPermSize=384m -Dcom.oxygenxml.editor.plugins.dir=D:\projects\MyPluginProject
Note: If you need to configure the plugin for , set the com.oxygenxml.app.descriptor to
ro.sync.exml.AuthorFrameDescriptor or ro.sync.exml.DeveloperFrameDescriptor,
respectively.
8. Add a break point in the source of one of your Java classes.
9. Debug the created configuration. When the code reaches your breakpoint, the debug perspective should take over.
Disabling a Plugin
To disable a plugin, use one of the following two methods:
Open the Preferences dialog box, go to Plugins, and deselect the plugin that you want to disable.
Create an empty file called plugin.disable next to the plugin configuration file (plugin.xml). The plugin
will be disabled and will no longer be loaded by the application on startup.
Note: This is useful if you want to temporarily stop work on a plugin and use the application without it.
Author Component
The Author Component was designed as a subset of Oxygen XML Editor that can be integrated into another application
under the terms of the Oxygen XML Editor SDK agreement to provide functionality for editing and authoring XML
documents. The component can be embedded in a third-party standalone Java application or customized as a Java Web
Applet to provide WYSIWYG-like XML editing directly in your web browser.
The Author Component startup project for Java Swing integrations is available online as a Maven archetype on the
Oxygen XML Editor website. More information about the setup can be found on the oXygen SDK page.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 994
Licensing
The licensing terms and conditions for the Author Component are defined in the oXygen SDK License Agreement. To
obtain the licensing terms and conditions and other licensing information as well, you can also contact our support team
at [email protected]. You may also obtain a free of charge evaluation license key for development purposes,
subject to registration. Any deployment of an application developed using the Author Component is also subject to the
terms of the SDK agreement.
There are two main categories of Author Component integrations:
1. Integration for internal use.
You develop an application which embeds the Author Component to be used internally (in your company or by you).
You can buy and use previously purchased Oxygen XML Editor floating licenses to enable the runtime usage of the
Author Component as it was integrated into the application.
2. Integration for external use.
Using the Author Component, you create an application that you distribute to other users outside your company
(with a CMS for example). In this case you need to contact us to apply for a Value Added Reseller (VAR) partnership.
From a technical point of view, the Author Component provides the Java API to:
Inject floating license server details in the Java code. The following link provides details about how to configure a
floating license servlet: http://www.oxygenxml.com/license_server.html#floating_license_servlet.
AuthorComponentFactory.getInstance().init(frameworkZips, optionsZipURL, codeBase, appletID,
//The servlet URL
"http://www.host.com/servlet",
//The HTTP credentials user name
"userName",
//The HTTP credentials password
"password");
Inject the licensing information key (for example the evaluation license key) directly in the component's Java code.
AuthorComponentFactory.getInstance().init(
frameworkZips, optionsZipURL, codeBase, appletID,
//The license key if it is a fixed license.
licenseKey);
Display the license registration dialog box. This is the default behavior if a null license key is set using the API,
this transfers the licensing responsibility to the end-user. The user can license an Author Component using standard
Oxygen XML Editor license keys. The license key will be saved to the local user's disk and on subsequent runs the
user will not be asked anymore.
AuthorComponentFactory.getInstance().init(
frameworkZips, optionsZipURL, codeBase, appletID,
//Null license key, will ask the user.
null);
Installation Requirements
Running the Author Component as a Java applet requires:
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 995
Customization
For a special type of XML, you can create a custom framework (which also works in a standalone version of Oxygen
XML Editor). Oxygen XML Editor already has frameworks for editing DocBook, DITA, TEI, and so on. Their sources
are available in the Oxygen SDK. This custom framework is then packed in a zip archive and used to deploy the component.
The following diagram shows the components of a custom framework.
More than one framework can coexist in the same component and can be used at the same time for editing XML
documents.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 996
You can add on your custom toolbar all actions available in the standalone Oxygen XML Editor application for editing
in the Author mode. You can also add custom actions defined in the framework customized for each XML type.
The Author Component can also provide the Outline, Model, Elements, and Attributes views which can be added to
your own developed containers.
The main entry point for the Author Component Java API is the AuthorComponentFactory class.
Example - Customizing the DITA Framework
If you look inside the bundle-frameworks\oxygen-frameworks folder distributed with the Author Component
sample project, it contains a document type framework folder. Customizations which affect the framework/document
type configuration for the component should first be done in a standalone installation of Oxygen XML Editor.
An Oxygen XML Editor standalone installation comes with a frameworks folder which contains the dita framework
located in [OXYGEN_DIR]\frameworks\dita. The dita framework contains a bundled DITA-OT distribution
which contains the DTDs used for DITA editing. If your DTD specialization is a DITA OT plugin, it should be installed
in the DITA_OT_DIR\plugins folder.
To make changes to the DITA document type configuration, open the Preferences dialog box and go to Document
Type Association. These changes will affect the [OXYGEN_DIR]\frameworks\dita\dita.framework
configuration file.
After you do this you can re-pack the Author Component following the instructions from the README.html file located
in the oxygen-sample-applet project. The Author Component sample project and the Oxygen XML Editor standalone
installation should be of the same version.
Packing a Fixed Set of Options
The Author Component shares a common internal architecture with the standalone application although it does not have
Preferences dialog boxes. However, the Author Component Applet can be configured to use a fixed set of user options
on startup.
The sample project contains a module called bundle-options. The module contains a file called options.xml
in the oxygen-options folder. Such an XML file can be obtained by exporting the options to an XML format from
an installation of Oxygen XML Editor.
To create an options file in the Oxygen XML Editor:
Make sure the options that you want to set are not stored at project level.
Set the values you want to impose as defaults in the Preferences pages.
Select Options > Export Global Options.
Deployment
The Author Component Java API allows you to use it in your Java application or as a Java applet. The JavaDoc for the
API can be found here. The sample project found in the oxygen-sample-applet module comes with Java sources
(ro/sync/ecss/samples/AuthorComponentSample.java) demonstrating how the component is created,
licensed and used in a Java application.
Important: You must obtain the appropriate deployment license (upon payment of a required deployment
license fee) in order to deploy the Author Component along with your application developed with the SDK.
Web Deployment
The Author Component can be deployed as a Java Applet using the new Applet with JNLP Java technology, available
in Oracle (Sun) Java JRE version 1.6 update 10 or newer.
The sample project demonstrates how the Author Component can be distributed as an applet.
Here are the main steps you need to follow in order to deploy the Author Component as a Java Applet:
Follow the instructions here to setup the sample project and look for Java sources of the sample Applet implementation
in the sample project module (oxygen-sample-applet). They can be customized to fit your requirements.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 997
The default.properties configuration file must first be edited to specify your custom certificate information
used to sign the applet libraries. You also have to specify the code base from where the applet will be downloaded.
You can look inside the web-resources/author-component-dita.html and
web-resources/author-component-dita.js sample Web resources to see how the applet is embedded
in the page and how it can be controlled using JavaScript (to set and get XML content from it).
The sample Applet target/jnlp/author-component-dita.jnlp file contains the list of used libraries.
This list is automatically generated from the Maven dependencies of the project.
The sample frameworks and options JAR archives can be found in the bundle-frameworks and
bundle-options modules of the sample project.
Use the Maven command mvn package to pack the component. More information are available here. The resulting
applet distribution is copied in the target/jnlp/ directory. From this on, you can copy the applet files on your
web server.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 998
2. Generate a self-signed certificate.
Invoke the following in a command line terminal:
keytool -selfcert -alias myAlias -keystore keystore.pkcs -storetype PKCS12
4. Edit the default.properties file and fill-in the parameters that hold the path to keystore.pkcs file
(keystore parameter), keystore type (storetype parameter, with JSK or PKCS12 as possible values), alias
(alias parameter) and password (password parameter).
5. The jar files are automatically signed during the package phase of the Maven build.
Supported Browsers and Operating Systems
The applet was tested for compatibility with the following browsers:
IE 7
IE 8
IE 9
IE 10
IE 11
Firefox
Safari
Chrome
Opera
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Windows 7
Passed
Passed
Passed
Passed
Passed
Passed
Windows 8
Passed
Passed
Passed
Passed
Passed
OS X
(10.6 10.9)
Passed
Passed
Failed
Passed
Linux
Ubuntu 10
Passed
Failed
Passed
Vista
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 999
3. Remove the Java Webstart cache from the local drive and try again.
4. Remove the Author Component framework cache from the local drive and try again:
5. Problems sometimes occur after upgrading the web browser and/or the JavaTM runtime. Redeploy the applet on the
server by running Ant in your Author Component project. However, doing this does not always fix the problem,
which often lies in the web browser and/or in the Java plug-in itself.
6. Sometimes when the HTTP connection is slow on first time uses the JVM would simply shut down while the jars
were being pushed to the local cache (for example, first time uses). This shut down typically occurs while handling
oxygen.jar. One of the reasons could be that some browsers (Firefox for example) implement some form of
"Plugin hang detector" See
https://developer.mozilla.org/en/Plugins/Out_of_process_plugins/The_plugin_hang_detector.
7. If you are running the Applet using Safari on OS X and it has problems writing to disk or fails to start, do the
following:
In Safari, go to Safari->Preferences->Security.
Select Manage Website Settings.
Then select Java and for the oxygenxml.com entry, choose the Run in Unsafe mode option.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 1000
URLConnection connection = new HttpURLConnection(u, null);
if(!u.toString().endsWith(".jar")) {
//Do not cache HTTP resources other than JARS
//By default the Java HTTP connection caches content for
//all URLs so if one URL is modified and then re-loaded in the
//applet the applet will show the old content.
connection.setDefaultUseCaches(false);
}
return connection;
}
};
}
return null;
}
});
To edit specialized DITA Composite with MathML content, include the entire MathML2 framework directory
([OXYGEN_DIR]/frameworks/mathml2) in the frameworks bundled with the component in the
bundle-frameworks module. This directory is used to solve references to MathML DTDs.
Adding MathML support using MathFlow
In the pom.xml file add dependencies to the additional libraries used by the MathFlow library to parse MathML
equations:
1.
2.
3.
4.
5.
MFComposer.jar
MFExtraSymFonts.jar
MFSimpleEditor.jar
MFStructureEditor.jar
MFStyleEditor.jar
You can reference these additional libraries from the MathFlow SDK as in the example below:
<dependency>
<groupId>com.dessci</groupId>
<artifactId>MFComposer</artifactId>
<version>1.0.0</version>
<scope>system</scope>
<systemPath>${MathFlowSDKDir}/lib/MFComposer.jar</systemPath>
</dependency>
In addition, you must obtain fixed MathFlow license keys for editing and composing MathML equations and register
them using these API methods: AuthorComponentFactory.setMathFlowFixedLicenseKeyForEditor
and AuthorComponentFactory.setMathFlowFixedLicenseKeyForComposer.
To edit specialized DITA Composite with MathML content, include the entire
[OXYGEN_DIR]/frameworks/mathml2 Mathml2 framework directory in the frameworks bundled with the
component in the bundle-frameworks module. This directory is used to solve references to MathML DTDs.
More documentation is available on the Design Science MathFlow website.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 1001
Adding Support to Insert References from a WebDAV Repository
Predefined actions that insert references, such as the Insert Image action, display a URL chooser that allows you to
select the Browse Data Source Explorer action. To use an already configured WebDAV connection in the Author
Component, follow these steps:
1. Open a standalone Oxygen XML Editor 17.1 and configure a WebDAV connection.
2. Pack the fixed set of options from the standalone to use them with the Author Component project.
3. In the Author Component, the defined connection still does not work when expanded because the additional JAR
libraries used to browse the WebDAV repository are missing. By default, the httpclient dependency of the oXygen
SDK artifact is excluded. You can enable it by commenting the following lines:
<exclusion>
<artifactId>httpclient</artifactId>
<groupId>org.apache.httpcomponents</groupId>
</exclusion>
If you want to have a different WebDAV connection URL, user name and password depending on the user who has
started the component, you have a more flexible approach using the API:
//DBConnectionInfo(String id, String driverName, String url, String user, String passwd, String host, String
port)
DBConnectionInfo info = new DBConnectionInfo("WEBDAV", "WebDAV FTP", "http://host/webdav-user-root", "userName",
"password", null, null);
AuthorComponentFactory.getInstance().setObjectProperty("database.stored.sessions1", new DBConnectionInfo[]
{info});
The bundle-plugins module must contain the additional plugin directories in the dropins subdirectory. The
content must also contain a plugin.dtd file. Copy the plugin.dtd file from an [OXYGEN_DIR]\plugins
folder.
In the class which instantiates the AuthorComponentFactory, for example the
ro.sync.ecss.samples.AuthorComponentSample class, call the methods
AuthorComponentFactory.getPluginToolbarCustomizers(),
AuthorComponentFactory.getPluginViewCustomizers() and
AuthorComponentFactory.getMenubarCustomizers(), obtain the customizers which have been added
by the plugins and call them to obtain the custom swing components that they contribute. There is a commented-out
example for this in the AuthorComponentSample.reconfigureActionsToolbar() method for adding
the toolbar from the Acrolinx plugin.
Important: As the Author Component is just a subset of the entire application, there is no guarantee that all
the functionality of the plugin works.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 1002
Microsoft SharePoint
Microsoft SharePoint is a Web application platform developed by Microsoft.
SharePoint comprises a multipurpose set of Web technologies backed by a common technical infrastructure. It provides
the benefit of a central location for storing and collaborating on documents, which can significantly reduce emails and
duplicated work in an organization. It is also capable of keeping track of the different versions created by different users.
Why Integrate the Author Component with SharePoint
The Author Component can be embedded in a SharePoint site as a Java applet. This is a simple and convenient way for
you to retrieve, open, and save XML and XML related documents stored on your company's SharePoint server, directly
from your web browser.
For example, suppose that you are working on a team project that uses the DITA framework for writing product
documentation. You have the DITA maps and topics stored on a SharePoint repository. By using a custom defined action
from the contextual menu of a document, you can easily open it in the Author Component applet that is embedded in
your SharePoint Documents page.
You can embed the applet either on a site that is located on a standalone SharePoint server, or on your company Microsoft
Office 365 account.
This example can be used as a starting point for other CMS integrations.
Deploying Resources
You are able to embed the Author Component in a SharePoint site as a Java Applet, using the new Applet with JNLP
Java technology. Sign with a valid certificate the JNLP file and the associated JAR files that the applet needs.
Deploy these resources on a third party server (other than the SharePoint server). The Java applet downloads the resources
as needed. If you deploy the JNLP and JAR files on the SharePoint server, the Java Runtime Environment will not be
able to access the applet resources because it is not aware of the current authentication tokens from your browser. This
causes the Java Class Loader to fail loading classes, making the applet unable to start.
Accessing Documents
One of the main challenges when integrating the Author Component applet in your SharePoint site is to avoid
authenticating twice when opening a document resource stored in your SharePoint repository.
You have already signed in when you started the SharePoint session, but the applet is not aware of your current session.
In this case every time the applet is accessing a document it will ask you to input your credentials again.
As a possible solution, do not execute HTTP requests directly from the Java code, but forward them to the web browser
that hosts the applet, because it is aware of the current user session (authentication cookies).
To open documents stored on your SharePoint repository, register your own protocol handler to the JVM. We implemented
a handler for both http and https protocols that forwards the HTTP requests to a JavaScript XMLHttpRequest object.
This way, the browser that executes the JavaScript code is responsible for handling the authentication to the SharePoint
site.
To install this handler, add the following line to your Java Applet code (in our case, in the
ro.sync.ecss.samples.AuthorComponentSampleApplet class):
URL.setURLStreamHandlerFactory(new ro.sync.net.protocol.http.handlers.CustomURLStreamHandlerFactory(this));
To enable JavaScript calls from your Java applet code, set the MAYSCRIPT attribute to true in the <applet> element
embedded in you HTML page:
<applet width="100%" height="600"
code="ro.sync.ecss.samples.AuthorComponentSampleApplet"
name="authorComponentAppletName" id="authorComponentApplet"
MAYSCRIPT="true">
.....
</applet>
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 1003
Tip: If the applet is not working, or you cannot open documents from your SharePoint repository, enable the
debugging tools that come bundled with your Web Browser or the Java Console from your operating system to
try to identify the cause of the problem.
Integrating the Author Component
To integrate the Author Component as a Java applet with your SharePoint site, you need the Author Component start-up
project.
The project is available as a Maven archetype online. More information about the setup can be found here.
An online demo applet is deployed at
http://www.oxygenxml.com/demo/AuthorDemoApplet/author-component-dita-requirements.html.
Customize Your Applet
Follow these steps to customize the Author Component Java applet:
1. Follow this set of instructions to setup the sample project and look for the Java sources (these can be customized to
fit your requirements) of the sample applet implementation;
Note: The Java source files are located in the src folder of the oxygen-sample-applet module.
2. Look inside web-resources/sharepoint/author-component-dita.aspx and the associated *.js
resources, to see how the applet is embedded in the page and how it can be controlled using JavaScript (to set and
get XML content from it).
3. Edit the default.properties configuration to specify your custom certificate information, used to sign the
applet libraries. Also, specify the code base from where the applet resources will be downloaded.
4. The sample Applet target/jnlp/author-component-dita.jnlp file contains the list of used libraries.
This list is automatically generated from the Maven dependencies of the project. The sample frameworks and options
JAR archives are located in the bundle-frameworks and bundle-options modules of the sample project.
Note: The JNLP file and the associated resources and libraries must be deployed on a non-SharePoint web
server, otherwise the applet will not be loaded.
5. Use the Maven command mvn package to pack the component. More information are available here. The resulting
applet distribution is copied in the target/jnlp/ directory. From now on, you can copy the applet files on your
web server.
Add Resources to Your SharePoint Site
Copy the following resources to a sub-folder (in our example named author-component) of the SitePages folder
from your SharePoint site, where you want to embed the applet:
1. author-component-dita.aspx - an HTML document containing the Java applet.
Note: It has an .aspx extension instead of .html. If you use the latter extension, the browser will download
the HTML document instead of displaying it.
Note: Edit the .aspx file and change the value of the applet parameter jnlp_href to the URL of the deployed
author-component-dita.jnlp. Keep in mind that the JNLP file should be deployed on a third party
server. For example:
<applet>
<param name="jnlp_href"
value="http://www.oxygenxml.com/demo/AuthorDemoApplet/author-component-dita.jnlp"/>
..........
</applet>
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 1004
4. connectionUtil.js - contains JavaScript utility methods.
Note: Replace the value of the SPRootSiteURL property with the URL of your SharePoint root site, without
trailing '/'. This is used by the openListItemInAuthor(itemUrl) method, to compute the absolute
URL of the list item that is to be opened in the applet.
Copy Resources Using Oxygen XML Editor
You can use Oxygen XML Editor to copy your resources to the SharePoint server:
1. Configure a new connection to your SharePoint site in the Data Source Explorer View.
Note: To watch our video demonstration about connecting to repository located on a SharePoint server, go
to http://www.oxygenxml.com/demo/SharePoint_Support.html.
2. Browse your new SharePoint connection site and select the SitePages folder.
3. Create a folder named author-component using the New Folder contextual menu action.
4. Upload your resources to this folder using the Import Files contextual menu action.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 1005
Note: It is recommended that you deselect the Enable Java content in the browser option from the Java
Control Panel until you finish editing the page. Otherwise, the browser will load the applet for every change
that you will make.
Edit the page directly in your browser, following these steps:
1. Go to the home page of your SharePoint site where you want to add the Author Component Java applet.
2. Select the Page tab from the ribbon located at top of the page and click the Edit button.
3. Select the Insert tab and click Web Part.
4. In the Categories panel, select Media and Content.
5. In the Parts panel, select the Script Editor Web Part.
6. Click the Add button to insert the selected Web Part to your page content.
7. Select the newly added Web Part.
8. Select the Web Part tab and click the Web Part Properties button.
9. Click the Edit Snippet link under your Web Part.
10. Insert the following HTML snippet to your newly created Web Part:
<div>
<iframe
id="appletIFrame"
src="/applet/SitePages/author-component/author-component-dita.aspx"
width="800px" height="850px">
</iframe>
<script type="text/JavaScript">
function openInAuthor(itemUrl) {
var appletFrame = document.getElementById("appletIFrame");
var appletWin = appletFrame.contentWindow;
appletWin.openListItemInAuthor(itemUrl);
}
</script>
</div>
The above HTML fragment contains an IFrame that points to the page where the Java applet resides. Replace the
value of the src attribute with the path of the author-component-dita.aspx HTML page that you added
earlier to the SitePages folder;
Note: Use the iframe element from the HTML fragment with the expanded form (<iframe></iframe>).
Otherwise, the Web Part will not display the target page of the frame.
11. Save the changes you made to the page.
Note: Do not forget to select the Enable Java content in the browser, to allow the browser to load the
Java applet.
Create a SharePoint Custom Action
To open a document from your SharePoint repository in the Author Component applet, add a new custom action to the
contextual menu of your Documents Library:
1.
2.
3.
4.
5.
6.
7.
Note: This translates to a call to the openInAuthor(itemUrl) JavaScript function defined in the
HTML fragment that was embedded in the Script Editor Web Part. The {ItemUrl} parameter will be
expanded to the URL of the list item that the action is invoked on.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 1006
8. Click the OK button to save the action.
The Result
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 1007
Framework files are downloaded on the first load of the applet. Subsequent loads will re-use the cached customization
files and will be much faster.
6. For on-line demo
(http://www.oxygenxml.com/demo/AuthorDemoApplet/author-component-dita.html),
noted a significant wait during initial startup. Any other mechanisms to enhance startup time?
See the explanation above.
7. Does the Author Component support multiple documents being open simultaneously? What are the licensing
ramifications?
A single AuthorComponentFactory instance can create multiple EditorComponentProvider editors
which can then be added and managed by the developer who is customizing the component in a Swing JTabbedPane.
A single license (floating or user-based) is enough for this.
If you need to run multiple Java Applets or distinct Java processes using the Author Component, the current floating
license model allows for now only two concurrent components from the same computer when using the license
servlet. An additional started component will take an extra license seat.
8. Is there any internet traffic during an editing session (user actively working on the content, on the client side, in the
Author Component)?
No.
Functionality
1. How and when are saves performed back to the hosting server?
What you can see on our web site is just an example of the Author Component (which is a Java Swing component)
used in an Applet.
This applet is just for demonstration purposes. It's source can be at most a starting point for a customization. You
should implement, sign and deploy your custom applet implementation.
The save operation could be implemented either in JavaScript by requesting the XML content from the Applet or in
Java directly working with the Author Component. You would be responsible to send the content back to the CMS.
2. Is there a particular XML document size (or range) when the applet would start to exhibit performance problems?
The applet has a total amount of used memory specified in the JNLP JavaWebstart configuration file which can be
increased if necessary. By default it is 156 Mb. It should work comfortably with documents of 1-3 megabytes.
3. What graphic formats can be directly rendered in the Author Component?
GIF, JPEG, PNG, BMP and SVG.
4. Can links be embedded to retrieve (from the server) and "play" other types of digital assets, such as audio or video
files?
You could add listeners to intercept clicks and open the clicked links. This would require a good knowledge of the
oXygen SDK. The Author Component can only render static images (no GIF animations).
5. Does the Author Component provide methods for uploading ancillary files (new graphics, for instance) to the hosting
server?
No.
6. Does the Author Component provide any type of autosave functionality?
By default no but you could customize the applet that contains the Author Component to save its content periodically
to a file on disk.
7. Assuming multiple documents can be edited simultaneously, can content be copied, cut and pasted from one Author
Component "instance" to another?
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 1008
Yes.
8. Does the Author Component support pasting content from external sources (such as a web page or a Microsoft Word
document and, if so, to what extent?
If no customizations are available the content is pasted as simple text. We provide customizations for the major
frameworks (DITA, DocBook, TEI, etc.) which use a conversion XSLT stylesheet to convert HTML content from
clipboard to the target XML.
9. Can UTF-8 characters (such as Greeks, mathematical symbols, etc.) be inserted and rendered?
Any UTF-8 character can be inserted and rendered provided that the font used for editing supports rendering the
characters. The font can be changed by the developers but not by the users. When using a logical font (which by
default is Serif for the Author Component) the JVM will know how to map all characters to glyphs. There is no
character map available but you could implement one
Customization
1. Please describe, in very general terms, the menus, toolbars, contextual menu options, helper panes, and so on, that
are available for the Author Component out-of-the box.
You can mount on your custom toolbar all actions available in the standalone Oxygen XML Editor application for
editing in the Author mode. This includes custom actions defined in the framework customized for each XML type.
The Author Component also can provide the Outline, Model, Elements, and Attributes views which can be added
to your own panels (see sample applet).
2. Please describe, in general terms, the actions, project resources (for example, DTD/Schema for validation purposes,
CSS/XSL for styling, etc.) and typical level of effort that would be required to deploy a Author Component solution
for a customer with a proprietary DTD.
The Author mode internal engine uses CSS to render XML.
For a special type of XML you can create a custom framework (which also works in an Oxygen XML Editor
standalone version) which would also contain default schemas and custom actions. A simple framework would
probably need 2-3 weeks development time. For a complex framework with many custom actions it could take a
couple of months. Oxygen XML Editor already has frameworks for editing (DocBook, DITA, TEI, etc.) Sources for
them are available in the Oxygen SDK.
More than one framework can coexist in the same Oxygen XML Editor instance (the desktop standalone version or
the applet version) and can be used at the same time for editing XML documents.
3. Many customers desire a very simplistic interface for contributors (with little or no XML expertise) but a more robust
XML editing environment for editors (or other users with more advanced XML expertise). How well does the Author
Component support varying degrees of user interface complexity and capability?
Forcing behaviors (for example, ensuring change tracking is on and preventing it from being shut down)
You could avoid placing the change tracking toolbar actions in the custom applet. You could also use API to turn
change tracking ON when the content has been loaded.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 1009
Using our API you can customize what the Outline or Breadcrumb presents for each XML tag. You can also
customize the in-place content completion list.
Presenting a small subset of the overall XML tag set (rather than the full tag set) for use by contributors (for
example, allowing an author to only insert Heading, Para and inline emphasis) Could varying "interfaces", with
different mixes these capabilities and customizations, be developed and pushed to the user based on a "role" or
a similar construct?
The API allows for a content completion filter which also affects the Elements view.
4. Does the Author Component API provide access to the XML document, for manipulation purposes, using common
XML syntax (such as DOM, XPath, etc.)?
Yes, using the Author Component API.
5. Can custom dialog boxes be developed and launched to collect information in a "form" (with scripting behind to
push tag the collection information and embed it in the XML document?
Yes.
6. Can project resources, customizations, etc. be readily shared between the desktop and component versions of your
Author Component product line?
A framework developed for the desktop version of the Oxygen XML Editor application can then be bundled with
the Author Component in a custom applet. For example, the demo applet from our web site is DITA-aware using
the same framework as the Oxygen XML Editor standalone distribution.
A custom version of the applet that includes one or more customized frameworks and user options can be built and
deployed for non-technical authors by a technical savvy user using a built-in tool of Oxygen XML Editor. All the
authors that load the deployed applet from the same server location will share the same frameworks and options.
A custom editing solution can deploy one or more frameworks that can be used at the same time.
Author Component
Intended audience
No.
Compatibility with the standard version Covers only editing and reviewing
of Oxygen XML Editor
features.
100%
No.
Yes.
Client-side setup
None.
Server-side setup
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 1010
WebApp Component
This section describes the various ways that you can customize the WebApp Component, and how to deploy it.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 1011
A Graphical Description of the WebApp Component System
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 1012
The following is a list of options and their accepted values:
Option name
Value
Description
com.oxygenxml.loadBuiltinProtocolHandlers
true/false
com.oxygenxml.webapp.datastore.docs.memory.size An integer
number.
com.oxygenxml.webapp.datastore.docs.disk.size An integer
number.
(*) - Duration is represented by an integer, followed by one of "d", "h", "m", or "s", representing days, hours, minutes,
or seconds, respectively.
Here is an example of how to configure a context parameter:
<context-param>
<param-name>com.oxygenxml.loadBuiltinProtocolHandlers</param-name>
<param-value>false</param-value>
</context-param>
Easier development and testing, since you can test most of the functionality in the standalone version of Oxygen
XML Editor using advanced tools such as the CSS Inspector, CSS Editor, or the Document Type Association
customization dialog box.
Uniform experience across multiple Oxygen XML Editor distributions.
Ability to reuse previously developed frameworks.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 1013
Deploying a Framework
1. Copy your customized framework into the bundle-frameworks/oxygen-frameworks/ folder of the oXygen
XML SDK project.
2. Build the SDK project and deploy it.
Customization Tips
If you want to use CSS rules that only apply when the framework is used in the WebApp Component, use the
following media query:
@media oxygen AND (platform:webapp) {
...
}
In the web folder of each framework, you can add a framework.js file that calls the JavaScript API to implement
custom editing actions. The possible use cases include the following:
Create custom actions and add them to the toolbar or contextual menu. For more details, see the JS custom action
tutorial.
Create custom form controls. For more details, see the JS form control tutorial.
Add additional views. For more details, see the JS custom view tutorial.
The WebApp Component continuously validates the XML documents using the default validation scenarios defined
at framework level. Only the validation units that have the Automatic Validation option selected in the Document
Type Association customization dialog box will be used (this option is set in the Edit Scenario dialog box that is
accessed by editing a scenario in the Validation subtab when editing a document type).
The + (direct adjacent) and > (child selector) structural selectors cannot be used to match table-related elements.
Oxygen XML Editor CSS extensions are ignored on print media. If an Oxygen XML Editor CSS extension is
used on the screen media, it will also be used on the print media.
Oxygen XML Editor CSS extension properties and functions cannot be used in a rule that has a :hover pseudo-class
in the selector. The attr function is also not supported in such a rule due to a lack of browser support.
The :hover pseudo-class is only available for mouse-enabled platforms.
Oxygen XML Editor CSS extensions used in property values that express lengths may not behave as expected.
Nevertheless, it is a good approximation.
Oxygen XML Editor synthetic DOM nodes comment, reference, cdata, pi, and error interfere with the +
(direct adjacent) structural selector. For example:
b + b {
color: red;
}
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 1014
The WebApp Component does not render non-table-row children elements of tables and non-table-cell
elements of table-row elements.
A width or height property set on any element other than the root XML element may cause some resize handles,
that cannot be disabled, to be displayed in IE11. This is also true for elements that have a position property with
a value of absolute or fixed. For more information about this issue, see this Microsoft Connect article.
The WebApp Component does not support the following:
Editor variables related with functionality that is not available in the WebApp Component, such as ${dbgXML} or
${dbgXSL}.
Editor variables related with Oxygen XML Editor project location, such as ${pdu}, ${pd}, or ${pn}.
Any editor variable that displays Java Swing-based components, such as ${ask}.
Editor variables related with the Oxygen XML Editor standalone installation directory, such as ${oxygenHome} or
${oxygenInstallDir}.
URLStreamHandler - This extensions can be used to integrate the WebApp Component with XML databases or
CMS. There is an example URLStreamHandler provided in oXygen XML SDK project in the
oxygen-sample-plugins/oxygen-sample-plugin-custom-protocol folder. The extension uses
the cproto protocol to access the file system of the server and can be used as a starting point.
Note: For more details about implementing an authentication mechanism, see the How To Make WebApp
Component Use the CMS Authentication Mechanism on page 1017 topic.
WorkspaceAccess - Most of the methods used to configure the Oxygen XML Editor GUI are unavailable in theses
extensions, but they can still be used, for example, to configure a javax.xml.transform.URIResolver.
Note: The ro.sync.exml.workspace.api.PluginWorkspace instance passed to the extension
also implements the
ro.sync.ecss.extensions.api.webapp.access.WebappPluginWorkspace interface and
provides access to some WebApp Component-specific functionality.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 1015
the plugin. An example of a use-case is you can use it to have the WebApp Component provide icons for
plugin-specific actions.
In the following example, the static resources will be available at
[OXYGEN-WEBAPP]/plugin-resources/relative-href/path-to-file, with the path-to-file
being relative to the static resources folder:
<extension type="WebappStaticResourcesFolder" path="path-to-resorce-folder" href="relative-href"/>
Note: The parameter values are percent encoded before being added to the editing
URL.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 1016
To add new actions to the action manager.
To change the startup options for the editor. For example, you can choose whether to only load the Review mode
editing actions or to enable full editing support (Edit mode editing actions).
Note: This example will provide browsing capabilities on your local file system. More complex connectors
can be implemented using our Java and JavaScript API. Also, to see information for a more complex example,
you can also look at our Oxygen XML WebApp storage services integration project that is hosted on GitHub.
3. Deploy the plugin in the Oxygen XML WebApp.
The registered create action will appear in the New section on your Dashboard, while a registered open action will
appear in the Open section.
Create a New Document
To create a new document, follow these steps:
1. Go to your Oxygen XML WebApp Dashboard page.
2. Click the New Document action in the New section. This opens a dialog box that allows you to select a new file
template.
3. Select a file template click OK. This opens a dialog box that allows you browse for a destination path.
4. Select a destination path and name for the new document.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 1017
The new document will be opened in a new tab.
Open a Document
To open a document, follow these steps:
1. Go to your Oxygen XML WebApp Dashboard page.
2. Click the Open Document action in the Open section. This opens a dialog box that allows you to browse for a file.
3. Select the file and click OK.
The selected document will be opened in a new tab.
How To Share a Tomcat Instance Between WebApp Component and Another Application
If you want to share a Tomcat instance between WebApp Component and another web application, the following issues
need to be considered:
Oxygen XML Editor reads and sets system properties, and while we try to namespace those that are specific to
Oxygen XML Editor, there is no guarantee that there will not be any clashes with those set by other applications.
You have to adapt the JVM's memory configuration to the scenario where there will be more applications competing
for the same pool of memory.
The WebApp Component currently does not restart (or reload in Apache Tomcat terminology) correctly unless the
Servlet Container is also restarted.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 1018
2. On the client-side, register the sync.api.FileBrowsingDialog widget as a UrlChooser using the following code snippet:
workspace.setUrlChooser(new sync.api.FileBrowsingDialog());
5. You can now open a document in Oxygen XML Editor standalone and start the WebApp Component with the plugin
installed, just by using the Start WebApp Editor button on the Oxygen XML Editor standalone toolbar.
Every time you make changes to the plugin sources, you will need to restart the WebApp Component using the Close
and Stop Server button.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 1019
Once you are happy with the result, you need to add the plugin back in your SDK project and follow these instructions
to perform a final testing of the project.
Software Requirements
On the server side, the following applications are supported:
Apache Tomcat 7 or 8.
Java Virtual Machine 1.7 or newer (if started in security mode, Java 1.8 is required).
Other Notes
All WebApp Component configuration files are stored in a single folder that can be shared amongst multiple servers
in a distributed deployment. It can also be reused when you update the server to a new version. The location of this
folder is defined by the oxygen.data.dir system property. If not set, a folder that is private to the application
is used.
Note: If the WebApp Component is started in security mode, you must set the oxygen.data.dir system
property.
It is recommended that you install the WebApp Component in its own instance of Tomcat, without sharing it with
other applications.
If you need to reload the application, you need to restart the server.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 1020
You should see a message that informs you that the license configuration was successfully applied.
How to Add and Configure Plugins
Add a New Plugin
To add a new plugin to the WebApp Component, follow these steps:
1.
2.
3.
4.
5.
Configure a Plugin
If the plugin can be configured, a
icon and follow the instructions.
Configure icon is displayed next to its name. To configure the plugin, click the
To create a configuration page for a plugin that does not already have the
steps:
1. Register a WebappServlet extension type with a role attribute set to config in your plugin.xml file:
<extension type="WebappServlet" role="config"
class="com.oxygenxml.sdksamples.github.GithubPluginConfigExtension"/>
The class attribute value should point to an extension of the PluginConfigExtension class.
2. When extending the PluginConfigExtension class, consider the following notes:
Implement the getOptionsForm method to return an HTML of your configuration page that contains user
inputs or buttons so that your plugin and JavaScript communicates with the PluginConfigExtensions
HTTP API.
Implement the getOptionsJson method to return a JSON string of the current options for a plugin. (The
JSON should only contain key values, where values is of the type string|number|boolean with no arrays
or other objects).
Implement the getPath method to return a non-empty string that represents the path for which this extension
will be served.
For example:
{webapp-context}/plugins-dispatcher/RESULT_OF_GETPATH
If you need to override the init method, make sure you call super.init(). Otherwise, options will not be
saved to disk and will be lost when you restart the application.
If you need to override any of the doPut/doDelete methods, make sure you call the saveOptions method
at the end to save the options to disk.
If you need to override the doGet method, make sure it responds with the result of getOptionsForm for
header Accept=text/html, and with the result of getOptionsJson when called with header
Accept=application/json. Use the getOption or getDefaultOptions methods to access the
current or default options.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 1021
Tip: For an implementation example, you can look at
com.oxygenxml.sdksamples.github.GithubPluginConfigExtension in the
oxygen-sdk-samples project.
3. The getOptionsForm method should return an HTML page with necessary logic to call the doMethods of the
PluginConfigExtension class. The options page should have some JavaScript code that listens for message
events and responds to the 'apply' and 'restoreDefaults' actions by calling the doPutand doDelete
methods respectively, as in the following example:
window.addEventListener('message', function (event) {
var action = event.data.action;
var origin = event.origin;
switch (action) {
case 'apply':
// call the doPut method of your PluginConfigExtension here using an XMLHttpRequest
// and send the required options taken from the inputs you sent with the getOptionsForm method.
var xhr = new XMLHttpRequest();
xhr.open("PUT", "../plugins-dispatcher/RESULT_OF_GETPATH");
// after receiving the response send it back to the sender of the message with a done property
// set to true if the action completed successfully or false otherwise. And send a message for
// the user as well. Also, make sure to set the origin to the event.origin otherwise the message
// will be ignored
event.source.postMessage({done: true, message: 'Options set succesfully for plugin X.'}, origin);
break;
case 'restoreDefaults':
// call the doDelete method of you PluginConfigExtension here using an XMLHttpRequest
// after receiving the response send it back to the sender of the message with a done property set
// to true if the action completed successfully or false otherwise. And send a message for the user
// as well. Also, make sure to set the origin to the event.origin otherwise the message will be ignored
event.source.postMessage({done: true, message: 'Options reset successfully for plugin X.'}, origin);
break;
}
Delete a Plugin
To delete a plugin from your WebApp Component, follow these steps:
1. Go to your Administration Page.
2. Select Plugins.
3. Find the plugin you want to delete and click the
4. Restart the server to apply the changes.
Delete a Framework
To delete a framework from your WebApp Component, follow these steps:
1. Go to your Administration Page.
2. Select Frameworks.
3. Find the framework you want to delete and click the
4. Restart the server to apply the changes.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 1022
Licensing the WebApp Component
The WebApp Component uses a floating license model, where the license key is stored on a server and individual users
consume license seats from a common pool.
How it works
The license key contains the maximum number of users that can simultaneously access the WebApp Component at any
given moment. After a period of inactivity, the license allocated to that user becomes available.
While no personal information is sent to the server, a cookie that identifies the user is auto-generated. Note that the use
of two different browsers (for example, Firefox and Chrome) by a single user, will consume two floating licenses.
However, using two or more windows or tabs of the same browser, consumes a single floating license.
Licensing
Follow these steps to license a deployment of the WebApp Component:
1. To obtain a license key, please contact [email protected].
2. Install a floating license server. If you decide to use an HTTP license server, you can deploy it in the same Tomcat
server, alongside with the WebApp Component.
3. Configure the license server connection.
Note: Information about your license will be displayed in the About section of the WebApp Component
Dashboard.
Configuring the License Server Connection (for oXygen License Server Servlet version only)
For information on configuring the license server connection with a simple GUI, see the How to Configure the License
Server Connection on page 1019 topic.
Bundling the License Server Configuration in the WebApp Component
If you need to build the WebApp Component with the license configuration bundled inside, use this method.
The connection to the server should be configured in a file located at WEB-INF/license.properties. It should
have the following keys:
licensing.server.type
Type of licensing server. Can be one of http or standalone.
licensing.server.url
The URL of the license server.
licensing.server.user
The user name used for the license server.
licensing.server.password
The password used for the license server.
licensing.server.host
The host name of the licensing standalone server.
licensing.server.port
The port of the licensing standalone server.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 1023
A configuration file might look like this:
licensing.server.type=http
licensing.server.url=http://example.com:8080/oxygenLicenseServlet/license-servlet
licensing.server.user=admin
licensing.server.password=******
It is a good security practice to allow a component to access only the information and resources that are necessary for
its purpose. In an environment that uses Apache Tomcat, you can enforce these rules following these steps:
Note: In the previous example, in the first line, replace oxygen-webapp with the name of your deployment
of the WebApp Component.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 1024
Edit the catalina.policy file and add a line such as:
permission java.io.FilePermission "path/to/yourSecretDir/-", "read,write,delete";
permission java.io.FilePermission "path/to/yourSecretDir", "read,write,delete";
Use the following system property when starting the Tomcat server:
-Dfile.protocol.blacklist=/path/to/yourSecretDir
Note: Use the value of path.separator system property to separate more directories. For example,
under Linux, the value of path.separator property is a colon punctuation character :.
Supported Plugin Integrations
By default, the WebApp Component comes bundled with the following plugin integrations:
GitHub
WebDAV
Note: You can also use the Administration Page to set the Client ID and Client Secret without creating the
github-plugin.properties file.
4. Restart the WebApp Component.
You now have access to the Login with GitHub button in the GitHub login dialog box.
Oxygen XML Editor | Extending Oxygen XML Editor Using the SDK | 1025
WebApp Component
Author Component
Intended audience
No.
Compatibility with the standard version Covers only editing and reviewing
of Oxygen XML Editor
features.
100%
No.
Yes.
Client-side setup
None.
Server-side setup
Chapter
19
Tools
Topics:
SVN Client
Tree Editor
Comparing and Merging
Documents
XML Digital Signatures
Large File Viewer
Hex Viewer
The Standalone SVG Viewer
Integrating External Tools
Oxygen XML Editor includes a variety of helpful tools to help you accomplish
XML-related tasks. This section presents many of those tools.
SVN Client
The Syncro SVN Client is a client application for the Apache Subversion version control system, compatible with
Subversion 1.6, 1.7 and 1.8 servers. It manages files and directories that change over time and are stored in a central
repository. The version control repository is much like an ordinary file server, except that it remembers every change
ever made to your files and directories. This allows you to access older versions of your files and examine the history
of how and when your data changed.
To start Syncro SVN Client, go to Tools > SVN Client.
Main Window
This section explains the main window of Syncro SVN Client.
Views
The main window consists of the following views:
Repositories view - Allows you to define and manage Apache Subversion repository locations.
Working Copy view - Allows you to manage with ease the content of the working copy.
History view - Displays information (author name, revision number, commit message) about the changes made to a
resource during a specified period of time.
Editor view - Allows you to edit different types of text files, with full syntax-highlight.
Annotations view - Displays a list with information regarding the structure of a document (author and revision for
each line of text).
Compare view - Displays the differences between two revisions of a text file from the working copy.
Image Preview - Allows you to preview standard image files supported by Syncro SVN Client: JPG, GIF and PNG.
Compare Images view - Displays two images side by side.
Properties view - Displays the SVN properties of a resource under version control.
Console view - Displays information about the currently running operation, similar with the output of the Subversion
command line client.
Help view - Shows information about the currently selected view.
The main window's status bar presents in the left side the operation in progress or the final result of the last performed
action. In the right side there is a progress bar for the running operation and a stop button to cancel the operation.
SVN Main Menu
The main menu of the Syncro SVN Client is composed of the following menus:
File Menu
New submenu:
New File
This operation creates a new file as a child of the selected folder from the Repositories view tree or the Working
Copy view tree, depending on the view that was last used. Note that for the Working Copy view, the file is added
to version control only if the selected folder is under version control.
New Folder(Ctrl (Command on OS X) + Shift + F)
This operation creates a new folder as a child of the selected folder from the Repositories view tree or the Working
Copy view tree, depending on the view that was last used. Note that for the Working Copy view, the file is added
to version control only if the selected folder is under version control.
New External Folder (Ctrl (Command on OS X) + Shift + W)
This operation allows you to add a new external definition on the selected folder. An external definition is a
mapping of a local directory to a URL of a versioned directory, and ideally a particular revision, stored in the
svn:externals property of the selected folder.
../ - Relative to the URL of the directory on which the svn:externals property is set.
^/ - Relative to the root of the repository in which the svn:externals property is versioned.
// - Relative to the scheme of the URL of the directory on which the svn:externals property is set.
/ - Relative to the root URL of the server in which the svn:externals property is versioned.
Important: To change the target URL of an external definition, or to delete an external item, do the
following:
1. Modify or delete the item definition found in the svn:externals property that is set on the
parent folder.
2. For the change to take effect, use the Update operation on the parent folder of the external item.
Note: Syncro SVN Client does not support definitions of local relative external items.
Scan for locks (Ctrl (Command on OS X) + L) - Contacts the repository and recursively obtains the list of
locks for the selected resources. A dialog box containing the locked files and the lock description will be displayed.
This is only active for resources under version control. For more details see Scanning for locks.
Lock (Ctrl (Command on OS X) + K) - Allows you to lock certain files that need exclusive access. You
can write a comment describing the reason for the lock and you can also force (steal) the lock. This action is
active only on files under version control. For more details on the use of this action see Locking a file.
Unlock (Ctrl (Command on OS X) + Alt + K) - Releases the exclusive access to a file from the repository.
You can also choose to unlock it by force (break the lock).
All Files,
Modified,
Incoming,
Outgoing, or
Refresh (F5)
Refreshes the state of the selected resources or of the entire working copy (if there is no selection).
Edit 'config' file - In this file you can configure various SVN client-side behaviors.
Edit 'servers' file - In this file you can configure various server-specific protocol parameters, including HTTP
proxy information and HTTP timeout settings.
Export Options
Allows you to export the current options to an XML file.
Import Options
Allows you to import options you have previously exported.
Reset Options
Resets all your options to the default ones.
Check out
Checks out a working copy from a repository. The repository URL and the working copy format must be specified.
Synchronize
Synchronizes the current working copy with the repository.
Update All
Updates all resources of the working copy that have an older revision that repository.
Commit All
Commits all resources of working copy that have a newer version compared to that of the repository.
Locally modified and the All Files view mode is currently selected (no matter if there are incoming changes).
Locally modified and there are no incoming changes when any other view mode is selected.
The remote version of the same resource, when remote information is available after a Synchronize operation
(only when one of Modified, Incoming, Outgoing and Conflicts view modes is selected).
The working copy revision, when the selected resource is from the History view.
Show History
Displays the history of the selected resource (from the Working Copy or Repository views) in the History view.
Show Annotation
Displays the annotations of the selected resource. The selected resource can be in the Working Copy or the History
views.
Revision Graph
Displays the revision graph of the selected resource. The selected resource can be in the Working Copy or the
Repositories views.
Enable/Disable flexible layout
Toggles between a fixed and a flexible layout. When the flexible layout is enabled, you can move and dock the
internal views to adapt the application to different viewing conditions and personal requirements.
Status Bar
The status bar of the Syncro SVN Client window displays important details of the current status of the application. This
information is available only in the Working Copy view.
The path of the currently processed file from the current working copy (during an operation like Check out or
Synchronize) or the result of the last operation.
The current status of the following working copy options:
).
The options for ignored and deleted files are switched on and off from the Settings menu of the Working Copy
panel:
A progress bar for the currently running SVN operation and a button (
).
Getting Started
This section explains the basic operations that can be done in Syncro SVN Client.
SVN Repository Location
This section explains how to add and edit the repository locations in Syncro SVN Client.
Add / Edit / Remove Repository Locations
Usually, team members do all of their work separately, in their own working copy, and then must share their work by
committing their changes. This is done using an Apache Subversion repository. Oxygen XML Editor supports versions
1.4, 1.5, 1.6, 1.7, and 1.8 of the SVN repository format.
Before you can begin working with a Subversion repository, you must define a repository location in the Repositories
view.
To create a repository location, use the
New Repository Location action that is available in the Repository menu,
the Repositories view toolbar, and in the contextual menu. This action opens the New Repository Location dialog box,
which prompts you for the URL of the repository you want to connect to. You can also use peg revisions at the end of
the URLs (for example, URL@rev1234) to browse only that specific revision. No authentication information is requested
at the time the location is defined. It is left to the Subversion client to request the user and password information when
it is needed. The main benefit of allowing Subversion to manage your password is that it prompts you for a new password
only when your password changes.
Once you enter the repository URL, Oxygen XML Editor tries to contact the server to get the content of the repository
for displaying it in the Repositories view. If the server does not respond in the timeout interval set in the preferences,
an error is displayed. If you do not want to wait until the timeout expires, you can use the
toolbar of the view.
There is one file for each server that you access. If you want to make Subversion forget your credentials, you can use
the Reset authentication command from the Options menu. This causes Subversion to forget all your credentials. When
you reset the authentication data, restart Oxygen XML Editor for the change to take effect.
Tip: The FILE protocol is recommended if the SVN repository and Oxygen XML Editor are located on the
same computer as it ensures faster access to the SVN repository compared with other protocols.
For HTTPS connections where client authentication is required by your SSL server, you must choose the certificate file
and enter the corresponding certificate password which is used to protect your certificate.
When using a secure HTTP (HTTPS) protocol for accessing a repository, a Certificate Information dialog box is
displayed and asks you whether you want to accept the certificate permanently, temporarily, or simply deny it.
If the repository has SVN+SSH protocol, the SSH authentication can also be made with a private key and a pass phrase.
Recursive (infinity) - Checks out all the files and folders contained in the selected folder.
Immediate children (immediates) - Checks out only the child files and folders without recursing subfolders.
File children only (files) - Checks out only the child files.
This folder only (empty) - Checks out only the selected folder (no child file or folder is included).
Get all buttons. The list of revisions can be refreshed at any time with the
Get next 50
revisions in predefined time frames (today, yesterday, this week, this month), by pressing the
from the toolbar.
The Affected Paths area displays all paths affected by the commit of the revision selected in history. You can see the
changes between the selected revision and the file's previous state using the Compare with previous version action,
available in the contextual menu.
Use an Existing Working Copy
Using an existing working copy is the process of taking a working copy that exists on your file system and connecting
it to Apache Subversion repository. If you have a brand new project that you want to import into your repository, then
see the section Import resources into the repository. The following procedure assumes that you have an existing valid
working copy on your file system.
1.
When you add unversioned or ignored directories, the initial value of the Depth field also depends on the state
of the Show unversioned directories content and Show ignored directories content options. If these options
are enabled, the value is based on the listing mode of the items in the working copy view. When they are disabled,
the value is empty .
The following options are available in this dialog box:
Enable automatic properties or Disable automatic properties - enables or disables automatic property assignment
(per runtime configuration rules), overriding the enable-auto-props runtime configuration directive, defined
in the config file of the Subversion configuration directory.
Note: This option is available only when there are defined properties to be applied automatically for resources
newly added under version control. You can define these properties in the config file of the Subversion
configuration directory, in the auto-props section. Based on the value of the enable-auto-props
runtime configuration directive, the presented option is either Enable automatic properties, or Disable
automatic properties.
No ignore - when you enable this option, file-name patterns defined to ignore unversioned resources do not apply.
Resources that are located inside an unversioned directory selected for addition, and match these patterns, are also
scheduled for addition in the repository.
In the config file of the Subversion configuration directory (the global-ignores option from the
miscellany section).
In the Oxygen XML Editor options (open the Preferences dialog box and go to SVN > Working copy >
Application global ignores).
Each of the above two options is activated only when you select an item for which the option can be applied.
Ignore Resources Not Under Version Control
Some resources inside your working copy do not need to be subject to version control. These resources can be files
created by the compiler, *.obj, *.class, *.lst, or output folders used to store temporary files. Whenever you
commit changes, Apache Subversion shows your modified files but also the unversioned files, which fill up the file
list in the commit dialog box. Though the unversioned files are committed unless otherwise specified, it is difficult to
see exactly what you are committing.
The best way to avoid these problems is to add the derived files to the Subversion ignore list. That way they are never
displayed in the commit dialog box and only genuine unversioned files that must be committed are displayed.
You can choose to ignore a resource by using the Add to svn:ignore action in the contextual menu of the Working
Copy view.
In the Add to svn:ignore dialog box, you can specify the resource to be ignored by name or by a custom pattern. The
custom pattern can contain the following wildcard characters:
* - Matches any string of characters of any size, including the empty string.
? - Matches any single character.
For example, you can choose to ignore all text documents by using the pattern: *.txt.
The action Add to svn:ignore adds a predefined Subversion property called svn:ignore to the parent directory of
the specified resource. In this property, there are specified all the child resources of that directory that must be ignored.
The result is visible in the Working Copy view. The ignored resources are represented with gray icons.
Delete Resources
The
Delete action is available in the contextual menu of the Working Copy view. When you delete an item from the
working copy, it is marked as deleted (scheduled for deletion from repository upon the next commit) and removed from
the file system. Depending on the state of each item, you are prompted to confirm the operation.
If a resource is deleted from the file system without Subversion's knowledge, the resource is marked as missing (
in your working copy. You can decide what you want to do with a missing item:
In the case of a commit, any missing item is first automatically deleted and then committed.
Note: Not any missing item can be committed as deleted, and removed from the repository. For example,
you cannot commit an item that no longer exists on the disk and that was scheduled for addition ( )
previously, since this item does not exist in the repository, but you can use the Delete action instead.
If you want to recover missing items, either update the items themselves or one of their parent directories. This
fetches their latest version from the repository.
You can also delete conflicting items (file content conflicts, property conflicts, tree-conflicts) and Syncro SVN Client
automatically marks them as resolved.
Note: It is recommended that you resolve conflicts manually to avoid loosing any important remote modifications.
Finally, you can change your mind and revert the deleted items to their initial, pristine, state.
If you copy an item to a directory that is not under version control (unversioned or ignored), the history of
the item is not preserved. For example, when copying directories, all items inside them will also be copied
without history.
If you copy a directory that contains external items, these are not copied. This is specific for SVN 1.7 working
copies only. To fetch the external items, use the Update operation on the copied directory.
In the Copy to dialog box, you can navigate through the working copy directories in order to choose a target directory,
to copy inside it. If you try to copy a single resource you are also able to change that resource's name. For versioned
items, you can select Ignore resource history to copy them without their history (similar to a simple file system copy).
Note: The Copy to dialog box only presents all the local directories that are a valid destination against the copy
operation, based on their local file status. Also, the working copy settings are taken into account.
In the Commit dialog box, only the directory in question will appear without its children.
Move Resources
As in the case of the copy command, you can move several resources at once. Select the resources in the Working Copy
view and choose the Move to action from the contextual menu. The move command actually behaves as if a copy
followed by a delete command were issued. You will find the moved resources at the desired destination and also at
their original location, but marked as deleted.
Note: External items cannot be moved using the Move to action, because they cannot be deleted. Instead, you
should edit the svn:externals property defining the external item and use the Update operation on the
item's parent folder for the change to take effect.
Attention: For SVN 1.8 working copies: when committing items that were moved and/or renamed, make sure
you select both the source and the destination, otherwise the commit operation will fail.
Rename Resources
The Rename action is available in the contextual menu of the Working Copy view and can be performed on a single
resource. This action acts as a move command with the destination directory being the same as the original location of
the resource. A copy of the original item is created with the new name, also keeping its history. The original item is
marked as deleted.
Note: External items cannot be renamed using the Rename action because they cannot be deleted. Instead, you
should edit the svn:externals property defining the external item, then use the Update operation on the item's
parent folder for the change to take effect.
Attention: For SVN 1.8 working copies: when committing items that were moved and/or renamed, make sure
you select both the source and the destination, otherwise the commit operation will fail.
Lock / Unlock Resources
The idea of version control is based on the copy-modify-merge model of file sharing. This model states that each user
contacts the repository and creates a local working copy (check out). Users can then work independently and modify
their working copies according to their needs. When their goal has been accomplished, it is time for the users to share
User authentication - the user performing the commit must be the lock owner
Software authorization - the user's working copy must have the same lock token as the one from the repository,
proving that it is the same working copy where the lock originated from.
- A file already locked from your working copy is no longer locked in the repository (it was unlocked by another
user).
- A file already locked from your working copy is being locked by another user. Now the owner of the file lock
is the user who stole the lock from you.
You can unlock a resource by selecting it and pressing the Unlock button.
Locking a File
By locking a file, you have exclusive write access to it in the repository.
Incoming changes - Changes committed by other users and not present yet in your working copy file. They are
marked with a blue highlight and on the middle divider the arrows point from right to left.
Outgoing changes - Changes you have done in the content of the working copy file. They are marked with a gray
highlight and the arrows on the divider are pointing from left to right.
Conflicting changes - This is the case when the same section of text which you already modified in the local file has
been modified and committed by some other person. They are marked with a red highlight and red diamonds on the
divider.
There are numerous actions and options available in the Compare View toolbar or in the Compare menu from the main
menu. You can decide that some changes need adjusting or that new ones must be made. After you perform the
adjustments, you may want to perform a new compare between the files. For this case there is an action called Perform
files differencing. After each files differencing operation the first found change will be selected. You can navigate from
one change to another by using the actions Go to first, Go to previous, Go to next and Go to last modification. If you
decide that some incoming change needs to be present in your working file you can use the action Copy change from
right to left. This is useful also when you want to override the outgoing modifications contained in a conflicting section.
The action Copy all non-conflicting changes from right to left copies all incoming changes which are not contained
inside a conflicting section in your local file.
Let us assume that only a few words or letters are changed. Considering that the differences are performed taking into
account whole lines of text, the change will contain all the lines involved. To find exactly what words or letters have
real conflict (
conflicts:
decorator in Name column) - Syncro SVN Client considers the following resource states to be real
conflicted state - a file reported by SVN as being in this state is obtained after it was updated/merged while having
incoming and outgoing content or property changes at the same time, changes which could not be merged. A
content conflict ( symbol in Local file status column) is reported when the modified file has binary content or
it is a text file and both local and remote changes were found on the same line. A properties conflict ( symbol
in Local properties status column) is reported when a property's value was modified both locally and remotely;
tree conflicted state ( symbol in Local file status column) - obtained after an update or merge operation, while
having changes at the directory structure level (for example, file is locally modified and remotely deleted or
locally scheduled for deletion and remotely modified);
obstructed state ( symbol in Local file status column) - obtained after a resource was versioned as one kind of
object (file, directory, symbolic link), but has been replaced outside Syncro SVN Client by a different kind of
object.
pseudo-conflict (
decorator in Name column) - a file is considered to be in pseudo-conflict when it contains both
incoming and outgoing changes. When incoming and outgoing changes do not intersect, an update operation may
automatically merge the incoming file content into the existing locally one. In this case, the pseudo-conflict marker
is removed. This marker is used only as a warning which should prevent you to run into a real conflict.
Note:
A conflicting resource cannot be committed to repository. You have to resolve it first, by using Mark
Resolved action (after manually editing/merging file contents) or by using Mark as Merged action (for
pseudo-conflicts).
and
decorators are presented only when one of the following view modes is selected: Modified,
Incoming, Outgoing, Conflicts.
The
state.
marker is used also for folders to signal that they contain a file in real conflict or pseudo-conflict
Also, for every conflicted file Subversion places three additional temporary files in your directory:
filename.ext.mine - This is your file as it existed in your working copy before you updated your working
copy, that is without conflict markers. This file has your latest changes in it and nothing else.
filename.ext.rOLDREV - This is the file that was the BASE revision before you updated your working copy,
that is the file revision that you updated before you made your latest edits.
filename.ext.rNEWREV - This is the file that Subversion client just received from the server when you updated
your working copy. This file corresponds to the HEAD revision of the repository.
OLDREV and NEWREV are revision numbers. If you have conflicts with binary files, Subversion does not attempt to
merge the files by itself. The local file remains unchanged (exactly as you last changed it) and you will get
filename.ext.r* files also.
A Property conflict is obtained when two people modify the same property of the same file or folder. When updating
such a resource a file named filename.ext.prej is created in your working copy containing the nature of the
conflict. Your local file property that is in conflict will not be changed. After resolving the conflict you should use the
Mark resolved action in order to be able to commit the file. Note that the Mark resolved action does not really resolve
the conflict. It just removes the conflicted flag of the file and deletes the temporary files.
Edit Real Content Conflicts
The conflicts of a file in the conflicted state (a file with the red double arrow icon) can be edited visually with the
Compare view (the built-in file diff tool) or with an external diff application. Resolving the conflict means deciding
for each conflict if the local version of the change will remain or the remote one instead of the special conflict markers
inserted in the file by the SVN server.
The Compare view (or the external diff application set in Preferences) is opened with the action Edit Conflict which
is available on the contextual menus of the Working Copy view and is enabled only for files in the conflicted state (an
update operation was executed but the differences could not be merged without conflicts). The external diff application
is called with 3 parameters because it is a 3-way diff operation between the local version of the file from the working
copy and the HEAD version from the SVN repository with the BASE version from the working copy as common
ancestor.
If the option Show warning dialog when edit conflicts is enabled you will be warned at the beginning of the operation
that the operation will overwrite the conflict version of the file received from the SVN server (the version which contains
the conflict markers <<<<<<<, =======, >>>>>>>) with the original local version of the file that preceded the update
operation. If you press the OK button the visual conflict editing will proceed and a backup file of the conflict version
received from the SVN server is created in the same working copy folder as the file with the edited conflicts. The name
of the backup file is obtained by appending the extension .sync.bak to the file as stored on the SVN server. If you
press the Cancel button the visual editing will be aborted.
The usual actions on the differences between two versions of a file are available on the toolbar of this view:
Save
Saves the modifications of the local version of the file displayed in the left side of the view.
Perform Files Differencing
Performs a comparison between the source file and target file.
Ignore Whitespaces
Enables or disables the whitespace ignoring feature. Ignoring whitespace means that before performing the
comparison, the application normalizes the content and trims its leading and trailing whitespaces.
Synchronized scrolling
Synchronizes scrolling so that a selected difference can be seen on both sides of the application window. This action
enables/disables the previously described behavior.
The Mark Resolved action on the file so that the result of the conflict editing process can be committed to the SVN
repository.
The Revert action so that the repository version overwrites all the local modifications.
Both actions remove the backup file and other temporary files created with the conflict version of the local file.
Revert Your Changes
If you want to undo changes made in your working copy, since the last update, select the items you are interested in,
right click to display the contextual menu and select Revert. A dialog box will open that shows you the files and folders
It is locally modified and the same resource was deleted from the repository (or deleted as a result of being renamed
or moved).
It was locally deleted (or deleted as a result of being renamed or moved) and the same resource is incoming as
modified from the repository.
The same conflict situation can occur after a merge or a switch action. The action ends with an error and the folder
containing the file that is now in the tree conflict state is also marked with a conflict icon.
Such a conflict can be resolved in one of the following ways which are available when the user double clicks on the
conflicting resource or when running the Edit conflict action:
Keep local change (delete resource) - Keeps the incoming change that comes from the repository.
Non-conflicting - A non-conflicting change occurs when a file has been changed remotely but has not been modified
locally.
Conflicting, but auto-mergeable - An auto-mergeable conflicting change occurs when a text file has been changed
both remotely and locally (for example, has non-committed local changes) but the changes are on different lines of
text. Not applicable to binary resources (for example, multimedia files, PDFs, executable program files)
Conflicting - A conflicting change occurs when one or more of the same lines of a text file have been changed both
remotely and locally.
If the resource contains only incoming changes or the outgoing changes do not intersect with incoming ones then the
update will end normally and the Subversion system will merge incoming changes into the local file. In the case of a
conflicting situation the update will have as result a file with conflict status.
The Oxygen XML Editor allows you to update your working copy files to a specific revision, not only the most recent
one. This can be done by using the Update to revision/depth action from the Working Copy view (All Files view
mode) or the Update to revision action from the History view contextual menu.
If you select multiple files and folders and then you perform an Update operation, all of those files and folders are
updated one by one. The Subversion client makes sure that all files and folders belonging to the same repository are
updated to the exact same revision, even if between those updates another commit occurred.
When the update fails with a message saying that there is already a local file with the same name Subversion tried to
check out a newly versioned file, and found that an unversioned file with the same name already exists in your working
folder. Subversion will never overwrite an unversioned file unless you specifically do this with an Override and update
action. If you get this error message, the solution is simply to rename the local unversioned file. After completing the
update, you can check whether the renamed file is still needed.
Send Your Changes to the Repository
Sending the changes you made to your working copy is known as committing the changes. If your working copy is
up-to-date and there are no conflicts, you are ready to commit your changes.
The Commit action sends the changes from your local working copy to the repository. The Commit dialog box presents
all the items that you are able to commit.
Unversioned or missing items are not selected by default in the Commit dialog box, unless you have selected them
explicitly when issuing the commit command.
Items that have been added or replaced previously, but now are presented as missing after being removed
from the file system, outside of an SVN client. Such items do not exist in the repository and you should use
the Delete action to remove them from your working copy.
Items that have incoming changes from the repository, after a synchronization. You need to have your
working copy up-to-date before committing your changes.
Files that, after a synchronization, appear as locked by other users or from other locations than the current
working copy.
Note: Due to dependencies between items, when you select or clear an unversioned ( ) or added ( ) item
in the Commit dialog box, other items with one of these states can be selected or cleared automatically.
The modifications that will be committed for each file can be reviewed in the compare editor window by double clicking
a file in the Commit dialog box, or by right clicking and selecting the Show Modifications action from the contextual
menu. This option is available to review only file content changes, not property changes.
The
Local file status column indicates the actual state of the items and the
indicates whether the properties of an item are modified.
The
Lock information column is displayed if at least one of the files in the Commit dialog box has lock information
associated with it, valid against the commit operation.
The following options are available in this dialog box:
Enable automatic properties or Disable automatic properties - enables or disables automatic property assignment
(per runtime configuration rules), overriding the enable-auto-props runtime configuration directive, defined
in the config file of the Subversion configuration directory.
Note: This option is available only when there are defined properties to be applied automatically for resources
newly added under version control. You can define these properties in the config file of the Subversion
configuration directory, in the auto-props section. Based on the value of the enable-auto-props
runtime configuration directive, the presented option is either Enable automatic properties, or Disable
automatic properties.
Keep locks - selecting the Keep locks option preserves any locks you set on various files.
Note: This option is available only when files that you locked are presented in the dialog box.
Each of the above options is activated only when you select an item for which the option can be applied.
Your working copy must be up-to-date with respect to the resources you commit. This is ensured by using the Update
action prior to committing, resolving conflicts and re-testing as needed. If your working copy resources you are trying
to commit are out of date you will get an appropriate error message.
Committing to Multiple Locations
Although Subversion does not support committing to different locations at once, Syncro SVN Client offers this
functionality regarding external items.
If items to be committed belong to different external definitions found in the working copy, they are grouped under the
corresponding item that indicates their repository origin. Each parent item is rendered bold and its corresponding
repository location is presented when hovering it. Parent items are decorated with a small arrow ( ) if they are external
definitions. The working copy root directory is never decorated and is not presented if there are no external items listed
(all items belong to the main working copy). Each child item is presented relative to the parent item.
Note: When an external directory has modifications of its own, it is presented both as a parent item and as an
item that you can select and commit. This is always the case for external files.
bugtraq:message - A string property. If it is set the Commit dialog box will display a text field for entering the bug
ID. It must contain the string %BUGID%, which is replaced with the bug number on commit.
bugtraq:label - A string property that sets the label for the text field configured with the bugtraq:message property.
bugtraq:url - A string property that is the URL pointing to the bug tracking tool. The URL string should contain
the substring %BUGID% which Syncro SVN Client replaces with the issue number. That way the resulting URL
will point directly to the correct issue.
bugtraq:warnifnoissue - A boolean property with the values true/yes or false/no. If set to true, the Syncro SVN
Client will warn you if the bug ID text field is left empty. The warning will not block the commit, only give you a
chance to enter an issue number.
bugtraq:number - A boolean property with the value true or false. If this property is set to false, then any character
can be entered in the bug ID text field. If the property is set to true or is missing then only numbers are allowed as
the bug ID.
bugtraq:append - A boolean property. If set to false, then the bug ID is inserted at the beginning of the commit
message. If yes or not set, then it's appended to the commit message.
bugtraq:logregex - This property contains one or two regular expressions, separated by a newline. If only one
expression is set, then the bug ID's must be matched in the groups of the regular expression string, for example
[Ii]ssue #?(\d+) If two expressions are set, then the first expression is used to find a string which relates to
a bug ID but may contain more than just the bug ID (for example, Issue #123 or resolves issue 123).
The second expression is then used to extract the bug ID from the string extracted with the first expression. An
example: if you want to catch every pattern issue #XXX and issue #890, #789 inside a log message you
could use the following strings:
The data configured with these SVN properties is stored on the repository when a revision is committed. A bug tracking
system or a statistics tools can retrieve the revisions that affected a bug from the SVN server and present the commits
related to that bug to the user of the bug tracking system.
If the bugtraq:url property was filled in with the URL of the bug tracking system and this URL includes the %BUGID%
substring as specified above in the description of the bugtraq:url property then the History view presents the bug ID
as a hyperlink in the commit message. Clicking such a hyperlink in the commit message of a revision opens a Web
browser at the page corresponding to the bug affected by that commit.
Obtain Information for a Resource
This section explains how to obtain information for a SVN resource:
Request Status Information for a Resource
While you are working with the SVN Client you often need to know which files you have changed, added, removed, or
renamed, or even which files got changed and committed by others. This is where the Synchronize action from the
The value of a property of the resource displayed in the dialog box can be copied by right-clicking the property and
selecting the Copy action.
Request History for a Resource
In Apache Subversion, both files and directories are versioned and have a history. If you want to examine the history
for a selected resource and find out what happened at a certain revision you can use the History view that can be accessed
from Repositories view, Working Copy view, Revision Graph, or Directory Change Set view. From the Working copy
view you can display the history of local versioned resources.
Management of SVN Properties
In the Properties view you can read and set the Apache Subversion properties of a file or folder. There is a set of
predefined properties with special meaning to Subversion. For more information about properties in Subversion see the
SVN Subversion specification. Subversion properties are revision dependent. After you change, add or delete a property
for a resource, you have to commit your changes to the repository.
If you want to change the properties of a given resource you need to select that resource from the Working Copy view
and run the Show properties action from the contextual menu. The Properties view will show the local properties for
the resource in the working copy. Once the Properties view is visible, it will always present the properties of the currently
selected resource. In the Properties view toolbar there are available actions which allow you to add, change and delete
the properties.
If you choose the Add a new property action, a new dialog box will appear that contains the following:
Name - Combo box that allows you to enter the name of the property. The drop-down menu of the combo box
presents the predefined Subversion properties (such as svn:ignore, svn:externals, svn:needs-lock, etc.)
Current value - Text area which allows you to enter the value of the new property.
If the selected item is a directory, you can also set the property recursively on its children by checking the Set property
recursively checkbox.
If you want to change the value for a previously set property you can use the Edit property action which will display
a dialog box where you can set:
If you want to completely remove a property previously set you can choose the Remove property action. It will display
a confirmation dialog box in which you can choose also if the property will be removed recursively.
In the Properties view there is a Refresh action which can be used when the properties have been changed from outside
the view. This can happen, for example, when the view was already presenting the properties of a resource and they
have been changed after an Update operation.
Branches and Tags
One of the fundamental features of version control systems is the ability to create a new line of development from the
main one. This new line of development will always share a common history with the main line if you look far enough
back in time. This line is known as a branch. Branches are mostly used to try out features or fixes. When the feature or
fix is finished, the branch can be merged back into the main branch (trunk).
Another feature of version control systems is the ability to take a snapshot of a particular revision, so you can at any
time recreate a certain build or environment. This is known as tagging. Tagging is especially useful when making release
versions.
In Apache Subversion, there is no difference between a tag and a branch. On the repository, both are ordinary directories
that are created by copying. The trick is that they are cheap copies instead of physical copies. Cheap copies are similar
to hard links in Unix, which means that they merely link to a specific tree and revision without making a physical copy.
As a result, branches and tags occupy little space on the repository and are created very quickly.
Provided that nobody ever commits to the directory in question, it remains a tag. If people start committing to it, it
becomes a branch.
Create a Branch / Tag
To create a branch or tag by copying a directory, use the Branch/Tag action that is available in the Tools menu when
an item is selected in the Working Copy view or Repositories view, or from the contextual menu of the Repositories
view.
HEAD revision in the repository - The new branch or tag will be copied in the repository from the HEAD revision.
The branch will be created very quickly, as the repository will make a cheap copy.
Specific revision in the repository - The new branch will be copied into the repository, but you can specify the
exact desired revision. For example, this is useful if you forgot to make a branch or tag when you released your
application. If you click the History button you can select the revision number from the History dialog box. This
type of branch will also be created very quickly.
Working copy - (Available only if the item is selected from the Working copy view). The new branch will be a
copy of your local working copy. If you have updated some files to an older revision in your working copy, or if
you have made local changes, that is exactly what goes into the copy. This involves transferring some data from
your working copy back to the repository, or more specifically, the locally modified files.
You can specify the location of the new branch or tag in the Destination section:
Into repository's directory - The URL of the parent directory of the new branch or tag.
Note: Peg revisions have no effect for this operation since it is used to send information to the repository.
Under the name - You can specify another branch or tag name other than the name of the resource selected in the
Repositories or Working copy view.
The new branch or tag will be created as a child of the specified URL of the repository directory and will have the new
name.
Merge revisions - port changes from one branch to another. Note that the trunk can also be considered a branch, in
this context.
Synchronize branch - fetch all the changes made on a parent branch (or the trunk) to a child branch.
Reintegrate a branch - merge back a branch to its parent branch (which can also be the trunk).
Merge two different trees - integrate the changes done on a branch to a different branch.
Perform pre-merge best practices checks of the working copy target - When enabled, the SVN Client checks if the
working copy target item is ready for the merge operation and displays the pre-merge checks wizard page.
Merge Revisions
This is the case when you have made one or more changes to a branch and you want to duplicate them in a different
branch. For example, we know that a problem has been fixed by committing revisions 17, 20, and 25 on branch B1.
These changes are also needed in branch B2. Thus, in order to merge them, we need a working copy of the B2 branch.
To merge revisions from a different branch, follow these steps:
1. Go to menu Tools > Merge.
The Merge wizard is opened.
2. Select the Merge revisions option.
3. It is recommended that you enable the Perform pre-merge best practices checks of the working copy target
option to make sure that the working copy target item is ready for the merge operation.
a) Press the Next button.
If the Perform pre-merge best practices checks of the working copy target option was enabled, the Pre-Merge
Checks wizard page is displayed.
Note: If errors are found you need to solve them before proceeding.
4. Press the Next button.
The Merge revisions wizard page is displayed.
5. In the Merge from (URL) text box, enter the URL of the branch or tag that contain the changes that you want to
duplicate in your working copy. In our example, it is the URL of the B1 branch.
You may also click the Browse button to browse the repository and find the desired branch. If you have previously
merged from this branch, then you can simply use the drop down menu, which displays a history of previously used
URLs.
Note: If the URL belongs to a different repository than the working copy, the Ignore ancestry / Disable
merge tracking option, in the Merge Options wizard page, will be enabled automatically (and you cannot
change this). This is because the Subversion client cannot track changes between different repositories.
Tip: You can also specify a peg revision at the end of the URL (for example, URL@rev1234). The peg
revision does not affect the merge range you select. By default, the HEAD revision is assumed.
all revisions - The operation will include all eligible revisions that were not yet merged.
specific revision(s) - You can specify one or more individual revisions and/or revision ranges. Also, you can
mix forward ranges (for example, 1-5), backward ranges (for example, 20-15), and subtract specific revisions
from a range (for example, 1-5, -3).
Note: If using the Subversion command-line client, a revision range of the form 1-5 means all changes
starting from revision 2 up to revision 5 (the changes necessary to reach revision 5, committed after revision
1). Unlike the Subversion command-line client, in Syncro SVN Client the revision ranges are inclusive,
meaning that it will process all revisions, starting with revision 1, up to and including revision 5.
Attention: The HEAD revision is the only non-numerical revision allowed, and it can only be used when
specifying revision ranges as one of the ends of the range (for example, 10-HEAD). Be careful when using
it, as it might not refer to the desired revision, if it has recently been committed by another user.
Tip: If you want to perform a reverse merge and roll-back your working copy changes that have already
been committed to the repository, use the negative revisions notation (for example, -7) or backward revision
ranges (for example, 20-10).
a) If you press the History button, the History dialog box is displayed, which allows you to select one or more
revisions to be merged.
7. Optionally, if you want to configure the options for your merge, press the Next button.
The Merge Options wizard page is displayed that allows you to configure options for the operation.
Warning: If the Ignore ancestry / Disable merge tracking option is enabled and you selected all revisions
in the Revisions to merge section, revisions that were previously merged will also be included, which may
result in conflicts.
8. Press the Merge button.
The merge operation is performed.
If the merge is completed successfully, all the changes corresponding to the selected revisions should be merged in your
working copy.
It is recommended to look at the results of the merge, in the working copy, to review the changes and see if it meets
your expectations. Since merging can sometimes be complicated, you may need to resolve conflicts after making major
changes.
Note: The merge result is only in your local working copy and needs to be committed to the repository for it
to be available to others.
Synchronize a Branch
While working on your own branch, other people on your team might continue to make important changes in the parent
branch (which can be the trunk itself or any other branch). It is recommended to periodically duplicate those changes
in your branch to make sure your changes are compatible with them. This is done by performing a synchronize merge,
which will bring your branch up-to-date with any changes made to its ancestral parent branch since the time your branch
was created or last synchronized. Subversion is aware of the history of your branch and can detect when it split away
from the parent branch.
Frequently keeping your branch in sync with the parent branch helps you to prevent unexpected conflicts when the time
comes for you to duplicate your changes back into the parent branch. The synchronization uses merge tracking to skip
all those revisions that have already been merged, thus a sync merge can be repeated periodically to fetch all the latest
changes of the parent branch to keep up-to-date with it.
Important: It is recommended to synchronize the whole working copy that was created from the child branch
(the root of the working copy), rather than just a part of it.
Local modifications.
The revision of the working copy must be greater than or equal to the last revision of the parent branch with which
the child branch was synchronized.
Tip: You can use the pre-merge checks option to make sure these conditions are fulfilled.
This method is useful when you have a feature branch on which the development has concluded and it should be merged
back into its parent branch. Since you have kept the feature branch synchronized with its parent, the latest versions of
them will be absolutely identical except for your feature branch changes. These changes can be reintegrated into the
parent branch by using a working copy of it and the Reintegrate a branch option.
This method uses the merge-tracking features of Apache Subversion to automatically calculate the correct revision
ranges and to perform additional checks that will ensure that the branch to be reintegrated has been fully updated with
its parent changes. This ensures that you do not accidentally undo work that others have committed to the parent branch
since the last time you synchronized the child branch with it. After the merge, all branch development will be completely
merged back into the parent branch, and the child branch will be redundant and can be deleted from the repository.
Tip: Before reintegrating the child branch it is recommended to synchronize it with its parent branch one more
time, to help avoid any possible conflicts.
To reintegrate a child branch into its parent branch, follow these steps:
1. Go to menu Tools > Merge.
The Merge wizard is opened.
2. Select the Reintegrate a branch option.
Note: This option is disabled if the selected working copy item (or if it is a directory, any of the items inside
of it) has any type of modification. This is because it is mandatory for the target item to have no modifications.
3. It is recommended that you enable the Perform pre-merge best practices checks of the working copy target
option to make sure that the working copy target item is ready for the merge operation.
a) Press the Next button.
If the Perform pre-merge best practices checks of the working copy target option was enabled, the Pre-Merge
Checks wizard page is displayed.
Note: If errors are found you need to solve them before proceeding.
4. Press the Next button.
The Reintegrate a branch wizard page is displayed.
5. In the Child branch (URL) text box, enter the URL of the child branch to be reintegrated. This means that the URL
must belong to the same repository as your working copy that was created from the parent branch.
You may also click the Browse button to browse the repository and find the desired branch. If you have previously
merged from this branch, then you can simply use the drop down menu, which displays a history of previously used
URLs.
Tip: You can also specify a peg revision at the end of the URL (for example, URL@rev1234). The peg
revision specifies both the peg revision of the URL and the latest revision that will be considered for merging.
By default, the HEAD revision is assumed.
The Merge Options wizard page is displayed that allows you to configure options for the operation.
Note: Since a reintegrate merge is so specialized, most of the merge options are not available, except for
those in the File Comparison category.
6. Press the Merge button.
HEAD revision - Use this option if you are sure that no one else has committed changes since the last
synchronization.
other revision - Use this option to input a specific revision number and avoid losing recent commits. You can
use the History button to see a list of all revisions.
7. In the To (ending URL and revision) section enter the URL of the second branch.
You may also click the Browse button to browse the repository and find the desired branch. If you have previously
merged from this branch, then you can simply use the drop down menu, which displays a history of previously used
URLs.
Tip: If you are using this method to merge a feature branch back to its parent branch, enter the URL of the
feature branch. This way, only the changes unique to this branch will be merged, since the branch should
have been periodically synchronized with its parent.
Attention: The URL must point to the same repository as the one in the From (starting URL and revision)
field. Otherwise, the operation will not be allowed, since Subversion cannot compute changes between items
from different repositories.
Tip: You can also specify a peg revision at the end of the URL (for example, URL@rev1234). By default,
the HEAD revision is assumed.
8. Select a revision to compute all changes committed up to that point by choosing between HEAD revision and other
revision.
9. Optionally, if you want to configure the options for your merge, press the Next button.
The Merge Options wizard page is displayed that allows you to configure options for the operation.
Warning: If the Ignore ancestry / Disable merge tracking option is enabled and you selected all revisions
in the Revisions to merge section, revisions that were previously merged will also be included, which may
result in conflicts.
10. Press the Merge button.
The merge operation is performed.
If the merge is completed successfully, all the changes corresponding to the selected revisions should be merged in your
working copy.
It is recommended to look at the results of the merge, in the working copy, to review the changes and see if it meets
your expectations. Since merging can sometimes be complicated, you may need to resolve conflicts after making major
changes.
Note: The merge result is only in your local working copy and needs to be committed to the repository for it
to be available to others.
Merge Options
Here is the list of options that can be used when merging:
Depth (This option is applicable only for directories) - sets the depth of the merge operation. You can specify how
far down into your working copy the merge should go by selecting one of the following values:
Current depth - Obeys the depths registered for the directories in the working copy that are to be switched.
Recursive (infinity) - Merges all the files and folders contained in the selected folder. This is the recommended
depth for most users, to avoid incomplete merges and subtree mergeinfo.
Immediate children (immediates) - Merges only the child files and folders without recursing subfolders.
File children only (files) - Merges only the child files.
This folder only (empty) - Merges only the selected folder (no child files or folders are included).
Note: The depth term is described in the Sparse checkouts section. The default depth is the current depth
of the working copy item receiving the merge.
Ignore ancestry / Disable merge tracking - Changes the way two items are merged if they do not share a common
ancestry. Most merges involve comparing items that are ancestrally related to one another. However, occasionally
you may want to merge unrelated items. If this option is disabled, the first item will be replaced with the second
item. In these situations, you would want the merge to do a path-based comparison only, ignoring any relations
between the items. For example, if two different files have the same name and are in the same relative location,
disabling the option replaces one of the files with the other one, and enabling it merges their contents.
Note: If the URL of the merge source belongs to a different repository than the URL of the target working
copy item (the one receiving the changes), this option is selected automatically (and you cannot change this).
This is because the Subversion client cannot track changes between different repositories.
Force deletion of modified or non-versioned items, if necessary - If disabled, when the merge operation involves
deleting locally modified or non-versioned items, it will fail. This is done in order to prevent data loss. This option
is only available if there are uncommitted changes in the working copy.
Only record the merge (block revisions from getting merged) - Available when the Ignore ancestry / Disable
merge tracking option is disabled. It enables a special mode of the merge operation that just records it in the local
merge tracking information, without actually performing it (does not modify any file contents or the structure of
your working copy). You might want to enable this option for two possible reasons:
Ignore line endings - Allows you to specify how the line ending changes should be handled. By default, all such
changes are treated as real content changes, but you can ignore them if you select this option.
Ignore whitespaces - Allows you to specify how the whitespace changes should be handled. By default, all such
changes are treated as real content changes, but you can ignore them if you select this option.
Ignore whitespace changes - Ignores changes in the amount of whitespaces or to their type (for example, when
changing the indentation or changing tabs to spaces).
Note: Whitespaces that were added where there were none before, or that were removed, are still
considered to be changes.
Test merge - Performs a dry run of the merge operation, allowing you to preview it without actually performing the
merge. In the Console view you will see a list of the working copy items that will be affected and how they will be
affected. This is helpful in detecting whether or not a merge will be successful, and where conflicts may occur.
Resolve later - Used for leaving the conflict as it is, to manually resolve it later.
Keep incoming - This option keeps all the incoming modifications and discards all current ones from your working
copy.
Keep outgoing - This option keeps all current modifications from your working copy and discards all incoming
ones.
Modifications.
Sparse directories (all directories must be of depth infinity).
Switched items.
Important: This recommendation becomes mandatory when performing a reintegrate merge operation. Also,
trying to merge to mixed-revision working copies will fail in all types of merge operations.
Remember: The merge result is only in your local working copy and needs to be committed to the repository
for it to be available to others.
Two revisions of a version item - the item can be local or remote and you can select two versions of it. This also
applies when you need to generate a patch that only contains the changes in the working copy that were not yet
committed.
Two different versioned items from the repository - the items are remote and you need to specify a revision for both.
Warning: The resulting patch file may contain content that was written using a mix of encodings, based upon
the encodings of the files that were compared. If you open the generated patch file in a text editor, it may result
in unrecognizable content.
Figure 423: The Create Patch Dialog Box - Add Unversioned Resources
The patch is created and stored in the path specified in the Output section of the Options page or in the default
location.
Create Patch Against a Specific Revision
This type of patch contains changes between an old revision and the current content from the selected item within the
working copy.
This option is useful if you want to obtain differences between an older revision and the current state of the working
copy (for instance, to test how current changes apply to an older version).
The steps are as follows:
1. Go to menu Tools > Create patch.
This opens the Create patch wizard.
2. Select the Create patch against a specific revision option in the dialog box.
3. Press the Next button.
The second step of the wizard is opened:
Output Section
Save as
The patch will be created and saved in the specified file.
Use Git extended diff format
When enabled, the patch is generated using the Git format. This option corresponds to the --git option of the
svn diff command.
Working with Repositories
This section explains how to locate and browse SVN repositories in Syncro SVN Client.
Ignore keywords
When enabled, the export operation does not expand the SVN keywords found inside the files.
Copy / Move / Delete Resources From a Repository
Once you have a location defined in the Repositories view, you can run commands (such as copy, move, and delete)
directly on the repository. The commands correspond to the following actions in the contextual menu:
The Copy to and Move to action allows you to copy and move individual or multiple resources to a specific directory
from the HEAD revision of the repository.
New name - This option is presented when you copy or move a single item, allowing you to also rename it.
Another useful action is Delete, allowing you to erase resources directly from the repository.
All three actions are commit operations and you will be prompted with the Commit message dialog box.
Sparse Checkout
Sometimes you need to check out only certain parts of a directory tree. For this you can check out the top directory (the
action Check out from the Repositories view) and then update recursively only the needed directories (the action Update
from the Working Copy view). Now, each directory has a depth set to it, which has four possible values:
For some operations, you can use as depth the current depth registered on the directories from the working copy (the
value Current depth). This is the depth value defined in a previous check out or update operation.
The sparse checked out directories are presented in the Working Copy view with a marker corresponding to each depth
value, in the top left corner, as follows:
Recursive (infinity) - This is the default value and it is has no mark. The directory has no limiting depth.
Immediate children (immediates) - The directory is limited to direct child directories (without contents) and
files.
File children only (files) - The directory is limited to direct child files only.
This folder only (empty) - The directory has empty depth set.
A depth set on a directory means that some operations process only items within the specified depth range. For example,
Synchronize on a working copy directory reports the repository modified items within the depth set on the directory
and those existing in the working copy outside of this depth.
The depth information is also presented in the SVN Information dialog box and in the tool tip displayed when hovering
a directory in the Working Copy view.
Repositories View
Working Copy View
History View
Console View
The other views that support the main working area are also presented in this section.
Repositories View
The Repositories view allows you to define and manage Apache Subversion repository locations and browse repositories.
If no connections to your repository are available, you can add a new repository location. Repository files and folders
are presented in a tree view with the repository locations at the first level, where each location represents a connection
to a specific repository. More information about each resource is displayed in a tabular form:
New Repository Location - Allows you to enter a new repository location by means of the Add SVN Repository
dialog box.
Move Up - Move the selected repository up one position in the list of repositories in the Repositories view.
Move Down - Move the selected repository down one position in the list of repositories in the Repositories
view.
If you click any of the view modes (All Files, Modified, Incoming, Outgoing, Conflicts), the information displayed
changes as follows:
All Files - Resources (files and folders) are presented in a hierarchical structure with the root of the tree
representing the location of the working copy on the file system. Each resource has an icon representation which
describes the type of resource and also depicts the state of that resource with a small overlay icon.
Modified - The resource tree presents resources modified locally (including those with conflicting content)
and remotely. Decorator icons are used to differentiate between various resource states:
- Pseudo-conflict state - A resource being locally and remotely modified at the same time, or a parent
directory of such a resource.
- Real conflict state - A resource that had both incoming and outgoing changes and not all the differences
could be merged automatically through the update operation (manually editing the local file is necessary for
resolving the conflict).
Conflicts - The resource tree presents only conflicting changes (real conflicts and pseudo-conflicts).
Name - Resource name. Resource icons can have the following decorator icons:
Propagated modification marker - A folder marked with this icon indicates that the folder itself presents
some changes (like modified properties) or a child resource has been modified.
External - This indicates a mapping of a local directory to the URL of a versioned resource. It is declared
with a svn:externals property in the parent folder and it indicates a working copy not directly related
with the parent working copy that defines it.
Switched - This indicates a resource that has been switched from the initial repository location to a new
location within the same repository. The resource goes to this state as a result of the Switch action executed
from the contextual menu of the Working Copy view.
Grayed - A resource with a grayed-out icon, but no overlaid icon, is an ignored resource. It is obtained
with the Add to svn:ignore action.
Immediate children (immediates) (a variant of sparse checkout) - The directory contains only direct
file and folder children. Child folders ignore their content.
File children only (files) (a variant of sparse checkout) - The directory contains only direct file children,
disregarding any child folders.
This folder only (empty) (a variant of sparse checkout) - The directory discards any child resource.
Note:
Any folder not marked with one of the depth icons, has recursive depth (infinity) set by default
(presents all levels of child resources).
Although folders not under version control can have no depth set, Oxygen XML Editor presents
unversioned and ignored folders with empty depth when Show unversioned directories content or
Show ignored directories content options are disabled.
Local file status - Shows the changes of working copy resources that were not committed to the repository yet.
The following icons are used to mark resource status:
- Marks a resource scheduled for addition, created by copying a resource already under version control and
inheriting all its SVN history.
- Resource is deleted(scheduled for deletion from Repository upon the next commit).
- The resource is incomplete (as a result of an interrupted check out or update operation).
- The resource is missing because it was moved or deleted without using an SVN-aware application.
- Resource is obstructed (versioned as one kind of object: file, directory, or symbolic link, but has been replaced
outside Syncro SVN Client by a different kind of object).
Local properties status - Marks the resources that have SVN properties, with the following possible states:
Remote properties status - Resources marked with the icon have incoming modified properties from the
repository.
Remote revision - Revision number of the resource latest committed modification.
Remote date - Date of the resource latest modification committed on the repository.
Remote author - Name of the author who committed the latest modification on the repository.
Lock information - Shows the lock state of a resource. The lock mechanism is a convention intended to help
you signal other users that you are working with a particular set of files. It minimizes the time and effort wasted in
solving possible conflicts generated by clashing commits. A lock gives you exclusive rights over a file, only if other
users follow this convention and they do not try to bypass the lock state of a file.
A folder can be locked only by the SVN client application, completely transparent to the user, if an operation in
progress was interrupted unexpectedly. As a result, folders affected by the operation are marked with the
To clear the locked state of a folder, use the Clean up action.
symbol.
no lock - the file is not locked. This is the default state of a file in the SVN repository.
remotely locked (
) - shown when:
If you try to commit a new revision of the file to the repository, the server does not allow you to bypass the file
lock.
Note: To commit a new revision, you need to wait for the file to be unlocked. Ultimately, you might try
to break or steal the lock, but this is not what other users expect. Use these actions carefully, especially
when you are not the file lock owner.
locked ( ) - displayed after you have locked a file from the current working copy. Now you have exclusive
rights over the corresponding file, being the only one who can commit changes to the file in the repository.
Note: Working copies keep track of their locked files, so the locks are presented between different
sessions of the application. Synchronize your working copy with the repository to make sure that the
locks are still valid (not stolen or broken).
stolen ( ) - a file already locked from your working copy is being locked by another user. Now the owner of
the file lock is the user who stole the lock from you.
broken ( ) - a file already locked from your working copy is no longer locked in the repository (it was unlocked
by another user).
Note: To remove the stolen or broken states from your working copy files, you have to Update them.
If one of your working copy files is locked, hover the mouse pointer over the lock icon to see more information:
The toolbar contains the following options for switching to a different working copy:
List of Defined Working Copies - A drop-down menu that contains all the working copies Oxygen XML Editor is
aware of. When you select a different working copy from the list, the newly selected working copy content is scanned
and displayed in the Working Copy view.
(
on Mac OS X) Working Copies Manager - Opens a dialog box that displays the working copies Oxygen
XML Editor is aware of. In this dialog box, you can add existing working copies or remove those you no longer
need. If you try to add a folder that is not a valid Subversion working copy, Oxygen XML Editor warns you that the
selected directory is not under version control.
Show ignored items - Displays the ignored resource when All Files mode is selected.
Show ignored directories content - Displays the content of ignored directories when All Files mode is selected.
Note: Although ignored items are not presented in the Modified, Incoming, and Conflicts modes, they
will be if, after a synchronize, they are reported as incoming from the repository.
Show deleted items - Displays the deleted resource when All Files mode is selected. All other modes always display
deleted resources, disregarding this option.
Tree /
Compressed /
Flat - Affect the way information is displayed inside the Modified, Incoming,
Outgoing, and Conflicts view modes.
Configure columns - Allows you to customize the structure of the Working Copy view data. This action opens the
following dialog box:
If the format is older than SVN 1.7, you are prompted to upgrade it to SVN 1.8 in order to load it.
If the format is 1.7, Syncro SVN Client takes into account the state of the When loading an old format working
copy option.
The format of the working copy can be downgraded or upgraded at any time with the Upgrade and
Downgrade actions available in the Tools menu. These actions allow switching between SVN 1.7 and SVN
1.8 working copy formats.
Latest from HEAD (Ctrl (Command on OS X) + Alt + H) - Performs a 3-way diff operation between the
selected file and the HEAD revision from the repository and displays the result in the Compare view. The
common ancestor of the 3-way diff operation is the BASE version of the file from the local working copy.
BASE revision (Ctrl (Command on OS X) + Alt + C) - Compares the working copy file with the BASE
revision file (the so-called pristine copy).
Revision (Ctrl (Command on OS X) + Alt + R) - Displays the History view that contains the log history of
that resource.
Branch/Tag - Opens the Compare with Branch/Tag dialog box that allows you to specify another file from
the repository (To URL field) to compare with the working copy file. You can specify the revision of the
repository file by choosing between HEAD revision or specific Other revision.
Tip: To compare with a file that was deleted, moved, or replaced, you need to specify the original URL
(before the file was removed) and use a peg revision at the end (for example, URL@rev1234).
These compare actions are enabled only if the selected resource is a file.
Replace with:
Latest from HEAD - Replaces the selected resources with their versions from the HEAD revision of the
repository.
BASE revision - Replace the selected resources with their versions from the pristine copy (the BASE revision).
For the Replace with BASE revision action, the resources being unversioned or added have no BASE
revision, and thus cannot be replaced. However, they will be deleted if the action is invoked on a parent
folder. The action will never work for missing folders or for obstructing files (folders being obstructed
by a file), since you cannot recover a tree of folders
For the Replace with latest from HEAD action, you must be aware that there are cases when resources
will be completely deleted or reverted to the BASE revision and then updated to a HEAD revision to
avoid conflicts. These cases are:
../ - Relative to the URL of the directory on which the svn:externals property is set.
^/ - Relative to the root of the repository in which the svn:externals property is versioned.
// - Relative to the scheme of the URL of the directory on which the svn:externals property is set.
/ - Relative to the root URL of the server in which the svn:externals property is versioned.
Important: To change the target URL of an external definition, or to delete an external item, do the
following:
1. Modify or delete the item definition found in the svn:externals property that is set on the
parent folder.
2. For the change to take effect, use the Update operation on the parent folder of the external item.
Note: Syncro SVN Client does not support definitions of local relative external items.
Scan for locks (Ctrl (Command on OS X) + L) - Contacts the repository and recursively obtains the list of
locks for the selected resources. A dialog box containing the locked files and the lock description will be displayed.
This is only active for resources under version control. For more details see Scanning for locks.
Lock (Ctrl (Command on OS X) + K) - Allows you to lock certain files that need exclusive access. You
can write a comment describing the reason for the lock and you can also force (steal) the lock. This action is
active only on files under version control. For more details on the use of this action see Locking a file.
Unlock (Ctrl (Command on OS X) + Alt + K) - Releases the exclusive access to a file from the repository.
You can also choose to unlock it by force (break the lock).
Information message - Informs you why there are no resources presented in the currently selected view mode.
Synchronize with Repository - Available only when there is nothing to present in the Modified and Incoming
view modes.
Show all changes/incoming/outgoing/conflicts - Depending on the currently selected view mode, this action
presents the corresponding resources after a synchronize operation was executed only on a part of the working copy
resources.
The table showing details about each revision, like: revision number, commit date and time, number of changes
(more details available in the tooltip), author's name, and a fragment of the commit message.
Some revisions may be highlighted to emphasize:
The current revision of the resource for which the history is displayed - a bold font revision.
The last revision in which the content or properties of the resource were modified - blue font revision.
Note: Both font highlights may be applied for the same revision.
A tree structure showing the folders where the modified resources are located. You can compress this structure to a
more compact form that focuses on the folders that contain the actual modifications.
The list of resources modified in the selected revision. For each resource, the type of action done against it is marked
with one of the following symbols:
Group
Only revisions between a start revision number and an end revision number.
Only revisions added in a period of time (such as today, last week, last month, etc.)
The toolbar of the History view has two buttons for extending the set of revisions presented in the view: Get next 50
and Get all.
The History Filter Field
When only the history entries which contain a specified substring need to be displayed in the History view the filter
field displayed at the top of this view is the perfect fit. Just enter the search string in the field next to the label Find.
Only the items with an author name, commit message, revision number or date which match the search string are kept
in the History view. The filter action is executed and the content of the table is updated when the button
pressed.
Search is
Author - Changes the name of the SVN user that committed the selected revision.
Message - Changes the commit message of the selected revision.
When two resources are selected in the History view, the contextual menu contains the following actions:
Compare revisions
When the resource is a file, the action compares the two selected revisions using the Compare view. When the
resource is a folder, the action displays the set of all resources from that folder that were changed between the two
revision numbers.
Revert changes from these revisions
Similar to the svn merge command, it merges two selected revisions into the working copy resource. This action
is only enabled when the resource history was requested for a working copy item.
For more information about the History view and its features, see the Request history for a resource and Using the
resource history view sections.
Directory Change Set View
The result of comparing two reference revisions from the history of a folder resource is a set with all the resources
changed between the two revision numbers. The changed resources can be contained in the folder or in a subfolder of
that folder. These resources are presented in a tree format. For each changed resource all the revisions committed between
the two reference revision numbers are presented.
Ignore whitespace changes - Ignores changes in the amount of whitespaces or to their type (for example, when
changing the indentation or changing tabs to spaces).
Note: Whitespaces that were added where there were none before, or that were removed, are still
considered to be changes.
after obtaining the outgoing status of a file with a Refresh operation, the view can be used to show the differences
between your working file and the pristine copy. In this way you can find out what changes you will be committing;
after obtaining the incoming and outgoing status of the file with the Synchronize operation, you can examine the
exact differences between your local file and the HEAD revision file;
The Compare view contains two editors. Edits are allowed only in the left editor and only when it contains the working
copy file. To learn more about how the view can be used in the day by day work see View differences.
Compare View Toolbar
The list of actions available in the Compare view toolbar include:
Save action
Saves the content of the left editor when it can be edited.
Perform Files Differencing
Performs a comparison between the source file and target file.
Ignore Whitespaces
Enables or disables the whitespace ignoring feature. Ignoring whitespace means that before performing the
comparison, the application normalizes the content and trims its leading and trailing whitespaces.
Synchronized scrolling
Synchronizes scrolling so that a selected difference can be seen on both sides of the application window. This action
enables/disables the previously described behavior.
Format and Indent Both Files (Ctrl Shift P (Meta Shift P on OS X))
Formats and indents both files before comparing them. Use this option for comparisons that contain long lines that
make it difficult to spot differences.
Next Block of Changes (Ctrl Period (Meta Period on OS X))
Jumps to the next block of changes. This action is disabled when the cursor is positioned on the last change block
or when there are no changes.
Note: A change block groups one or more consecutive lines that contain at least one change.
Copy Change from Right to Left
Copies the selected difference from the target file in the right side to the source file in the left side.
Copy All Changes from Right to Left
Copies all changes from the target file in the right side to the source file in the left side.
Previous Block of Changes (Ctrl Comma (Meta Comma on OS X))
Jumps to the previous block of changes. This action is disabled when the cursor is positioned on the first change
block or when there are no changes.
Next Change (Ctrl Shift Period (Meta Shift Period on OS X))
Jumps to the next change from the current block of changes. When the last change from the current block of changes
is reached, it highlights the next block of changes. This action is disabled when the cursor is positioned on the last
change or when there are no changes.
Previous Change (Ctrl Shift Comma (Meta Shift M on OS X))
Jumps to the previous change from the current block of changes. When the first change from the current block of
changes is reached, it highlights the previous block of changes. This action is disabled when the cursor is positioned
on the first change or when there are no changes.
First Change (Ctrl B (Meta B on OS X))
Jumps to the first change.
Most of these actions are also available from the Compare menu.
The path to the file external must be in a working copy that is already checked out. While directory externals can
place the external directory at any depth and it will create any intermediate directories, file externals must be placed
into a working copy that is already checked out.
The external file URL must be in the same repository as the URL that the file external will be inserted into;
inter-repository file externals are not supported.
While commits do not descend into a directory external, a commit in a directory containing a file external will commit
any modifications to the file external.
File externals cannot be moved or deleted; the svn:externals property must be modified instead; however, file
externals can be copied.
Add a new property - This button invokes the Add property dialog box in which you can specify the property
name and value.
Edit property - This button invokes the Edit property dialog box in which you can change the property value
and also see its original(base) value.
Remove property - This button will prompt a dialog box to confirm the property deletion. You can also specify
if you want to remove the property recursively.
Refresh - This action will refresh the properties for the current resource.
Console View
The Console View shows the traces of all the actions performed by the application. Part of the displayed messages
mirror the communication between the application and the Apache Subversion server. The output is expressed as
subcommands to the Subversion server and simulates the Subversion command-line notation. For a detailed description
of the Subversion console output read the SVN User Manual.
The view has a simple layout, with most of its space occupied by a message area. On its right side, there is a toolbar
holding the following buttons:
Clear
Erases all the displayed messages.
Lock scroll
Disables the automatic scrolling when new messages are appended in the view.
The maximum number of lines displayed in the console (length of the buffer) can be modified in the Preferences page.
By default this value is set to 100.
Dynamic Help View
Dynamic Help view is a help window that changes its content to display the help section that is specific to the currently
selected view. As you change the focused view, you are able to read a short description of it and its functionality.
icon for a resource removed and replaced with another one on the repository and a orange background.
Absolute Paths - In most cases, the Oxygen XML Editor expects absolute paths for local file system items.
Relative Paths - The Oxygen XML Editor only accepts relative paths in the form ~[/...], where ~ is the user
home directory.
Path Validation - Oxygen XML Editor validates the path as you type and invalid text becomes red.
Local Repository Paths - You can use local paths (absolute or relative) to access local repositories. When you use
the Browse button, the Oxygen XML Editor will convert the file path to a file:// form of URL, provided that
the location is a real repository.
Absolute Paths - In most cases, the Oxygen XML Editor expects absolute paths for local file system items.
Relative Paths - The Oxygen XML Editor only accepts relative paths in the form ~[/...], where ~ is the user
home directory.
Peg Revisions - For URL text boxes found inside dialog boxes where you are pulling information from the repository,
you can use peg revisions at the end of the URLs (for example, URL@rev1234).
Note: If you try to use a peg revision number in a dialog box where you are sending information to the
repository then the peg revision number will become part of the name of the item rather than searching for
the specified revision. For example, in the URL http://host/path/inside/repo/item@100, the
item name is considered to be item@100.
Tip: You can even use peg revisions with local repository paths. For example,
C:\path\to\local\repo@100 will be converted to file:///C:/path/to/local/repo@100
and the Repository browser will display the content of the local repository as it is at revision 100.
URL Validation - Oxygen XML Editor validates the URLs as you type and invalid text becomes red. Even paths to
local repositories are not accepted unless using the Browse button to convert them to valid URLs.
Drag and Drop - You can drag URLs from other applications or text editors and drop them into the URL text box.
You can also drag folders that point to local repositories, from the local file system or from other applications, and
they are automatically converted to valid file:// type URLs.
Automatic Use of Clipboard Data - If the URL text box is empty when its dialog box is opened, any data that is
available in the system clipboard is used, provided that it is valid for that text box. Even valid local paths will be
automatically converted to file:// type URLs.
Note: The text boxes that are in the form of a combo box also allow you to select previously used URLs, or
URLs defined in the Repositories view.
Technical Issues
This section contains special technical issues found during the use of Syncro SVN Client.
Authentication Certificates Not Saved
If Syncro SVN Client prompts you to enter the authentication certificate, although you already provided it in a previous
session, then you should make sure that your local machine user account has the necessary rights to store certificate files
in the Subversion configuration folder (write access to Subversion folder and all its subfolders). Usually, it is located in
the following locations:
Windows: [HOME_DIR]\AppData\Roaming\Subversion
Mac OS X and Linux: [HOME_DIR]/.subversion
You are running Oxygen XML Editor with Java 1.6 or older.
The repository is set to use only one of the SSLv3 or TLSv1 encryption protocols.
To solve this issue, set the HTTPS encryption protocols option to SSLv3 only or TLSv1 only (depending on the
repository configuration).
Accessing Old Items from a Repository
Usually, you point to an item from a repository using a URL. However, sometimes this might not be enough, because
the URL alone might point to a different item than the one you want and a peg revision is needed.
A Subversion repository tracks any change made to its items by using revisions, which contain information like the
name of the author who made the changes, the date when they were made, and a number that uniquely identifies each
of them. During time, an item from a specific location in a repository evolves as a result of committing different changes
to it. When an item is deleted, its entire life cycle (all changes made to it, from the moment it was created) still remains
recorded in the history of the repository. If a new item is created, with the same name and in the same location of the
repository as a previously existing one, then both items are identified by the same URL even though they are located in
different time frames. This is when a peg revision comes in handy. A peg revision is nothing more than a normal revision,
but the difference between them is made by their usage. Many of the Subversion commands accept also a peg revision
as a way to precisely identify an item in time, beside an operative revision (the revision we are interested in, regarding
the used command).
To illustrate an example, consider the following:
If we use a revision number less than 10, an error is triggered, because the file has not been created
yet.
If we use a revision number between 10 and 19, we will obtain the specific version we are interested
in.
Note: Although the file was modified in revisions 12, 15, 17, it existed in
all revisions between 10 and 19. Starting with a revision at which the file is
modified, it has the same content across all revisions generated in the repository
until another revision in which it is modified again.
At this point, we delete the file, creating revision 20. Now, we cannot access any version of the file,
because it does not exist anymore in the latest repository revision. This is due to the fact that Subversion
automatically uses the HEAD revision as a peg revision (it assumes any item currently exists in the
repository if not instructed otherwise). However, using any of the revision numbers from the 10-19
interval (when the file existed) as a peg revision (beside the operative revision), will help Subversion
to properly identify the time frame when the file existed, and access the file version corresponding to
the operative revision. If we use a revision number greater than 19, this will also trigger an error.
Continuing our example, suppose that at revision 30 we create a directory called config in the same
repository location as our deleted file. This means that our new directory will be identified by the
same repository address: http://host.com/myRepository/dir/config. If we use only
this URL in any Subversion command, we will access the new directory. We will also access the same
directory if we use as peg revision any revision number equal with or greater than 30. However, if
we are interested in accessing an old version of the previously existing file, then we must use as a peg
revision one of the revisions at which it existed (10-19), just like in the previous case.
Checksum Mismatch Error
A Checksum Mismatch error could happen if an operation that sends or retrieves information from the repository to the
working copy is interrupted. This means that there is a problem with the synchronization between a local item and its
corresponding remote item.
If you encounter this error, try the following:
1. Identify the parent directory of the file that caused the error (the file name should be displayed in the error message).
Note: If the parent directory is the root of the working copy or if it contains a large amount of items it is
recommended that you check out the working copy again, rather than continuing with the rest of this procedure.
2. Identify the current depth of that directory.
3. Update the parent directory using the Update to revision/depth action that is available from the contextual menu
or the Working copy menu.
a. For the Depth option, select This folder only (empty).
Warning: If you have files with changes in this directory, those changes could be lost. You should
commit your changes or move the files to another directory outside the working copy prior to proceeding
with this operation.
4. After clicking OK the contents of the directory will be erased and the directory is be marked as having an empty
depth.
5. Once again, update the same directory using the Update to revision/depth action.
a. This time, for the Depth option, select the depth that was previously identified in step 2.
Tree Editor
The Tree Editor (Tools > Tree Editor) is used for editing the content of a document displayed as an XML tree. The
workspace offers the following functional areas:
Main menu - Provides access to all the features and functions available in Oxygen XML Editor Tree Editor perspective.
Toolbar - Provides easy access to common and frequently used functions. Each icon is a button that acts as a shortcut
to a related function.
Editor panel - Easy editing of structured mark-up documents. Each token has an associated icon for easier visual
identification.
Model view - Shows the detailed information about the attribute or element that you are working on.
All Elements panel - Presents a list of all defined elements that can be inserted within your document.
The tree editor does not offer entity support. Entities are not presented with a special type of node in the tree and new
entity nodes cannot be inserted in the document.
Directories Comparison
The Compare Directories tool allows you to compare and manage changes to files and folders within the structure of
your directories. The utility is available from the Tools menu or can be opened as a stand-alone application from the
Oxygen XML Editor installation folder (diffDirs.exe).
The directories comparison results are presented as a tree of files and directories. The directories and folders that contain
files that differ are expanded automatically so that you can focus directly on the differences. You can merge the contents
of the directories by using the copy actions. If you double-click (or press Enter) on a line with a pair of files, Oxygen
XML Editor starts a file comparison between the two files, using the Compare Files tool.
Note: The comparison is only available for file type associations that are known by Oxygen XML Editor.
Perform Directories Differencing - Looks for differences between the two directories displayed in the left
and right side of the application window.
Perform Files Differencing - Compares the currently selected files.
Copy Change from Right to Left - Copies the selected change from the right side to the left side (if there is
no file/folder in the right side, the left file/folder is deleted).
Copy Change from Left to Right - Copies the selected change from the left side to the right side (if there is
no file/folder in the left side, the right file/folder is deleted).
Options Menu
Menu Shortcut Keys - Opens the Menu Shortcut Keys option page where you can configure keyboard shortcuts
available for menu items.
Reset Global Options - Resets options to their default values. Note that this option appears only when the tool is
executed as a stand-alone application.
Import Global Options - Allows you to import an options set that you have previously exported.
Export Global Options - Allows you to export the current options set to a file.
Help Menu
The Help menu contains the following actions:
Help (F1)
Opens a Help dialog box that displays the User Manual at a section that is appropriate for the context of the current
cursor position.
Use Online Help
If this option is enabled, when you select Help or press F1 while hovering over any part of the interface, Oxygen
XML Editor attempts to open the help documentation in online mode. If this option is disabled or an internet
connection fails, the help documentation is opened in offline mode.
Report problem
Opens a dialog box that allows the user to write the description of a problem that was encountered while using the
application. You can change the URL where the reported problem is sent by using the
com.oxygenxml.report.problems.url system property. The report is sent in XML format through the
report parameter of the POST HTTP method.
Support Center
Opens the Oxygen XML Editor Support Center web page in a browser.
Compare Toolbar of the Compare Directories Tool
The toolbar contains the following actions:
An X symbol, when a file or a folder exists in only one of the compared directories.
A symbol, when a file exists in both directories but the content differs. The same sign appears when a collapsed
folder contains differing files.
The color used for the symbol and the directory or file name can be customized in the Directories Comparison /
Appearance preferences page. You can double-click lines marked with the symbol to open a Compare Files window,
which shows the differences between the two files.
Compare Images
If you double-click a line containing two different images, the Compare images window is displayed. This dialog box
presents the images in the left and right sides, scaled to fit the available view area. You can use the contextual menu
actions to scale the images to their original size or scale them down to fit in the view area.
The supported image types are: GIF, JPG, JPEG, PNG, and BMP.
Files Comparison
The Compare Files tool can be used to compare files or XML file fragments. The utility is available from the Tools
menu or can be opened as a stand-alone application from the Oxygen XML Editor installation folder (diffFiles.exe).
Using the
Browse drop-down menu, open a file in the left side of the dialog box, and the file you want to compare
it to in the right side. To highlight the differences between the two files, click the
Perform File Differencing button.
The line numbers on each side help you to quickly identify the locations of the differences.
To compare XML file fragments, you need to copy and paste the fragments you want to compare into each side, without
selecting a file. If a file is already selected, you need to close it, using the
button, before pasting the fragments.
You can edit both the source and the target file. The differences are refreshed when you save the modified document.
Auto - selects the most appropriate algorithm, based on the compared content and its size (selected by default).
Syntax Aware - computes differences for file types or XML fragments that are known by Oxygen XML Editor.
XML Fast - works well on large files or fragments at the expense of accuracy.
XML Accurate - works best on small XML files or fragments and offers accurate results, at the expense of speed.
Source >
Source >
Open URL - Opens the URL to be used as a source file. See Open URL for details.
Source >
Open File from Archive - Browses an archive content for a source file.
Source >
Save - Saves the changes made in the source file.
Source > Save As - Displays the Save As dialog box that allows you to save the source file with a new name.
Target
The file that is displayed in the right side of the application window.
Target >
Target >
Open URL - Opens the URL to be used as a target file. See Open URL for details.
Target >
Open File from Archive - Browses an archive content for a target file.
Target >
Save - Saves the changes made in the target file.
Target > Save As - Displays the Save As dialog box that allows you to save the target file with a new name.
Exit
Quits the application.
Edit Menu
The following actions are available in the Edit menu:
Cut
Cut the selection from the currently focused Compare editor to the clipboard.
Copy
Copy the selection from the currently focused Compare editor to the clipboard.
Paste
Paste content from the clipboard into the currently focused Compare editor.
Undo
Undo changes in the currently focused Compare editor.
Redo
Redo changes in the currently focused Compare editor.
Find Menu
The Find menu actions are as follows:
Find/Replace
Perform find/replace operations in the currently focused Editor.
Find Next
Go to the next match using the same options as the last find operation. This action runs in both editor panels.
Menu Shortcut Keys - Opens the Menu Shortcut Keys option page where you can configure keyboard shortcuts
available for menu items.
Reset Global Options - Resets options to their default values. Note that this option appears only when the tool is
executed as a stand-alone application.
Import Global Options - Allows you to import an options set that you have previously exported.
Export Global Options - Allows you to export the current options set to a file.
Help Menu
The Help menu contains the following actions:
Help (F1)
Opens a Help dialog box that displays the User Manual at a section that is appropriate for the context of the current
cursor position.
Use Online Help
If this option is enabled, when you select Help or press F1 while hovering over any part of the interface, Oxygen
XML Editor attempts to open the help documentation in online mode. If this option is disabled or an internet
connection fails, the help documentation is opened in offline mode.
Report problem
Opens a dialog box that allows the user to write the description of a problem that was encountered while using the
application. You can change the URL where the reported problem is sent by using the
com.oxygenxml.report.problems.url system property. The report is sent in XML format through the
report parameter of the POST HTTP method.
Support Center
Opens the Oxygen XML Editor Support Center web page in a browser.
Compare Toolbar of the Compare Files Tool
This toolbar contains the operations that can be performed on the source and target files or XML fragments.
Auto - Selects the most appropriate algorithm, based on the compared content and its size (selected by default).
Lines - Computes the differences at line level, meaning that it compares two files or fragments looking for
identical lines of text. Once identical lines are found, it is considered a match. The content that precedes the
match is considered to be a difference and marked accordingly. The algorithm then continues to look for matching
lines.
Syntax Aware - Computes differences for known file types or XML fragments. Known file types include those
listed in the New dialog box, such as XML file types (XSLT files, XSL-FO files, XSD files, RNG files, NVDL
files, etc.), XQuery file types (.xquery, .xq, .xqy, .xqm extensions), DTD file types (.dtd, .ent, .mod
extensions), TEXT file type (.txt extension), or PHP file type (.php extension).
When comparing XML files or fragments, a token can be one of the following:
When comparing plain text, a token can be any continuous sequence of characters or any continuous sequence
of whitespaces, including a new line character.
XML Fast - Comparison that works well on large files or fragments, but it is less precise than XML Accurate.
XML Accurate - Comparison that is more precise than XML Fast, at the expense of speed.
Diff Options
Opens the Files Comparison page.
Perform directories differencing
Looks for differences between the two directories displayed in the left and right side of the application window.
Ignore Whitespaces
Enables or disables the whitespace ignoring feature. Ignoring whitespace means that before performing the
comparison, the application normalizes the content and trims its leading and trailing whitespaces.
Synchronized scrolling
Synchronizes scrolling so that a selected difference can be seen on both sides of the application window. This action
enables/disables the previously described behavior.
Format and Indent Both Files (Ctrl Shift P (Meta Shift P on OS X))
Formats and indents both files before comparing them. Use this option for comparisons that contain long lines that
make it difficult to spot differences.
Copy Change from Right to Left
Copies the selected difference from the target file in the right side to the source file in the left side.
Copy All Changes from Right to Left
Copies all changes from the target file in the right side to the source file in the left side.
Next Block of Changes (Ctrl Period (Meta Period on OS X))
Jumps to the next block of changes. This action is disabled when the cursor is positioned on the last change block
or when there are no changes.
Note: A change block groups one or more consecutive lines that contain at least one change.
Previous Block of Changes (Ctrl Comma (Meta Comma on OS X))
Jumps to the previous block of changes. This action is disabled when the cursor is positioned on the first change
block or when there are no changes.
Browse
Browse for local - Opens a dialog box to browse for files in your local file system.
Browse for remote - Opens the Open URL dialog box to browse for remote files.
Browse for archive - Opens the Archive Browser dialog box to browse for archives.
Browse Data Source Explorer - Opens the Data Source Explorer dialog box to browse database sources.
Search for file - Opens the Find Resource dialog box for advanced search capabilities.
The comparison tool keeps track of the files you are currently working with and those that you opened in this window.
You can see and select them from the two combo boxes.
You can also save the changes in either file by clicking the corresponding Save button.
You can close compared files by using the Close button. To compare XML fragments you need to close the compared
files in order to copy and paste the fragments into each side of the panel.
File Contents Panel
Selected files are opened in two side-by-side editors. A text perspective is used to offer a better view of the differences.
You can also compare XML fragments by copying and pasting them into both sides of the panel, without selecting files.
To compare XML fragments, if files are already opened you need to close them in order to paste the fragments into the
panels.
The two editors are constantly kept in sync. Therefore, if you scroll through the text in one side, the other one also scrolls
to show the differences side-by-side. The differences are indicated with highlights connected through colored areas. To
navigate through differences, do one of the following:
You can edit the content in either side of the editor and the differences are refreshed when you save the modified
document. If you save modified fragments, rather than a file, a dialog box opens that allows you to save the changes as
a new document.
If the compared blocks of text are too large and you want to see the differences at a more fine-tuned level, you can
choose options in the Compare menu to do a word level comparison or character level comparison.
Word Level Comparison
This option is only available if differences exist between the source and the target file. You can do a word level comparison
by selecting the Show word level details option from the Compare menu.
A digital signature must provide a way to verify that the data has not been modified or replaced to ensure integrity.
The signature must provide a way to establish the identity of the data's signer for authentication.
The signature must provide the ability for the data's integrity and authentication to be provable to a third party for
non-repudiation.
A public key system is used to create the digital signature and it's also used for verification. The signature binds the
signer to the document because digitally signing a document requires the originator to create a hash of the message and
then encrypt that hash value with his own private key. Only the originator has that private key and he is the only one
that can encrypt the hash so that it can be unencrypted using his public key. The recipient, upon receiving both the
message and the encrypted hash value, can decrypt the hash value, knowing the originator's public key. The recipient
must also try to generate the hash value of the message and compare the newly generated hash value with the unencrypted
hash value received from the originator. If the hash values are identical, it proves that the originator created the message,
because only the actual originator could encrypt the hash value correctly.
XML Signatures can be applied to any digital content (data object), including XML (see W3C Recommendation,
XML-Signature Syntax and Processing ). An XML Signature may be applied to the content of one or more resources:
Enveloped or enveloping signatures are applied over data within the same XML document as the signature
Detached signatures are applied over data external to the signature element; the signature is "detached" from the
content it signs. This definition typically applies to separate data objects, but it also includes the instance where the
signature and data object reside within the same XML document but are sibling elements.
The XML Signature is a method of associating a key with referenced data. It does not normatively specify how keys
are associated with persons or institutions, nor the meaning of the data being referenced and signed.
The original data is not actually signed. Instead, the signature is applied to the output of a chain of canonicalization and
transformation algorithms, which are applied to the data in a designated sequence. This system provides the flexibility
to accommodate whatever "normalization" or desired preprocessing of the data that might be required or desired before
subjecting it to being signed.
To canonicalize something means to put it in a standard format that everyone generally uses. Since the signature is
dependent on the content it is signing, a signature produced from a non-canonicalized document could possibly be
different from one produced from a canonicalized document. The canonical form of an XML document is physical
representation of the document produced by the method described in this specification. The term canonical XML refers
to XML that is in canonical form. The XML canonicalization method is the algorithm defined by this specification that
generates the canonical form of a given XML document or document subset. The term XML canonicalization refers to
the process of applying the XML canonicalization method to an XML document or document subset. XML
canonicalization is designed to be useful to applications that require the ability to test whether the information content
of a document or document subset has been changed. This is done by comparing the canonical form of the original
document before application processing with the canonical form of the document result of the application processing.
A digital signature over the canonical form of an XML document or document subset would allows the signature digest
calculations to be oblivious to changes in the original document's physical representation. During signature generation,
the digest is computed over the canonical form of the document. The document is then transferred to the relying party,
which validates the signature by reading the document and computing a digest of the canonical form of the received
document. The equivalence of the digests computed by the signing and relying parties (and hence the equivalence of
the canonical forms over which they were computed) ensures that the information content of the document has not been
altered since it was signed.
The following canonicalization algorithms are used in Oxygen XML Editor: Canonical XML (or Inclusive XML
Canonicalization)(XMLC14N) and Exclusive XML Canonicalization(EXCC14N). The first is used for XML where the
context doesn't change while the second was designed for canonicalization where the context might change.
Inclusive Canonicalization copies all the declarations, even if they are defined outside of the scope of the signature, and
all the declarations you might use will be unambiguously specified. Inclusive Canonicalization is useful when it is less
Canonicalizing Files
You can select the canonicalization algorithm to be used for a document from the dialog box that is displayed by using
the Canonicalize action that is available from the Source submenu when invoking the contextual menu in Text mode
or from the Tools menu.
Input URL - Available if the Canonicalize action was selected from the Tools menu. It allows you to specify the
location of the input file.
Exclusive - If selected, the exclusive (uncommented) canonicalization method is used.
Note: Exclusive Canonicalization just copies the namespaces you are actually using (the ones that are a part
of the XML syntax). It does not look into attribute values or element content, so the namespace declarations
required to process these are not copied. This is useful if you have a signed XML document that you want
to insert into other XML documents (or you need self-signed structures that support placement within different
XML contexts), as it will ensure the signature is verified correctly each time.
Inclusive with comments - If selected, the inclusive with comments canonicalization method is used.
XPath - The XPath expression provides the fragments of the XML document to be signed.
Output - Available if the Canonicalize action was selected from the Tools menu. It allows you to specify the output
file path where the signed XML document will be saved.
Open in editor - If checked, the output file will be opened in the editor.
Certificates
A certificate is a digitally signed statement from the issuer (an individual, an organization, a website or a firm), saying
that the public key (and some other information) of some other entity has a particular value. When data is digitally
signed, the signature can be verified to check the data integrity and authenticity. Integrity means that the data has not
been modified. Authenticity means the data comes indeed from the entity that claims to have created and signed it.
Certificates are kept in special repositories called keystores.
A keystore is an encrypted file that contains private keys and certificates. All keystore entries (key and trusted certificate
entries) are accessed via unique aliases. An alias must be assigned for every new entry of either a key or certificate as
a reference for that entity. No keystore can store an entity if its alias already exists in that keystore and cannot store
trusted certificates generated with keys in its keystore.
In Oxygen XML Editor there are provided two types of keystores: Java Key Store (JKS) and Public-Key Cryptography
Standards version 12 (PKCS-12). A keystore file is protected by a password. In a PKCS 12 keystore you should not
store a certificate without alias together with other certificates, with or without alias, as in such a case the certificate
without alias cannot be extracted from the keystore.
To configure the options for a certificate or to validate it, open the Preferences dialog box and go to XML > XML
Signing Certificates. This opens the certificates preferences page.
Signing Files
You can select the type of signature to be used for documents from a signature settings dialog box. To open this dialog
box, select the Sign action from the Source submenu when invoking the contextual menu in Text mode or from the
Tools menu.
Input - Available if the Sign action was selected from the Tools menu. Specifies the location of the input URL.
Transformation Options - See the Digital Signature Overview section for more information about these options.
Exclusive with comments - If selected, the exclusive with comments canonicalization method is used.
Inclusive - If selected, the inclusive (uncommented) canonicalization method is used.
Note: Inclusive Canonicalization copies all the declarations, even if they are defined outside of the scope
of the signature, and all the declarations you might use will be unambiguously specified. Inclusive
Canonicalization is useful when it is less likely that the signed data will be inserted in other XML document
and it is the safer method from the security perspective because it requires no knowledge of the data that
are to be secured in order to safely sign them. A problem may occur if the signed document is moved
Inclusive with comments - If selected, the inclusive with comments canonicalization method is used.
XPath - The XPath expression provides the fragments of the XML document to be signed.
ID - Provides ID of the XML element to be signed.
Envelope - If selected, the enveloped signature is used. See the Digital Signature Overview for more information.
Detached - If selected, the detached signature is used. See the Digital Signature Overview for more information.
Append KeyInfo - If this option is checked, the ds:KeyInfo element will be added in the signed document.
Signature algorithm - The algorithm used for signing the document. The following options are available: RSA
with SHA1, RSA with SHA256, RSA with SHA384, and RSA with SHA512.
Output - Available if the Sign action was selected from the Tools menu. Specifies the path of the output file where
the signed XML document will be saved.
Open in editor - If checked, the output file will be opened in Oxygen XML Editor.
The menu bar provides menu driven access to all the features and functions that are available in Large File Viewer:
The status bar provides information about the current opened file path, the Unicode representation of the character
at cursor position and the line and column in the opened document where the cursor is located.
Attention: For faster computation the Large File Viewer uses a fixed font (plain, monospace font of size 12)
to display characters. The font is not configurable from the Preferences page.
Tip: The best performance of the viewer is accomplished for encodings that use a fixed number of bytes per
character, like UTF-16 or ASCII. The performance for UTF-8 is very good for documents that use mostly
characters of the European languages. For the same encoding the rendering performance is high for files consisting
of short lines (up to a few thousand characters) and may degrade for long lines.
Hex Viewer
When the Unicode characters that are visible in a text viewer or editor are not enough and you need to see the byte values
of each character of a document, you can start the Hex Viewer that is available on the Tools menu. It has two panels:
the characters are rendered in the right panel and the bytes of each character are displayed in the left panel. There is a
1:1 correspondence between the characters and their byte representation: the byte representation of a character is displayed
in the same matrix position of the left panel as the character in the matrix of the right panel.
Zoom out
To zoom in on an image, use any of the following methods:
Rotate
To rotate an image, use either of the following methods:
Refresh
To refresh (or reset) an image, use either of the following methods:
Move
To move an image, use either of the following methods:
Pan
To pan an image, click and drag the image with your mouse.
Chapter
20
Configuring Oxygen XML Editor
Topics:
Preferences
Configuring Options
Importing / Exporting Global
Options
Reset Global Options
Configuring the Layout of the
Views and Editors
Configure Toolbars
Scenarios Management
Editor Variables
Custom System Properties
Localizing the User Interface
Setting a Java Virtual Machine
Parameter in the Launcher
Configuration File / Start-up Script
This chapter presents all the user preferences and options that allow you to
configure various features, or the application itself, and the editor variables that
are available for customizing the user-defined commands.
Preferences
You can configure Oxygen XML Editor options using the Preferences dialog box.
To open the preferences dialog box, go to Options > Preferences.
You can select the preference page you are interested in from the tree on the left of the Preferences dialog box. You
can filter the tree by typing in the filter box above the tree.
Global Preferences
The global options cover a number of aspects of the overall operation of Oxygen XML Editor. To configure the Global
options, open the Preferences dialog box and go to Global.
The following options are available in the Global preferences page:
Line separator - This option sets the line separator used when saving files. Use System Default to select the normal
line separator for your OS. If you want the existing file separator of a file to be maintained, regardless of your current
OS, check Detect the line separator on file open.
Detect the line separator on file open - When this option is selected, the editor detects the line separator when a
file is loaded and it uses it when the file is saved. New files are saved using the line separator defined by theLine
separator option.
Default Internet browser - This option sets the Web browser that Oxygen XML Editor will use to do the following:
If you leave this setting blank, the system default browser will be used.
Open last edited files from project - When this option is enabled,Oxygen XML Editor opens the files you had open
the last time you used a project whenever you open the application or switch to that project.
Beep on operation finished - When this option is selected, Oxygen XML Editor beeps when a validation or transform
action ends. Different tones are used for success and failure. The tones used may depend on your operating system's
sound settings.
Show memory status - When this option is selected, the memoryOxygen XML Editor uses is displayed in the status
bar. To free memory, click the
Free unused memory button located at the right side of the status bar. The memory
status bar turns yellow or red when Oxygen XML Editor uses too much memory. You can change the amount of
memory available to Oxygen XML Editor by changing the parameters of the application launcher.
Check opened files for file system changes - When this option is selected, Oxygen XML Editor checks the content
of the all opened editors to see if they have been updated by another application. If the file has changed, Oxygen
XML Editor will ask you if you want to reload the file.
Auto update unmodified editors on file system changes - If this option is selected, Oxygen XML Editor
automatically updates unmodified editors if the edited file changes externally.
Show Java vendor warning at startup - If this option is selected, Oxygen XML Editor displays a warning on
startup if a non-recommended version of the Java virtual machine is being used.
File Chooser Dialog - This options sets the directory that will be shown when the Open file dialog box is displayed.
Show hidden files and directories - If this option is selected, Oxygen XML Editor shows system hidden files and
folders in the file browser dialog box and the folder browser dialog box. This setting is not available on OS X.
Appearance Preferences
This preferences page contains various options that allow you to change the appearance of the user interface of Oxygen
XML Editor. To configure the Appearance options, open the Preferences dialog box and go to Appearance.
The following options are available in the Appearance preferences page:
Look and Feel
This option allows you to change the graphic style (look and feel) of the user interface. Depending on the operating
system, you can choose between various predefined style options.
Theme
This option allows you to choose predefined color themes that will be applied over the entire user interface. You
can select between the following:
You can also change various appearance related options in other preference pages for the selected theme by clicking
on the various links in this section. The result of the applied modifications is displayed in the XML Syntax Highlight
Preview area.
Custom Themes
You can also create custom themes to share with others or use in other installations of Oxygen XML Editor. To
create a custom theme, follow these steps:
1. Select a Theme to use as a base.
2. Configure the desired options in any of the option pages listed in this preferences page.
3. Click Export and specify a name for your custom theme. If you save the theme to the default file path, your
custom theme will immediately appear in the Theme drop-down list. Otherwise, if you save it to another
location, you can use the Import button to make it appear in the drop-down list.
Note: In OS X (starting with Yosemite), if you choose Graphite for the Theme, it is recommended that you
enable the Use dark menu and Dock option that is found in System Preferences > General.
Note: In Windows, if a high contrast theme is detected, and the Look and Feel option is set to Default or
Windows and the Theme option is set to Classic, Oxygen XML Editor inherits the high contrast theme
colors that are set in the operating system.
Reset
Resets the theme to its default values (this option is available when the theme is modified).
Rename
Changes the name of the theme (not available for default or predefined themes).
Delete
Removes the selected theme (not available for default or predefined themes).
Import
Allows you to import a color theme from an XML theme file. You can use this option to load an exported custom
theme.
Export
Allows you to export the current color theme into an XML theme file that can then be shared with others or imported
into another installation of Oxygen XML Editor.
Colors Preferences
Oxygen XML Editor allows you configure the colors for frames, dialog boxes, controls, and commands. To configure
the Colors, open the Preferences dialog box and go to Appearance > Colors.
Text antialiasing
This option allows you to set the text anti-aliasing behavior:
Default - Allows the application to use the setting of the operating system, if available.
On - Sets the text anti-aliasing to pixel level.
Off - Disables text anti-aliasing.
Sub-pixel anti-aliasing modes, such as GASP, LCD_HRGB, LCD_HBGR, LCD_VRGB, and LCD_VBGR.
Text components
This option allows you to choose the font to be used in text boxes within the interface.
GUI
This option allows you to choose the font to be used for user interface labels.
Note: You must restart the application for your changes to be applied.
Default - Uses the default layout for all perspectives. Any modification of this layout (such as closing views,
displaying views, or a new view arrangement) is saved on exit and reloaded at start-up.
Predefined - Allows you to choose one of the predefined layouts:
Custom - Allows you to specify a custom layout to be used. You can save your preferred layout using Window >
Export Layout, then enter the location of the saved layout file in this setting.
Reset layout at startup - When this option is enabled, Oxygen XML Editor forgets any changes made to the
layout during a session and reloads the default layout the next time it is started. This is useful when you want to
keep a fixed layout from one session to another.
Remember layout changes for each project - When this options is enabled, Oxygen XML Editor saves layouts
individually for each project. When you switch projects, the layout you last used for that project is loaded
automatically.
Allow detaching editors from main window - When this options is enabled, you can drag and drop an editor window
outside of the main screen. This is useful especially when you are using two monitors and you want to view files
side by side.
Note: If the main screen is maximized, you cannot drag and drop an editor outside of it.
The changes you make to any layout are preserved between working sessions. The predefined layout files are saved in
the preferences directory of Oxygen XML Editor.
To watch our video demonstration about configuring the user interface of Oxygen XML Editor, go to
http://oxygenxml.com/demo/Dockable_Views.html.
Add-ons Preferences
You can use add-ons to enhance the functionality of Oxygen XML Editor. To configure the Add-ons options, open the
Preferences dialog box and go to Add-ons. The following options are available in the Add-ons preferences page:
Enable automatic updates checking - When this option is selected, Oxygen XML Editor will search for available
updates automatically.
Add-on Sites URLs - This is a list of the URLs for the add-on sites. You can add, edit, and delete sites in this list.
Namespace - Specifies the namespace of the root element from the association rules set (* (any) by default). If
you want to apply the rule only when the root element has no namespace, leave this field empty (remove the
ANY_VALUE string).
Root local name - Specifies the local name of the root element (* (any) by default).
File name - Specifies the name of the file (* (any) by default).
Public ID - Represents the Public ID of the matched document.
Java class - Presents the name of the Java class, which is used to determine if a document matches the rule.
New
Opens a Document type configuration dialog box that allows you to add a new association.
Edit
Opens a Document type configuration dialog box that allows you to edit an existing association.
Note: If you try to edit an existing association type when you do not have write permissions to its store
location, a dialog box will be shown asking if you want to extend the document type.
Duplicate
Opens a Document type configuration dialog box that allows you to duplicate the configuration of an existing
document type association.
Extend
Opens a Document type configuration dialog box that allows you to extend an existing document type. You can
add or remove functionality starting from a base document type. All of these changes will be saved as a patch. When
the base document type is modified and evolves (for example, from one application version to another) the extension
will evolve along with the base document type, allowing it to use the new actions added in the base document type.
Internal preferences - The document type configuration is stored in the application Internal preferences.
Additional frameworks directories - The document type configuration is loaded from one of the specified Additional
frameworks directories list.
Add-ons - An add-on can contribute a framework. You can manage the add-ons locations in the Add-ons preferences
page.
The frameworks folder - The main folder containing framework configurations.
All loaded document type configurations are first sorted by priority, then by document type name and then by load
location (in the exact order specified above). When an XML document is opened, the application chooses the first
document type configuration from the sorted list which matches the specific document.
All loaded document type configurations are first sorted by priority, then by document type.
The Document Type Configuration Dialog Box
The Document type configuration dialog box allows you to create or edit a Document Type Association (framework).
The following fields are available in this dialog box:
You are able to configure the options of each framework in the following tabs:
Association rules
Schema
Classpath
Author
Templates
Catalogs
Transformation
Validation
Extensions
New.
Small icon - Allows you to select an image for the icon that Oxygen XML Editor uses for the contextual menu
action.
Note: If you are using a Retina or HiDPI display, Oxygen XML Editor automatically searches for higher
resolution icons in the path specified in both the Large icon and Small icon options. For more information, see
the Adding Retina/HiDPI Icons in a Framework section.
Shortcut key - This field allows you to configure a shortcut key for the action that you are editing. The + character
separates the keys. If the Enable platform-independent shortcut keys checkbox is enabled, the shortcut that you
specify in this field is platform-independent and the following modifiers are used:
M1 represents the Command key on MacOS X, and the Ctrl key on other platforms.
M2 represents the Shift key.
M3 represents the Option key on MacOS X, and the Alt key on other platforms.
M4 represents the Ctrl key on MacOS X, and is undefined on other platforms.
Operations
In this section of the Action dialog box, you configure the functionality of the action that you are editing. An action
has one or more operation modes. The evaluation of an XPath expression activates an operation mode. The first
enabled operation mode is activated when you trigger the action. The scope of the XPath expression must consist
only of element nodes and attribute nodes of the edited document. Otherwise, the XPath expression does not return
a match and does not fire the action. For more details see: Activation of Multiple Functions for Actions using XPath
Expressions on page 1158.
The following options are available in this section:
Operation priority - Increases or decreases the priority of an operation. The operations are invoked in the order of
their priority. If more than one XPath expression is true, the operation with the highest priority is invoked.
When this XPath expression is true - An XPath 2.0 expression that applies to elements and attributes. For more
details see:Activation of Multiple Functions for Actions using XPath Expressions on page 1158.
invoke the operation - Specifies the invoked operation.
with the arguments - Specifies the arguments of the invoked operation.
Edit - Allows you to edit the arguments of the operation.
Evaluate activation XPath expressions even in read-only cotnexts - If this checkbox is enabled, the action can
be invoked even when the cursor is placed in a read-only location.
The child element with the specified local name that belongs to the default namespace.
oxy:allows-child-element("para")
The above example verifies if the para element (of the default namespace) is allowed in the current context.
The child element with the local name specified by any namespace.
oxy:allows-child-element("*:para")
The above example verifies if the para element (of any namespace) is allowed in the current context.
A prefix-qualified name of an element.
oxy:allows-child-element("prefix:para")
The prefix is resolved in the context of the element where the cursor is located. The function matches on the
element with the para local name from the previous resolved namespace. If the prefix is not resolved to a
namespace, the function returns a value of false.
A specified namespace-URI-qualified name of an element.
oxy:allows-child-element("{namespaceURI}para")
The namespaceURI is the namespace of the element. The above example verifies if the para element (of the
specified namespace) is allowed in the current context.
Any element.
oxy:allows-child-element("*")
The above function verifies if any element is allowed in the current context.
Note: A common use case of oxy:allows-child-element("*") is in combination with the
attributeName parameter.
attributeName
The attribute of an element that you want to check if it is valid in the current context. Its value is a string that supports
the following forms:
The above example verifies if an element with the class attribute and the default value of this attribute (that
contains the topic/topic string) is allowed in the current context.
The attribute with the local name specified by any namespace.
oxy:allows-child-element("*", "*:localname", " topic/topic ")
The prefix is resolved in the context of the element where the cursor is located. If the prefix is not resolved to
a namespace, the function returns a value of false.
defaultAttributeValue
A string that represents the default value of the attribute. Depending on the value of the next parameter, the default
value of the attribute must either contain this value or be equal with it.
contains
An optional boolean. The default value is true. For the true value, the default value of the attribute must contain
the defaultAttributeValue parameter. If the value is false, the two values must be the same.
The oxy:current-selected-element() Function
This function returns the fully selected element. If no element is selected, the function returns an empty sequence.
oxy:current-selected-element()[self::p]/b
This example returns the b elements that are children of the currently selected p element.
Menu
In the Menu sub-tab you configure what framework specific actions appear in the Oxygen XML Editor menu. The
sub-tab is divided in two sections: Available actions and Current actions.
The Available actions section presents a table that displays the actions defined in the Actions sub-tab, along with their
icon, ID, and name. The Current actions section holds the actions that are displayed in the Oxygen XML Editor menu.
To add an action in this section as a sibling of the currently selected action, use the
an image in this section as a child of the currently selected action use the
Add as sibling button. To add an action in this section as a child of the currently selected action use the
Add as sibling button. To add an action in this section as a child of the currently
Add as sibling button. To add an action in this section as a child of the currently
Encoding Preferences
Oxygen XML Editor lets you configure how character encodings are recognized when opening files and which encodings
are used when saving files. To configure encoding options, open the Preferences dialog box and go to Encoding. The
following encoding options are available:
Fallback character encoding - Default character encoding of non-XML documents if their character encoding
cannot be determined from other sources (like, for example, specified in the document itself, or determined by the
file type).
Note: For certain document types, the following encoding detection rules are used:
For XML, DTD and CSS documents, Oxygen XML Editor tries to collect the character encoding from
the document. If no such encoding is found, then UTF-8 is used.
For JavaScript, JSON, SQL, XQuery, and RNC, the UTF-8 encoding is used.
UTF-8 BOM handling - This setting specifies how to handle the Byte Order Mark (BOM) when Oxygen XML
Editor saves a UTF-8 XML document:
Don't Write - do not save the BOM bytes. Loaded BOM bytes are ignored.
Write - save the BOM bytes.
Keep - do not alter the BOM declaration of the currently open file. This is the default option.
Note: The UTF-16 BOM is always preserved. UTF-32 documents have a big-endian byte order.
REPORT - displays an error identifying the character that cannot be represented in the specified encoding.
Unrecognized characters are rendered as an empty box. This is the default option.
IGNORE - the error is ignored and the character is not included in the document displayed in the editor.
Attention: If you edit and save the document, the characters that cannot be represented in the specified
encoding are dropped.
REPLACE - the character is replaced with a standard replacement character. For example, if the encoding is
UTF-8, the replacement character has the Unicode code FFFD, and if the encoding is ASCII, the replacement
character code is 63.
Editor Preferences
Oxygen XML Editor lets you configure how the editor appears. To configure the appearance of the text editor, open the
Preferences dialog box and go to Editor.
The following options are available:
Show SPACE marks - Makes the space character visible in the editor.
Can edit read only files - If this option is selected, Oxygen XML Editor will let you edit, but not save, a read-only
file. If the option is disabled, a warning message is displayed when you try to edit a read-only file.
Display quick-assist and quick-fix side hints - Displays the Quick Assist and Quick Fix icon in the editor's left
side line number stripe. Works both in the Text and Author edit modes.
Undo history size - Sets the maximum amount of undo operations you can perform in either of the editor modes
(Text, Author, Design, Grid).
Print Preferences
Oxygen XML Editor lets you configure how files are printed out of the editor. Note that these setting cover how files
are printed directly from Oxygen XML Editor itself, not how they are printed after the XML source has been transformed
by a publishing stylesheet. To configure the Print options, open the Preferences dialog box and go to Editor > Print.
This page allows you to customize the headers and footers added to a printed page when you print from the Text mode
or Author mode editors. These settings do not apply to the Grid and schema Design modes.
You can specify what is printed on the Left, Middle, and Right of the header and footer using plain text of any of the
following variables:
For example, to show the current page number and the total number of pages in the top right corner of the page, write
the following pattern in the Right text area of the Header section: ${cp} of ${tp}.
You can also set the Color and Font used in the header and footer. Default font is SansSerif.
You can place a line below the header or above the footer by selecting Underline/Overline.
Edit modes Preferences
Oxygen XML Editor lets you configure which edit mode a file is opened in the first time it is opened. This setting only
affects the first time a file is opened. The current editing mode of each file is saved when the file is closed and restored
the next time it is opened. To configure the Edit modes options, open the Preferences dialog box and go to Editor >
Edit modes .
If Allow Document Type specific edit mode setting to override the general mode setting is selected, the initial edit
mode setting set in the Document Type configuration dialog box overrides the general edit mode setting from the table
below.
The initial edit mode can be one of the following:
Text
Author
Grid
Design (available only for the W3C XML Schema editor).
Text Preferences
Oxygen XML Editor lets you configure how text mode editor appears. To configure the Text mode editor options, open
the Preferences dialog box and go to Editor > Edit modes > Text.
The following preferences are available:
Editor background color - Sets the background color of the Text editing mode, Diff Files editors and Outline
view.
Editor cursor color - Sets the color of the cursor.
Highlight current line - Sets the foreground color of the line numbers displayed in the editor panels.
Show line numbers - Shows line numbers in the editor panels and in the Results view of the Debugger perspective.
Show print margin - In conjunction with the Print margin column option, allows you to set a safe print limit in
the form of a vertical line displayed in the right side of the editor pane. You can also customize the print margin line
color.
Line wrap - Enables soft wrap of long lines, that is automatically wrap lines in edited documents. The document
content is unaltered as the application does not use newline characters to break long lines.
Note: When you enable the Line wrap option, Oxygen XML Editor disables the Highlight current line
option.
Cut / Copy whole line when nothing is selected - Enables the Cut and Copy actions when nothing is selected in
the editor. In this case the Cut and Copy actions operate on the entire current line.
Enable folding - Displays the vertical stripe that holds the folding markers.
Highlight matching tag - If you place the cursor on a start or end tag, Oxygen XML Editor highlights the
corresponding member of the pair. You can also customize the highlight color.
Lock the XML tags - Default tag locking state of the opened editors.
Diagram Preferences
For certain XML languages, Oxygen XML Editor provides a diagram view as part of the text mode editor. To configure
the Diagram preferences, open the Preferences dialog box and go to Editor > Edit modes > Text > Diagram.
The following options are available:
Show Full Model XML Schema diagram - When this option is selected, the Text mode editor for XML Schemas
is displayed with a split screen view that shows a diagram of the schema structure. This may be useful for seeing the
effect of schema changes you make in text view. For editing a the schema using diagram rather than text, use the
schema Design view.
Enable Relax NG diagram and related views - Enables the Relax NG schema diagram and synchronization with
the related views (Attributes, Model, Elements, Outline).
Enable NVDL diagram and related views - Enables the NVDL schema diagram and synchronization with the
related views (Attributes, Model, Elements, Outline).
Show Relax NG diagram - Displays the Relax NG schema diagram in Full Model View and Logical Model
View.
Show NVDL diagram - Displays the NVDL schema diagram in Full Model View and Logical Model View.
Location relative to editor - Allows you to specify the location of the schema diagram panel relative to the diagram
Text editor.
Grid Preferences
Oxygen XML Editor provides a Grid view of an XML document. To configure the Grid options, open the Preferences
dialog box and go to Editor > Edit modes > Grid.
The following options are available:
Compact representation - If selected, the compact representation of the grid is used: a child element is displayed
beside the parent element. In the non-compact representation, a child element is nested below the parent.
Format and indent when passing from grid to text or on save - If selected, the content of the document is formatted
and indented each time you switch from the Grid view to the Text view.
Default column width (characters) - Sets the default width in characters of a table column of the grid. A column
can hold:
Element names
Element text content
Attribute names
Attribute values
If the total width of the grid structure is too large you can resize any column by dragging the column margins with
the mouse pointer, but the change is not persistent. To make it persistent, set the new column width with this option.
Active cell color - Sets the background color for the active cell of the grid. There is only one active cell at a time.
The keyboard input always goes to the active cell and the selection always contains it.
Selection color - Background color for the selected cells of the grid except the active cell.
Border color - The color used for the lines that separate the grid cells.
Background color - The background color of grid cells that are not selected.
Foreground color - The text color of the information displayed in the grid cells.
Row header colors - Background color - The background color of row headers that are not selected.
Row header colors - Active cell color - The background color of the row header cell that is currently active.
Row header colors - Selection color - The background color of the header cells corresponding to the currently
selected rows.
Column header colors - Background color - The background color of column headers that are not selected.
Column header colors - Active cell color - The background color of the column header cell that is currently active.
Column header colors - Selection color - The background color of the header cells corresponding to the currently
selected columns.
The column headers are painted with two color gradients, one for the upper 1/3 part of the header and the other for the
lower 2/3 part. The start and end colors of the first gradient are set with the first two color buttons. The start and end
colors of the second gradient are set with the last two color buttons.
Break lines only after elements displayed as blocks, do not indent - Choose this option to instruct Oxygen
XML Editor to insert new lines only after elements that have a CSS display property set to anything other
than inline or none (for example, block, list-item, table, etc.) and indenting will not be used.
When selecting this option, the formatting is dictated by the CSS.
Note: New lines that are added by the user in elements where the xml:space attribute is set to
preserve (such as pre elements in HTML, or codeblock elements in DITA) are still inserted.
Also, selecting this option automatically disables the Also apply 'Format and Indent' action as
in 'Text' edit mode option, since the formatting from Text mode does not take the CSS styles into
account.
Tags Section
In this section you can configure the following options in regards to tags that are displayed in Author mode:
Tags display mode
Sets the default display mode for element tags presented in Author mode. You can choose between the following:
Full Tags with Attributes - All XML tags are displayed, with attribute names and values, making it easier
to transition from a Text-based editing to Author mode editing.
Full Tags - All XML tags are displayed, but without attributes.
Block Tags - The XML tags that enclose block elements are displayed in full. Compact tags (no element
names) are displayed for inline elements.
Inline Tags - The XML tags that enclose inline elements are displayed in full. Block tags are not displayed.
Partial Tags - Partial tags (no names) are displayed for all elements.
No Tags - No tags are displayed. This representation is as close as possible to a word-processor view.
Highlight elements near cursor - When this option is selected, the element containing the cursor is highlighted.
You can use the color picker to choose the color of the highlight.
Show cursor position tooltip - Oxygen XML Editor uses tool tips in Author mode to indicate the position of the
cursor in the element structure of the underlying document. Depending on context, the tool tips may show the current
element name or the names of the elements before and after the current cursor position.
Show location tooltip on mouse move - When this option is selected, Oxygen XML Editor displays Location
Tooltips when you are editing the document in certain tags display modes (Inline Tags, Partial Tags, No Tags) and
the mouse pointer is moved between block elements.
Quick up/down navigation - By default, when you navigate using the up and down arrow keys in Author mode,
the cursor is placed within each of the underlying XML elements between two blocks of text. (The cursor turns
horizontal when it is between blocks of text.) For instance, between a list item in one section and the title in a following
sections, the cursor might stop several times in the underlying structure: the list item, the list, the paragraph, the
section, and the root element between sections, the new section, and finally in the title. Any one of these location is
a place you might want to insert new content. When this option is selected, however, the cursor does not stop at these
positions, but jumps from one text line to another, similar to how the cursor behaves in a word processor.
Arrow keys move the cursor in the writing direction - This setting determines how the left and right arrow keys
behave in Author mode for bidirectional (BIDI) text. When this option is selected, the right arrow key advances the
cursor in the reading direction. When this option is not selected, pressing the right arrow will simply move the cursor
to the right, regardless of the text direction.
Schema-Aware Preferences
Oxygen XML Editor can use the schema of your XML language to improve the way the Author mode editor handles
your content. To configure the Schema Aware options, open the Preferences dialog box and go to Editor > Edit
modes > Author > Schema aware.
Smart delete
If deleting the tag would make the document invalid, Oxygen XML Editor will attempt to make the
document valid by unwrapping the current element or by appending it to an adjacent element where the
result would be valid. For instance, if you delete a bold tag, the content can be unwrapped and become
part of the surrounding paragraph, but if you delete a list item tag, the list item content cannot become
part of the list container. However, the content could be appended to a preceding list items.
Creating a sibling element that can accept the content. (For example, if you tried to paste a paragraph
into an existing paragraph.)
Inserting the content into a parent or child element. (For example, if you tried to paste a list item into
an existing list item, or into the space above or below and existing list.)
Inserting the content into an ancestor element where it would be valid.
Typing
Controls the behavior that takes place when typing. Available options:
Smart typing
If typed characters are not allowed in the element at the cursor position, but the previous element does
allow text, then a similar element will be inserted, along with your content.
Content Completion
Controls the behavior that takes place when inserting elements using content completion. Available options
are:
Join Elements
If selected, a warning message will be displayed if the Join Elements action will result in an invalid
document. You will be asked to confirm the join.
Review Preferences
Oxygen XML Editor lets you enter review comments and track changes in your documents. The Review preferences
control how the Oxygen XML Editor review features work. To configure the Review options, open the Preferences
dialog box and go to Editor > Edit modes > Author > Review.
The available options are:
Author - Specifies the name to be attached to all comments and to changes made while Track Changes is active.
By default, Oxygen XML Editor uses the system user name.
Initial State - Specifies whether or not Track Changes is enabled when you open a document. You may have some
opened documents in which track changes is enabled and others in which it is disabled. You can choose between the
following options:
Stored in document - The current state of track changed is stored in the document itself, meaning that track
changes on or off depending on the state the last time the document was saved. This is the recommended setting
when multiple authors work on the same set of documents as it will make it obvious to other authors that changes
have been made in the document.
Always On - The Track Changes feature is always on when you open a document. You can turn it off for an
open document, but it will be turned on for the next document you open.
Always Off - The Track Changes feature is always off when you open a document. You can turn it on for an
open document, but it will be turned off for the next document you open.
Display changed lines marker - A changed line maker is a vertical line on the left side of the editor window
indicating where changes have been made in the document. To hide the changed lines marker, deselect this option.
Inserted content color - When Track Changes option is on, the newly inserted content is highlighted with an
insertion marker, that uses a color to adjust the following display properties of the inserted content: foreground,
background, and underline. This section allows you to customize the marker's color:
Automatic - Oxygen XML Editor assigns a color to each user who inserted content in the current document. The
colors are picked from the Colors for automatic assignment list, the priority being established by the change
(deletion, insertion, or comment) timestamp.
Fixed - Uses the specified color for all insertion markers, regardless of who the author is.
Deleted content color - When Track Changes option is on, the deleted content is highlighted with a deletion marker,
that uses a color to adjust the following display properties of the deleted content: foreground, background, and
strikethrough. This section allows you to customize the marker's color:
Automatic - Oxygen XML Editor assigns a color to each user who deleted content in the current document. The
colors are picked from the Colors for automatic assignment list, the priority being established by the change
(deletion, insertion, or comment) timestamp.
Fixed - Uses the specified color for all deletion markers, regardless of who the author is.
Use same color for text foreground - Use the color defined above (Automatic or Fixed) to render the foreground
of the deleted content.
Use same color for background - Use the color defined above (Automatic or Fixed) to render the background
of the deleted content. A slider control allows you to set the transparency level of the marker's background.
Comments color (applies for all authors) - Sets the background color of the text that is commented on. The options
are:
Automatic - Oxygen XML Editor assigns a color to each user who added a comment in the current document.
The colors are picked from the Colors for automatic assignment list, the priority being established by the change
(deletion, insertion, or comment) timestamp.
Fixed - Uses the specified color for all changes, regardless of the author's name. Use the slider to control the
transparency level.
Callouts Preferences
Oxygen XML Editor can display callouts for review items such as comments and tracked changes. To set review callouts
preferences, open the Preferences dialog box and go to Editor > Edit modes > Author > Review > Callouts.
The options are as follows:
Comments - If selected, callouts are displayed for comments. This option is enabled by default.
Track Changes deletion - If selected, callouts are displayed for deletions.
Show deleted content in callout - If selected, the deleted content is displayed in the callout.
Show inserted content in callout - If selected, the inserted content is displayed in the callout.
Show review time - When selected, the date and time of a change are displayed in the callout.
Show all connecting lines - When selected, lines connect the callout to the location of the change.
Callouts pane width (px) - Sets the width of the callout field. The default is 200 pixels.
Callouts text limit (characters) - Sets the number of characters shown in the callout. The default is 160. Note that
this does not limit the number of characters in a comment. I only limits the number of characters shown in the callout.
To see the full comment, see the review view.
This setting is used to define how profiled elements are treated in Author mode. It does not create profiling
or conditional text attributes or values in the underlying XML vocabulary. It just changes how the editor
displays them.
This setting should be used for profiling / conditional text elements only. To change how other types of
attributes are displayed in the text, use a CSS style sheet.
If you are using the DITA XML vocabulary and a DITA Subject Scheme Map is defined in the root map of
your document, it will be used in place of anything defined using this dialog box.
Import from DITAVAL - This button allows you to import profiling attributes from .ditaval files. You can
merge these new profiling attributes with the existing ones, or replace them completely. If the imported attributes
conflict with the existing ones, Oxygen XML Editor displays a dialog box that contains two tables. The first one
previews the imported attributes and the second one previews the already defined attributes. You can choose to either
keep the existing attributes or replace them with the imported ones.
Note: When importing profiling attributes from DITAVAL files, Oxygen XML Editor automatically creates
condition sets based on these files.
Profiling Attributes section - Allows you to specify a set of allowable value for each profiling or conditional
attribute. You can use the New button at the bottom of the table to add profiling attributes, the Edit button to edit
existing ones, or the Delete button to delete entries from the table. Use the Up and Down buttons to change the
priority of the entries. If you have multiple entries with identical names that match the same document type, Oxygen
XML Editor uses the one that is positioned highest in the table.
Profiling Condition Sets section - Allows you to specify a specific set of profiling attributes to be used to specify
a particular build configuration for your content. You can use the New button at the bottom of the table to add
condition sets, the Edit button to edit existing ones, or the Delete button to delete entries from the table. Use the Up
and Down buttons to change the priority of the entries. If you have multiple entries with identical names that match
the same document type, Oxygen XML Editor uses the one that is positioned highest in the table.
Defined attributes values - contains the styles for profiling attribute values defined in the Profiling / Conditional
Text preferences page. Each profiling attribute value has an associated style. To ease the process of customizing
styles, the Defined attributes values category contains by default the list of empty styles. All you have to do is to
adjust the colors and decorations, thus skipping the process of manually defining the association rules (document
type, attribute name and value). This is the reason why a style from this category can only be reset, not deleted.
Other - this category contains styles for attribute values that are not marked as profiling values, in the Profiling /
Conditional Text preferences page. In this category are listed:
All the styles that were defined in other projects (with different profiling attribute value sets).
All the styles set for the profiling attributes defined in a subject scheme map.
Double-click the style in the styles table to open the Edit Profiling Style dialog box.
Select the style in the styles table and press Edit to open the Edit Profiling Style dialog box.
Show profiling attribute name - If checked, the names of the profiling attributes are displayed with their values.
If unchecked, only the values are displayed.
Background color - Sets the background color used to display the profiling attributes.
Attribute name foreground color - Sets the foreground color used to display the names of the profiling attributes.
Attribute values foreground color - Sets the foreground color used to display values of the profiling attributes.
Border color - Sets the color of the border of the block that displays the profiling attributes.
MathML Preferences
Oxygen XML Editor allows you to edit MathML equations and displays the results in a preview window. For a more
specialized MathML editor, you can install Design Science MathFlow, which is a commercial product that requires a
separate license.
To configure the MathML editor or to enter your MathFlow license information, open the Preferences dialog box and
go to Editor > Edit modes > Author > MathML. You can configure the following parameters:
Equation minimum font size - The minimum size of the font used for rendering mathematical symbols when editing
in the Author mode.
MathFlow installation directory - The installation folder for the MathFlow Components product (MathFlow SDK).
MathFlow license file - The license forMathFlow Components product (MathFlow SDK).
MathFlow preferred editor - A MathML formula can be edited in one of three editors of MathFlow Components
product(MathFlow SDK):
Save special characters - When editing mathematical expressions the special characters can be saved in the XML
file:
As entity names - saves the characters in &name; format. It refers to a character by the name of the entity which
has the desired character as its replacement text. For example, the Greek Omega character is saved as Ω.
As character entities (default selection) - saves the characters in a hexadecimal value, using the &#xNNN format.
For example, the Greek Omega character is saved as Ω.
As character values - saves the characters as the actual symbol. For example, the Greek Omega character is
saved as .
Enable AutoCorrect - This option is enabled by default. When enabled, while editing in Author mode, if you type
anything that is listed in the Replace column of the Replacements table displayed in this preferences page, Oxygen
XML Editor will automatically replace it with the value listed in the With column.
Use additional suggestions from the spell checker - If enabled, in addition to anything listed in the Replacements
table displayed in this preferences page, Oxygen XML Editor will also use suggestions from the Spell Checker to
automatically correct misspelled words. Suggestions from the Spell Checker will only be used if the misspelled word
is not found in the Replacements table.
Note: The AutoCorrect feature shares the same options configured in the Language options and Ignore elements
sections in the Spell Check preferences page.
Replacements Table
The AutoCorrect feature uses the Replacements table to automatically replace anything that is listed in the Replace
column with the value listed in the With column for each language. You can specify the language in the Replacements
for language drop-down menu, and for each language, you can configure the items listed in the table. The language
selected in this page is not the language that will be used by the AutoCorrect feature. It is simply the language for which
you are configuring the Replacements table.
You can double-click on cells in either column to edit the listed items. Use the Add button to insert new items and the
Remove button to delete rows from the table.
Note: Any changes, additions, or deletions you make to this table are saved to a path that is specified in the
AutoCorrect Dictionaries preferences page.
Smart Quotes Section
You can also choose to automatically convert double and single quotes to a quotation characters of your choice by using
the following options in the Smart quotes section:
Replace "Single quotes" - Replaces single quotes with the quotation symbols you select with the Start quote and
End quote buttons.
Replace "Double quotes" - Replaces double quotes with the quotation symbols you select with the Start quote
and End quote buttons.
Dictionaries default folder - Displays the default location where the dictionaries that Oxygen XML Editor uses for
the AutoCorrect feature are stored.
Include dictionaries from - Enable this option if you want to specify an additional location for the dictionaries that
Oxygen XML Editor will use for the AutoCorrect feature.
Note: The AutoCorrect feature takes into account dictionaries collected both from the default and custom
locations and multiple dictionaries from the same language are merged into a generic dictionary (for example,
en_UK.dat from the default location is merged with en_US.dat from a custom location, and the result is
that a third file is created for a generic dictionary called en.dat). However, if there is already a generic
dictionary (for example, en.dat) saved in either the default or custom location, the other specific dictionaries
(for example, en_UK.dat and en_US.dat) will not be merged and the existing generic dictionary will simply
be used. Also, if the additional location contains a file with the same name as one from the default location, the
file in the additional location takes precedence over the file from the default location. The user-defined
replacements are never merged.
Save user-defined replacements in the following location - Specifies the target where added, edited, or deleted
replacements are saved. By default, the target is the application preferences folder, but you can also choose a custom
location.
Tip: To save changes to the Replacement table (in the AutoCorrect preferences page) at project level, select
a custom location for the User-defined replacements and select Project Options at the bottom of the page.
Show annotation in the diagram - When selected, Oxygen XML Editor displays the content of
xs:documentation elements in the XML Schema Design view.
When trying to edit components from another schema - The schema diagram editor will combine schemas
imported by the current schema file into a single schema diagram. You can choose what happens if you try to edit
a component from an imported schema. The options are:
Always go to its definition - Oxygen XML Editor opens the imported schema file so that you can edit it.
Never go to its definition - The imported schema file is not opened. The definition cannot be edited in place.
Always ask - Oxygen XML Editor asks if you want to open the imported schema file.
Zoom - Allows you to set the default zoom level of the schema diagram.
Detect indent on open - Oxygen XML Editor detects how a document is indented when it is opened. Oxygen XML
Editor uses a heuristic method of detection by computing a weighted average indent value from the initial document
content. You can disable this setting if the detected value does not work for your particular case and you want to use
a fixed-size indent for all the edited documents.
Tip: If you want to minimize the formatting differences created by the Format and Indent operation in a
document edited in the Text edited mode, make sure that both the Detect indent on open and Detect line
width on open options are enabled.
Use zero-indent, if detected - By default, if no indent was detected in the document, the fixed-size indent is
used. Enable this option if all your document have no indentation and you want to keep them that way.
Indent with tabs - If selected, indents are created using tab characters. If unchecked, lines are indented using space
characters.
Indent size - A fixed number of spaces used for indenting a line.
Hard line wrap (Limit to "Line width - Format and Indent") - If selected, when typing content in the Text editing
mode when the maximum line width is reached, a line break is automatically inserted.
Indent on enter - If disabled, when you press the Enter key to insert a line break in the Textediting mode, no
indentation will be added to the new line.
Enable smart enter - If selected, when you press the Enter key between a start and an end XML tag in the Text
editing mode, the cursor is placed in an indented position on the empty line formed between the start and end tag.
Detect line width on open - When selected, Oxygen XML Editor detects the line width automatically when the
document is opened.
Format and indent the document on open - When selected, an XML document is formatted and indented before
opening it in Oxygen XML Editor.
Line width - Format and Indent - Defines the number of characters after which the Format and Indent (pretty-print)
action performs hard line wrapping. For example, if set to 100, after a Format and Indent action, the longest line
will have at most 100 characters. This setting is also used when saving the XML content edited in the Author editing
mode.
Clear undo buffer before Format and Indent - The Format and Indent operation can be undone, but if used
intensively, a considerable amount of the memory allocated for Oxygen XML Editor will be used for storing the
undo states. If this option is selected, Oxygen XML Editor empties the undo buffer before doing a Format and
Indent operation. This means you will not be able to undo any changes you made before the format and indent
operation. Select this option if you encounter out of memory problems (OutOfMemoryError) when performing
the Format and Indent operation.
The indent size and line width limit settings are used in various places in the application:
When the Format and Indent action is used in the Text editing mode.
When you press ENTER in the Text editing mode to break a line.
When editing in the Text mode with Hard line wrap enabled.
When the XML is serialized by saving content in the Author editing mode.
To watch our video demonstration about the formatting options offered by Oxygen XML Editor, go to
http://oxygenxml.com/demo/Autodetect_Formating.html.
XML Formatting Preferences
To configure the XML Formatting options, open the Preferences dialog box and go to Editor > Format > XML.
The following options are available:
Format Section
This section includes the following drop down boxes:
Preserve empty lines
The Format and Indent operation preserves all empty lines found in the document.
Preserve text as it is
The Format and Indent operation preserves text content as it is, without removing or adding any white space.
Preserve line breaks in attributes
Line breaks found in attribute values are preserved.
Note: When this option is enabled, the Break long attributes option is automatically disabled.
Break long attributes
The Format and Indent operation breaks long attribute values.
Indent inline elements
The inline elements are indented on separate lines if they are preceded by white spaces and they follow another
element start or end tag. For example:
Original XML:
<root>
text <parent> <child></child> </parent>
</root>
element[@attr] - Matches all instances of the specified element that include the specified attribute.
element[not(@attr)] - Matches all instances of the specified element that do not include the specified
attribute.
element[@attr = "value"] - Matches all instances of the specified element that include the specified
attribute with the given value.
element[@attr != "value"] - Matches all instances of the specified element that include the specified
attribute and its value is different than the one given.
elementName
//elementName
/elementName1/elementName2/elementName3
//xs:localName
Note: The namespace prefixes (such as xs) are treated as part of the element name without taking
its binding to a namespace into account.
Default space
List of elements for which the content is normalized (multiple contiguous whitespaces are replaced by a single
space), before applying the Format and Indent operation.
Mixed content
The elements from this list are treated as mixed content when applying the Format and Indent operation. The
lines are split only when whitespaces are encountered.
Line break
List of elements for which line breaks will be inserted, regardless of their content. You can choose to break the
line before the element, after, or both.
Schema aware format and indent
The Format and Indent operation takes the schema information into account with regards to the space preserve,
mixed, or element only properties of an element.
Indent Section
Includes the following options:
Format XPath code embedded in XSLT, XSD and Schematron files - If enabled, the Format and Indent action
applied on a XSD, XSLT, or Schematron document will perform an XPath-specific formatting on the values of the
attributes that accept XPath expressions.
Note: For XSLT documents, the formatting is not applied to attribute value templates.
Start curly brace on new line - Opening curly braces start on a new line.
Preserve empty lines - Empty lines in the JavaScript code are preserved. This option is enabled by default.
Allow formatting embedded JavaScript - Applied only to XHTML documents, this option allows Oxygen XML
Editor to format embedded JavaScript code, taking precedence over the Schema aware format and indent option.
This option is enabled by default.
Auto close the last opened tag - Oxygen XML Editor closes the last open tag when you type </.
Automatically rename/delete/comment matching tag - If you rename, delete, or comment out a start tag, Oxygen
XML Editor automatically renames, deletes, or comments out the matching end tag.
Note: If you select Toggle comment for multiple starting tags and the matching end tags are on the same
line as other start tags, the end tags are not commented.
If it has no matching tag - The end tag of the inserted element is automatically added only if it is not already
present in the document.
Add element content - Oxygen XML Editor inserts the required elements specified in the DTD, XML Schema,
or RELAX NG schema that is associated with the edited XML document.
Add optional content - Oxygen XML Editor inserts the optional elements specified in the DTD, XML
Schema, or RELAX NG schema.
Add first Choice particle - Oxygen XML Editor inserts the first choice particle specified in the DTD, XML
Schema, or RELAX NG schema.
Cursor position between tags - When selected, Oxygen XML Editor automatically moves the cursor between start
and end tag after inserting the element. This only applies to:
Show all entities - Oxygen XML Editor displays a list with all the internal and external entities declared in the
current document when you type the start character of an entity reference (for example, &).
Insert the required attributes - Oxygen XML Editor inserts automatically the required attributes taken from the
DTD or XML Schema. This option is applied also in the Author mode of the XML editor.
Insert the fixed attributes - Oxygen XML Editor automatically inserts any FIXED attributes from the DTD or
XML Schema for an element inserted with the help of the Content Completion Assistant. This option is applied
also in the Author mode of the XML editor.
Show recently used items - when checked, Oxygen XML Editor remembers the last inserted items from the Content
Completion Assistant window. The number of items to be remembered is limited by the Maximum number of
recent items shown list box. These most frequently used items are displayed on the top of the content completion
window and are separated from the rest of the suggestions by a thin gray line . This option is applied also in the
Author mode of the XML editor.
Maximum number of recent items shown - limits the number of recently used items presented at the top of the
Content Completion Assistant window. This option is applied also in the Author mode of the XML editor.
Learn attributes values - Oxygen XML Editor learns the attribute values used in a document. This option is applied
also in the Author mode of the XML editor.
Learn on open document - Oxygen XML Editor automatically learns the document structure when the document
is opened. This option is applied also in the Author mode of the XML editor.
Learn words (Dynamic Abbreviations, available on Ctrl Space (Command Space on OS X)) - When selected,
Oxygen XML Editor learns the typed words and makes them available in a content completion fashion by pressing
Ctrl Space (Command Space on OS X) om your keyboard;
Note: In order to be learned, the words need to be separated by space characters.
Activation delay of the proposals window (ms) - Delay in milliseconds from last key press until the content
completion assistant window is displayed.
Annotations Preferences
Different types of schemas (XML Schema, DTDs, Relax NG) can include annotations that document the various elements
and attributes that they define. Oxygen XML Editor can display these annotations when offering content completion
suggestions. To configure the Annotations preferences, open the Preferences dialog box and go to Editor > Content
Completion > Annotations.
The following options are available:
Show annotations in Content Completion Assistant
Oxygen XML Editor displays the schema annotations of an element, attribute, or attribute value currently selected
in the Content Completion Assistant proposals list.
Show annotations in tooltip
Oxygen XML Editor displays the annotation of elements and attributes as a tooltip when you hover over them with
the cursor in the editing area or in the Elements view.
Show annotation in HTML format, if possible
This option allows you to view the annotations associated with an element or attribute in HTML format. It is available
when editing XML documents that have associated an XML Schema or Relax NG schema. When this option is
disabled the annotations are converted and displayed as plain text.
If at least one doc: comment is found in the entire DTD, only comments of this type are displayed as annotations.
If no doc: comment is found in the entire DTD, all comments are considered annotations and displayed as
such.
When the option is disabled, all comments, regardless of their type, are considered annotations and displayed as
such.
Use all Relax NG annotations as documentation
When this option is selected, any element outside the Relax NG namespace, that is
http://relaxng.org/ns/structure/1.0, is considered annotation and is displayed in the annotation
window next to the Content Completion Assistant window and in the Model view. When this option is not selected,
only elements from the Relax NG annotations namespace, that is
http://relaxng.org/ns/compatibility/annotations/1.0 are considered annotations.
XSL Preferences
XSL stylesheets are often used to create output in XHTML or XSL-FO. In addition to suggesting content completion
options for XSLT stylesheet elements, Oxygen XML Editor can suggest elements from these vocabularies. To configure
the XSL content completion options, open the Preferences dialog box and go to Editor > Content Completion > XSL.
The following options are available:
Automatically detect XHTML transitional or Formatting objects - Detects if the output being generated is
XHTML or FO and provides content completion for those vocabularies. Oxygen XML Editor analyzes the namespaces
declared in the root element to find an appropriate schema.
If the detection fails, Oxygen XML Editor uses one of the following options:
Documentation schema - You can choose an additional schema that will be used for documenting XSL stylesheets.
Choose between the following:
XPath Preferences
Oxygen XML Editor provides content-completion support for XPath expressions. To configure the options for the
content completion in XPath expressions, open the Preferences dialog box and go to Editor > Content Completion >
XPath.
The following options are available:
Enable content completion for XPath expressions - Enables the Content Completion Assistant in XPath expressions
that you enter in the match, select, and test XSL attributes and also in the XPath toolbar.
Show signatures of XSLT / XPath functions - Makes the editor indicate the signature of the XPath function located
at the cursor position in a tooltip. See the XPath Tooltip Helper section for more information.
Function signature window background - Specifies the background color of the tooltip window.
Function signature window foreground - Specifies the foreground color of the tooltip window.
XSD Preferences
Oxygen XML Editor provides content completion assistance when you are writing an XML Schema (XSD). To configure
XSD preferences, open the Preferences dialog box and go to Editor > Content Completion > XSD. The options in
this preferences page define what elements are suggested by the Content Completion Assistant, in addition to the ones
from the XML Schema (defined by the xs:annotation/xs:appinfo elements).
The following options are available:
None - The Content Completion Assistant offers only the XML Schema schema information.
ISO Schematron - The Content Completion Assistant includes ISO Schematron elements in xs:appinfo.
Schematron 1.5 - The Content Completion Assistant includes Schematron 1.5 elements in xs:appinfo.
Other - The Content Completion Assistant includes in xs:appinfo elements from an XML Schema identified
by an URL.
JavaScript Preferences
Oxygen XML Editor can provide content completion suggestions when you are writing JavaScript files. To configure
content completion support for JavaScript, open the Preferences dialog box and go to Editor > Content Completion >
JavaScript. You can configure the following options:
Enable content completion - Enables the content completion support for JavaScript files.
Use built-in libraries - Allows Oxygen XML Editor to include components (object names, properties, functions,
and variables) collected from the built-in JavaScript library files when making suggestions.
Use defined libraries - Oxygen XML Editor can also use JavaScript libraries to when making suggestions. List the
paths (URIs) of any JavaScript files you want Oxygen XML Editor to use when making suggestions.
Note: The paths can contain editor variables such as ${pdu}, or ${oxygenHome}. You can make these
paths relative to the project directory or installation directory.
Lock local resources - When this option is enabled and you open a file from the local file system or a shared network
drive, Oxygen XML Editor locks the file for the current user and the file cannot be modified by other users while
the lock exists. However, other users are offered the possibility to edit the file, but without overwriting it. If they
decide to continue, they will be asked to save the changes in a different file or drop them. Newly created files are
locked when you first save them. If you enable this option with files already opened in Oxygen XML Editor, it will
lock all the currently opened files. If you disable this option with files already opened, it will unlock them by deleting
the corresponding .lock files.
Support for Special Characters section - You can choose how you want Oxygen XML Editor to handle bidirectional
text, Asian languages, or other special characters when they are detected. You can choose one of the following:
Disable special characters support for documents larger than (characters) - Enabling bidirectional text editing
support can affect performance on large files. When this option is selected, bidirectional editing is disabled for files
exceeding the specified size, even if the Enable support for special characters option is selected.
Save
The following options apply to saving files:
Safe save (only for local files) - In the unlikely event of a failure of the Save action, this option provides increased
protection from corruption of the original file. When this option is enabled, it saves the content to a temporary file
and if the save is unsuccessful, the editor preserves its unsaved state status.
Make backup copy on save (only for local files) - If selected, a backup copy is made when saving the edited
document. This option is available only for local files (files that are stored on the local file system). The default
backup file extension is .bak, but that can be changed.
Enable automatic save - When selected, your documents are saved automatically, after a preset time interval.
Automatic save interval (minutes) - Selects the interval, in minutes, for the automatic save action.
Check errors on save - If enabled, Oxygen XML Editor runs a validation that checks your document for errors
before saving it.
Performance
The following options cover performance issues when dealing with large files:
Optimize loading in the Text edit mode for files over (MB) - File loading is optimized for reduced memory usage
for any file with a size larger than this value. This is useful for editing large files, but it comes with several restrictions
on memory-intensive operations.
Show warning when loading large documents - Oxygen XML Editor will warn you if you open a file that is bigger
than the specified size.
Optimize loading for documents with lines longer than (Characters) - Line wrap is turned on for a document
that contains lines that exceed the specified length. For a list of the restrictions applied to a document with long lines,
see the Editing Documents with Long Lines section.
Show warning when loading documents with long lines - When selected, Oxygen XML Editorwill warn you when
you open a file with lines longer than the specified length. To reduce the length of lines in a file, format and indent
the document after it is opened in the editor panel. For a list of the restrictions applied to a document with long lines,
see Editing Documents with Long Lines on page 468.
Clear undo buffer on save - If selected, Oxygen XML Editor clears its undo buffer when you save a document.
Therefore, modifications made prior to saving the document cannot be undone. Select this option if you frequently
encounter out of memory errors when editing large documents.
Consider application bundles to be directories when browsing - This option is available only on the Mac OS X
platform. When selected, the file browser dialog box allows browsing inside an application bundle, as in a regular
folder. Otherwise, the file browser dialog box does not allow browsing inside an application bundle, as the Finder
application does on Mac OS X.
Note: The same effect can be obtained by setting the property apple.awt.use-file-dialog-packages to true
or false in the Info.plist descriptor file of the Oxygen XML Editor application:
<key>apple.awt.use-file-dialog-packages</key>
<string>false</string>
Automatically compile LESS to CSS when saving - If enabled, when you save a LESS file it will automatically
be compiled to CSS (disabled by default).
Important: If this option is enabled, when you save a LESS file, the CSS file that has the same name as
the LESS file is overwritten without warning. Make sure all your changes are made in the LESS file. Do not
edit the CSS file directly, as your changes might be lost.
Templates Preferences
This page groups the preferences for code templates and document templates:
Code Templates
Document Templates
M1 represents the Command key on MacOS X, and the Ctrl key on other platforms.
M2 represents the Shift key.
M3 represents the Option key on MacOS X, and the Alt key on other platforms.
M4 represents the Ctrl key on MacOS X, and is undefined on other platforms.
Content - Text box where you define the content that is used when the code template is inserted.
Edit
Opens the Code template dialog box and allows you to edit an existing code template. You can edit the following
fields:
Description - The description of the code template that will appear in the Code Templates preferences page
and in the tooltip message when selecting it from the Content Completion Assistant. HTML markup can be
used for better rendering.
Shortcut key - Allows you to configure a shortcut key that can be used to insert the code template. The +
character separates keys. If the Enable platform-independent shortcut keys checkbox is enabled, the shortcut
is platform-independent and the following modifiers are used:
M1 represents the Command key on MacOS X, and the Ctrl key on other platforms.
M2 represents the Shift key.
M3 represents the Option key on MacOS X, and the Alt key on other platforms.
M4 represents the Ctrl key on MacOS X, and is undefined on other platforms.
Content - Text box where you define the content that is used when the code template is inserted.
Duplicate
Creates a duplicate of the currently selected code template.
Delete
Deletes the currently selected code template. This action is disabled for the built-in code templates.
Export
Exports a file with code templates.
${caret} - The position where the cursor is located. This variable can be used in a code template, in Author mode
operations, or in a selection plugin.
${selection} - The current selected text content in the current edited document. This variable can be used in a code
template, in Author mode operations, or in a selection plugin.
${ask('message', type, ('real_value1':'rendered_value1'; 'real_value2':'rendered_value2'; ...), 'default_value')} - To
prompt for values at runtime, use the ask('message', type, ('real_value1':'rendered_value1';
'real_value2':'rendered_value2'; ...), 'default-value'') editor variable. You can set the following parameters:
'message' - The displayed message. Note the quotes that enclose the message.
type - Optional parameter, with one of the following values:
Parameter
url
password
${ask('Input URL', url)} - The displayed dialog box has the name Input
URL. The expected input type is URL.
${ask('Input URL', url, 'http://www.example.com')} - The
displayed dialog box has the name Input URL. The expected input type is URL.
The input field displays the default value http://www.example.com.
generic
relative_url
combobox
${ask('File location', relative_url, 'C:/example.txt')} - The dialog box has the name
'File location'. The URL inserted in the input box is made relative to the
current edited document location.
${timeStamp} - Time stamp, that is the current time in Unix format. It can be used for example to save transformation
results in different output files on each transform.
${uuid} - Universally unique identifier, a unique sequence of 32 hexadecimal digits generated by the Java UUID
class.
${id} - Application-level unique identifier; a short sequence of 10-12 letters and digits which is not guaranteed to
be universally unique.
${cfn} - Current file name without extension and without parent folder. The current file is the one currently opened
and selected.
${cfne} - Current file name with extension. The current file is the one currently opened and selected.
${cf} - Current file as file path, that is the absolute file path of the current edited document.
${cfd} - Current file folder as file path, that is the path of the current edited document up to the name of the parent
folder.
${frameworksDir} - The path (as file path) of the [OXYGEN_DIR]/frameworksdirectory.
${pd} - Current project folder as file path. Usually the current folder selected in the Project View.
${oxygenInstallDir} - Oxygen XML Editor installation folder as file path.
${homeDir} - The path (as file path) of the user home folder.
${pn} - Current project name.
${env(VAR_NAME)} - Value of the VAR_NAME environment variable. The environment variables are managed by
the operating system. If you are looking for Java System Properties, use the ${system(var.name)} editor variable.
${system(var.name)} - Value of the var.name Java System Property. The Java system properties can be specified
in the command line arguments of the Java runtime as -Dvar.name=var.value. If you are looking for operating
system environment variables, use the ${env(VAR_NAME)} editor variable instead.
${date(pattern)} - Current date. The allowed patterns are equivalent to the ones in the Java SimpleDateFormat class.
Example: yyyy-MM-dd;
Note: This editor variable supports both the xs:date and xs:datetime parameters. For details about xs:date,
go to http://www.w3.org/TR/xmlschema-2/#date. For details about xs:datetime, go to
http://www.w3.org/TR/xmlschema-2/#dateTime.
Spell checking engine - Oxygen XML Editor ships with two spell check engines, Hunspell and Java spell checker.
The two engines come with different dictionaries. When you select an engine here, the list of languages in the Default
language option changes based on the available dictionaries for the engine you have chosen.
Automatic Spell Check - This option is disabled by default. When enabled, Oxygen XML Editor automatically
checks the spelling as you type and highlights misspelled words in the document.
Select editors - You can select which editors (and therefore which file types) will be automatically spelled
checked. File types for which automatic spell check is generally not useful, such as CSS and DTD, are excluded
by default.
Spell check highlight color - Use this option to set the color used by the spell check engine to highlight spelling
errors.
Default language - The default language list allows you to choose the language used by the spell check engine when
the language is not specified in the source file. You can add additional dictionaries to the spell check engines.
Use "lang" and "xml:lang" attributes - When this option is selected, the contents of an element with one of the
lang or xml:lang attributes is checked in that language. When this option is enabled, choose between the following
two options for instances when these attributes are missing:
Use the default language - If the lang and xml:lang attributes are missing, the selection in the Default
language list is used.
Do not check - If the lang and xml:lang attributes are missing, the element is not checked.
Comments
Attribute values
Text
CDATA
Options Section
Check capitalization - When selected, the spell checker reports capitalization errors (for example, a word that starts
with lowercase after etc. or i.e..
Check punctuation - When selected, the spell checker checks punctuation. Misplaced white space and unusual
sequences, like a period following a comma, are highlighted as errors.
Ignore mixed case words - When selected, the spell checker does not check words containing mixed case characters
(for example, SpellChecker).
Dictionaries and term lists default folder - Displays the default location where the dictionaries and term lists that
Oxygen XML Editor uses are stored.
Include dictionaries and term list from - Selecting this option allows you to specify a location where you have
stored dictionaries and term lists that you want to include, along with the default ones.
Note: The spell checker takes into account dictionaries and term lists collected both from the default and custom
locations and multiple dictionaries and term lists from the same language are merged into generic ones (for
example, en_UK.dic from the default location is merged with en_US.dic from a custom location, and the
result is that a third file is created for a generic dictionary called en.dic). However, if there is already a generic
dictionary (for example, en.dic) saved in either the default or custom location, the other specific dictionaries
(for example, en_UK.dic and en_US.dic) will not be merged and the existing generic dictionary will simply
be used. Also, if the additional location contains a file with the same name as one from the default location, the
file in the additional location takes precedence over the file from the default location.
Save learned words in the following location - Specifies the target where the newly learned words are saved. By
default, the target is the application preferences folder, but you can also choose a custom location.
Delete learned words - Opens the list of learned words, allowing you to select the items you want to remove, without
deleting the dictionaries and term lists.
XML files - Activates the Highlight IDs Occurrences feature in XML files.
XSLT files - Activates the Highlight Component Occurrences feature in XSLT files.
XML Schema files and WSDL files - Activates the Highlight Component Occurrences feature in XSD and WSDL
files.
RNG files - Activates the highlight component occurrences feature in RNG files.
Schematron files - Activates the Highlight Component Occurrences feature in Schematron files.
Ant files - Activates the Highlight Component Occurrences feature in Ant files.
Declaration highlight color - Color used to highlight the component declaration.
Reference highlight color - Color used to highlight component references.
Name - Name of the custom validation engine that will be displayed in the
Validation toolbar drop-down
menu.
Executable path - Path to the executable file of the custom validation tool. You can insert editor variables, such as
${home}, ${pd}, ${oxygenInstallDir}.
Working directory - The working directory of the custom validation tool.
Associated editors - The editors that can perform validation with the external tool (XML editor, XSL editor, XSD
editor, etc.)
Command line arguments for detected schemas - Command line arguments used in the commands that validate
the current edited file against different types of schema (W3C XML Schema, Relax NG full syntax, Relax NG
compact syntax, NVDL, Schematron, DTD, etc.) The arguments can include any custom switch (like -rng) and the
following editor variables:
${cf} - Current file as file path, that is the absolute file path of the current edited document.
${currentFileURL} - Current file as URL, that is the absolute file path of the current edited document represented
as URL.
${ds} - The path of the detected schema as a local file path for the current validated XML document.
${dsu} - The path of the detected schema as an URL for the current validated XML document.
Use the com.oxygenxml.stack.size.validation.threads property to increase the size of the stack for validation
engines. The value of this property is specified in bytes. For example, to set a value of one megabyte specify
1x1024x1024=1048576.
Increase the value of the -Xss parameter.
Note: Increasing the value of the -Xss parameter affects all the threads of the application.
Profile - Selects one of the available validation profiles: CSS 1, CSS 2, CSS 2.1, CSS 3, CSS 3 with Oxygen
extensions, SVG, SVG Basic, SVG Tiny, Mobile, TV Profile, ATSC TV Profile. The CSS 3 with Oxygen
extensions profile includes all the CSS 3 standard properties plus the CSS extensions specific for Oxygen that can
be used in Author mode. That means all Oxygen specific extensions are accepted in a CSS stylesheet by the built-in
CSS validator when this profile is selected.
Media type - Selects one of the available mediums: all, aural, braille, embossed, handheld, print, projection,
screen, tty, tv, presentation, oxygen.
Warning level - Sets the minimum severity level for reported validation warnings. Can be one of: All, Normal,
Most Important, No Warnings.
Ignore properties - You can type comma separated patterns that match the names of CSS properties that will be
ignored at validation. As wildcards you can use:
Recognize browser CSS extensions (applies also to content completion) - If checked, Oxygen XML Editor
recognizes (no validation is performed) browser-specific CSS properties. The Content Completion Assistant lists
these properties at the end of its list, prefixed with the following particles:
XML Preferences
This section describes the panels that contain the user preferences related with XML.
XML Catalog Preferences
To configure the XML Catalog options, open the Preferences dialog box and go to XML > XML Catalog.
The following options are available:
Prefer - the prefer setting determines whether public identifiers specified in the catalog are used in favor of system
identifiers supplied in the document. Suppose you have an entity in your document for which both a public identifier
and a system identifier has been specified, and the catalog only contains a mapping for the public identifier (for
example, a matching public catalog entry). If public is selected, the URI supplied in the matching public catalog
entry is used. If system is selected, the system identifier in the document is used.
Note: If the catalog contained a matching system catalog entry giving a mapping for the system identifier,
that mapping would have been used, the public identifier would never have been considered, and the setting
of override would have been irrelevant.
Generally, the purpose of catalogs is to override the system identifiers in XML documents, so Prefer should usually
be public in your catalogs.
When using catalogs it is sometimes useful to see what catalog files are parsed, if they are valid or not, and what
identifiers are resolved by the catalogs. The Verbosity option selects the detail level of such logging messages of
the XML catalog resolver that will be displayed in the Catalogs view at the bottom of the window:
None - No message is displayed by the catalog resolver when it tries to resolve a URI reference, a SYSTEM one
or a PUBLIC one with the XML catalogs specified in this panel.
Unresolved entities - Only the logging messages that track the failed attempts to resolve references are displayed.
All messages - The messages of both failed attempts and successful ones are displayed.
If Process namespaces through URI mappings for XML Schema is selected then the target namespace of the
imported XML Schemas is resolved through the uri mappings. The namespace is taken into account only when the
schema specified in the schemaLocation attribute was not resolved successfully.
If the Use default catalog option is checked the first XML catalog which Oxygen XML Editor will use to resolve
references at document validation and transformation will be a default built-in catalog. This catalog maps such
references to the built-in local copies of the schemas of the Oxygen XML Editor frameworks (DocBook, DITA, TEI,
XHTML, SVG, etc.)
You can also add or configure catalogs at framework level from the Catalogs tab in the Document Type configuration
dialog box.
When you add, delete or edit an XML catalog to / from the list, reopen the currently edited files which use the modified
catalog or run the Validate action so that the XML catalog changes take full effect.
XML Parser Preferences
To configure the XML Parser options, open the Preferences dialog box and go to XML > XML Parser.
The configurable options of the built-in XML parser are as follows:
Enable parser caching (validation and content completion) - Enables re-use of internal models when validating
and provides content completion in opened XML files which reference the same schemas (grammars) like DTD,
XML Schema, RelaxNG.
Ignore the DTD for validation if a schema is specified - Forces validation against a referenced schema (W3C
XML Schema, Relax NG schema) even if the document includes also a DTD DOCTYPE declaration. This option
is useful when the DTD declaration is used only to declare DTD entities and the schema reference is used for validation
against a W3C XML Schema or a Relax NG schema.
Note: Schematron schemas are treated as additional schemas. The validation of a document associated with
a DTD and referencing a Schematron schema is executed against both the DTD and the Schematron schema,
regardless of the value of the Ignore the DTD for validation if a schema is specified option.
Enable XInclude processing - Enables XInclude processing. If checked, the XInclude support in Oxygen XML
Editor is turned on for validation, rendering in Author mode and transformation of XML documents.
Base URI fix-up - According to the specification for XInclude, processors must add an xml:base attribute to
elements included from locations with a different base URI. Without these attributes, the resulting infoset information
would be incorrect.
Unfortunately, these attributes make XInclude processing not transparent to Schema validation. One solution to this
is to modify your schema to allow xml:base attributes to appear on elements that might be included from different
base URIs.
If the addition of xml:base and / or xml:lang is undesired by your application, you can disable base URI fix-up.
Language fix-up - The processor will preserve language information on a top-level included element by adding an
xml:lang attribute if its include parent has a different [language] property. If the addition of xml:lang is undesired
by your application, you can disable the language fix-up.
DTD post-validation - Enable this option to validate an XML file against the associated DTD, after all the content
merged to the current XML file using XInclude was resolved. If you disable this option, the current XML file is
validated against the associated DTD before all the content merged to the current XML file using XInclude is
resolved.
Default XML Schema version - Allows you to select the version of W3C XML Schema: XML Schema 1.0 or XML
Schema 1.1.
Note: You are also able to set the XML Schema version using the Customize option in New dialog box.
Default XML Schema validation engine - Allows you to set the default XML Schema validation engine either to
Xerces or Saxon EE.
Multiple schema imports - Forces xs:import to fetch the referenced schema document. By default, the xs:import
fetches the document only if no schema document for the given namespace has already been loaded. With this option
in effect, the referenced schema document is loaded unless the absolute URI is the same as a schema document
already loaded.
Assertions can see comments and processing instructions - Controls whether comments and processing instructions
are visible to the XPath expression used to define an assertion. By default (unlike Saxon 9.3), they are not made
visible.
Relax NG Preferences
To configure the Relax NG options, open the Preferences dialog box and go to XML > XML Parser > Relax NG.
The following options are available in this page:
Check feasibly valid - Checks whether Relax NG documents can be transformed into valid documents by inserting
any number of attributes and child elements anywhere in the tree.
Note: Enabling this option disables the Check ID/IDREF option.
Check ID/IDREF - Checks the ID/IDREF matches when a Relax NG document is validated.
Add default attribute values - Default values are given to the attributes of documents validated using Relax NG.
These values are defined in the Relax NG schema.
Schematron Preferences
To configure the Schematron options, open the Preferences dialog box and go to XML > XML Parser > Schematron.
The following options are available in this preferences page:
Optimize (visit-no-attributes) - If your ISO Schematron assertion tests do not contain the attributes axis, you should
check this option for faster ISO Schematron validation.
Allow foreign elements (allow-foreign) - Enables support for allow-foreign on ISO Schematron. This option
is used to pass non-Schematron elements to the generated stylesheet.
Use Saxon EE (schema aware) for xslt2/xslt3 query language binding - When enabled, Saxon EE is used for
xslt2/xslt3 query binding. If this option is disabled, Saxon PE is used.
Enable Schematron Quick Fixes (SQF) support - Allows you to enable or disable the support for quick fixes in
Schematron files. This option is enabled by default.
Embedded rules query language binding - You can control the query language binding used by the ISO Schematron
embedded rules. You can choose between: xslt1, xslt2, or xslt3.
Note: To control the query language binding for standalone ISO Schematron, you need to set the query
language to be used with a queryBinding attribute on the schema root element.
XPath Version - Allows you to select the version of XPath for the expressions that are allowed in Schematron
assertion tests. You can choose between: 1.0, 2.0, or 3.0. This option is applied in both standalone Schematron 1.5
schemas and embedded Schematron 1.5 rules.
Generate optional elements - If checked, the elements declared optional in the schema will be generated in the
XML instance.
Generate optional attributes - If checked, the attributes declared optional in the schema will be generated in the
XML instance.
Values of elements and attributes - Specifies what values are generated in elements and attributes of the XML
instance. It can have one of the values:
Preferred number of repetitions - If the values set here is greater than maxOccurs, then the maxOccurs is used.
Maximum recursivity level - For recursive type definitions this parameter specifies the number of levels of recursive
elements inserted in the parent element with the same name.
Type alternative strategy - Specifies how the element type alternatives are generated in the XML instance:
First - The first element type alternative whose XPath condition is true is used.
Random - A random element type alternative whose XPath condition is true is used.
Note: If no XPath condition is true, the default element type alternative is used.
Note: To evaluate an XPath expression, either the values of the attributes defined in the Options tab of
the XML Instance Generator dialog box, or the attributes values defined in the XML Schema are used.
Choice strategy - For choice element models specifies what choice will be generated in the XML instance:
First - The first choice is selected from the choice definition and an instance of that choice is generated in the
XML instance document.
Random - A random choice is selected from the choice definition and an instance of that will be generated.
Name - The value of this field will be displayed in the XProc transformation scenario and in the command line that
will start it.
Description - A textual description that will appear as a tooltip where the XProc engine will be used.
Working directory - The working directory for resolving relative paths. You can use built-in editor variables and
custom editor variables for the path.
Command line - The command line that will run the XProc engine as an external process. You can use built-in
editor variables and custom editor variables for parametrizing a file path.
Output encoding - The encoding for the output stream of the XProc engine, used for reading and displaying the
output messages.
Error encoding - The encoding for the error stream of the XProc engine, used for reading and displaying the messages
from the error stream.
Value - Allows you to set the value of the TransformerFactory Java class.
XSLT 1.0 Validate with - Allows you to set the XSLT engine used for validation of XSLT 1.0 documents.
XSLT 2.0 Validate with - Allows you to set the XSLT Engine used for validation of XSLT 2.0 documents.
XSLT 3.0 Validate with - Allows you to set the XSLT Engine used for validation of XSLT 3.0 documents.
Note: Saxon-HE does not implement any XSLT 3.0 features. Saxon-PE implements a selection of XSLT
3.0 (and XPath 3.0) features, with the exception of schema-awareness and streaming. Saxon-EE implements
additional features relating to streaming (processing of a source document without constructing a tree in
memory. For further details about XSLT 3.0 conformance, go to
http://www.saxonica.com/documentation/index.html#!conformance/xslt30.
Saxon6 Preferences
To configure the Saxon 6 options, open the Preferences dialog box and go to XML > XSLT/FO/XQuery > XSLT >
Saxon > Saxon 6.
Line numbering - Specifies whether line numbers are maintained and reported in error messages for the XML source
document.
Disable calls on extension functions - If enabled, external functions called is disallowed. Checking this is
recommended in an environment where untrusted stylesheets may be executed. Also disables user-defined extension
elements, together with the writing of multiple output files, all of which carry similar security risks.
Handling of recoverable stylesheet errors - Allows you to choose how dynamic errors are handled. One of the
following options can be selected:
Saxon-HE/PE/EE Preferences
To configure the Saxon HE/PE/EE options, open the Preferences dialog box and go to XML > XSLT/FO/XQuery >
XSLT > Saxon > Saxon HE/PE/EE.
Oxygen XML Editor allows you to configure the following XSLT options for the Saxon 9.6.0.7 Home Edition (HE),
Professional Edition (PE), and Enterprise Edition (EE):
Use a configuration file ("-config") - Sets a Saxon 9.6.0.7 configuration file that is executed for XSLT transformation
and validation processes.
Version warnings ("-versmsg") - Warns you when the transformation is applied to an XSLT 1.0 stylesheet.
Line numbering ("-l") - Error line numbers are included in the output messages.
Debugger trace into XPath expressions (applies to debugging sessions) - Instructs the XSLT DebuggerXSLT
Debugger to step into XPath expressions.
Expand attributes defaults ("-expand") - Specifies whether or not the attributes defined in the associated DTD
or XML Schema are expanded in the output of the transformation you are executing.
DTD validation of the source ("-dtd") - The following options are available:
On - Requests DTD validation of the source file and of any files read using the document() function.
Off - (default setting) Suppresses DTD validation.
Recover - Performs DTD validation but treats the errors as non-fatal.
Note: Any external DTD is likely to be read even if not used for validation, since DTDs can contain
definitions of entities.
Recoverable errors ("-warnings") - Policy for handling recoverable errors in the stylesheet: Allows you to choose
how dynamic errors are handled. One of the following options can be selected:
Strip whitespaces ("-strip") - Strip whitespaces feature can be one of the following three options:
All ("all") - Strips all whitespace text nodes from source documents before any further processing, regardless
of any xsl:strip-space declarations in the stylesheet, or any xml:space attributes in the source document.
Ignorable ("ignorable") - Strips all ignorable whitespace text nodes from source documents before any further
processing, regardless of any xsl:strip-space declarations in the stylesheet, or any xml:space attributes
in the source document. Whitespace text nodes are ignorable if they appear in elements defined in the DTD or
schema as having element-only content.
None ("none") - default setting. No whitespaces are stripped before further processing. However, whitespace
are stripped if this is specified in the stylesheet using xsl:strip-space.
Optimization level ("-opt") - Set the optimization level. The value is an integer in the range 0 (no optimization) to
10 (full optimization). This option allows optimization to be suppressed when reducing the compiling time is important,
Allow calls on extension functions ("-ext") - If checked, the stylesheet is allowed to call external Java functions.
This does not affect calls on integrated extension functions, including Saxon and EXSLT extension functions. This
option is useful when loading an untrusted stylesheet, such as from a remote site using an http://[URL]. It ensures
that the stylesheet cannot call arbitrary Java methods and thus gain privileged access to resources on your machine.
Register Saxon-CE extension functions and instructions - Registers the Saxon-CE extension functions and
instructions when compiling a stylesheet using the Saxon 9.6.0.7 processors.
Note: Saxon-CE, being JavaScript-based, was designed to run inside a web browser. This means that you
will use Oxygen XML Editor only for developing the Saxon-CE stylesheet, leaving the execution part to a
web browser. See more details about executing such a stylesheet on Saxonica's website.
The advanced options available only in Saxon Enterprise Edition (EE) are:
XML Schema version - Use this option to change the default XML Schema version. To change the default XML
Schema version, open the Preferences dialog box and go to XML > XML Parser > XML Schema.
Note: This option is available when you configure the Saxon EE advanced options from a transformation
scenario.
Validation of the source file ("-val") - Requests schema-based validation of the source file and of any files read
using the document() or similar functions. It can have the following values:
Schema validation ("strict") - This mode requires an XML Schema and specifies that the source documents
should be parsed with strict schema-validation enabled.
Lax schema validation ("lax") - If an XML Schema is provided, this mode enables parsing the source documents
with schema-validation enabled but the validation will not fail if, for example, element declarations are not found.
Disable schema validation - This specifies that the source documents should be parsed with schema-validation
disabled.
Validation errors in the results tree treated as warnings ("-outval") - Normally, if validation of result documents
is requested, a validation error is fatal. Enabling this option causes such validation failures to be treated as warnings.
Write comments for non-fatal validation errors of the result document - The validation messages are written
(where possible) as a comment in the result document itself.
Generate bytecode ("--generateByteCode:(on|off)") - If you enable this option, Saxon-EE attempts to generate
Java bytecode for evaluation of parts of a query or stylesheet that are amenable to such an action. For further details
regarding this option, go to http://www.saxonica.com/documentation9.5/index.html#!javadoc.
XSLTProc Preferences
To configure XSLTProc options, open the Preferences dialog box and go to XML > XSLT/FO/XQuery > XSLT >
XSLTProc.
The options of the XSLTProc processor are the same as the ones available in the command line:
Enable XInclude processing - If checked, XInclude references will be resolved when XSLTProc is used as transformer
in XSLT transformation scenarios.
Skip loading the document's DTD - If checked, the DTD specified in the DOCTYPE declaration will not be loaded.
Do not apply default attributes from document's DTD - If checked, the default attributes declared in the DTD
and not specified in the document are not included in the transformed document.
Do not use Internet to fetch DTD's, entities or docs - If checked, the remote references to DTD's and entities are
not followed.
Maximum depth in templates stack - If this limit of maximum templates depth is reached the transformation ends
with an error.
Verbosity - If checked, the transformation will output detailed status messages about the transformation process in
the Warnings view.
Show version of libxml and libxslt used - If checked, Oxygen XML Editor will display in the Warnings view the
version of the libxml and libxslt libraries invoked by XSLTProc.
Show time information - If checked, the Warnings view will display the time necessary for running the
transformation.
Show debug information - If checked, the Warnings view will display debug information about what templates
are matched, parameter values, and so on.
Show all documents loaded during processing - If checked, Oxygen XML Editor will display in the Warnings
view the URL of all the files loaded during transformation.
Show profile information - If checked, Oxygen XML Editor will display in the Warnings view a table with all the
matched templates, and for each template will display: the match XPath expression, the template name, the number
of template modes, the number of calls, the execution time.
Show the list of registered extensions - If checked, Oxygen XML Editor will display in the Warnings view a list
with all the registered extension functions, extension elements and extension modules.
Refuses to write to any file or resource - If checked, the XSLTProc processor will not write any part of the
transformation result to an external file on disk. If such an operation is requested by the processed XSLT stylesheet
the transformation ends with a runtime error.
Refuses to create directories - If checked, the XSLTProc processor will not create any directory during the
transformation process. If such an operation is requested by the processed XSLT stylesheet the transformation ends
with a runtime error.
MSXML Preferences
To configure the MSXML options, open the Preferences dialog box and go to XML > XSLT/FO/XQuery > XSLT >
MSXML.
The options of the MSXML 3.0 and 4.0 processors are the same as the ones available in the command line for the
MSXML processors:
Validate documents during parse phase - If checked and either the source or stylesheet document has a DTD or
schema against which its content can be checked, validation is performed.
Start transformation in this mode - Although stylesheet execution usually begins in the empty mode, this default
may be changed by specifying another mode. Changing the start mode allows execution to jump directly to an
alternate group of templates.
MSXML.NET Preferences
To configure the MSXML.NET options, open the Preferences dialog box and go to XML > XSLT/FO/XQuery >
XSLT > MSXML.NET.
The options of the MSXML.NET processor are:
Enable XInclude processing - If checked, XInclude references will be resolved when MSXML.NET is used as
transformer in the XSLT transformation scenario.
Validate documents during parse phase - If checked and either the source or stylesheet document has a DTD or
schema against which its content can be checked, validation is performed.
Do not resolve external definitions during parse phase - By default MSXML.NET resolves external definitions
such as DTD external subsets or external entity references when parsing source XML document and stylesheet
document. Using this option you can disable this behavior. Note, that it may affect also the validation process for
the XML document.
Strip non-significant whitespaces - If checked, strips non-significant white space from the input XML document
during the load phase. Enabling this option can lower memory usage and improve transformation performance while,
in most cases, creating equivalent output.
Show time information - If checked, the relative speed of various transformation steps can be measured:
Forces ASCII output encoding - There is a known problem with .NET 1.X XSLT processor
(System.Xml.Xsl.XslTransform class): it doesn't support escaping of characters as XML character references
when they cannot be represented in the output encoding. That means that when you output a character that cannot
be represented in output encoding, it will be outputted as '?'. Usually this happens when output encoding is set to
ASCII. With this option checked the output is forced to be ASCII encoded and all non-ASCII characters get escaped
as XML character references (&#nnnn; form).
Allow multiple output documents - This option allows to create multiple result documents using the
exsl:document extension element.
Use named URI resolver class - This option allows to specify a custom URI resolver class to resolve URI references
in xsl:import and xsl:include instructions (during XSLT stylesheet loading phase) and in document()
function (during XSL transformation phase).
Assembly file name for URI resolver class - The previous option specifies partially or fully qualified URI resolver
class name (for example, Acme.Resolvers.CacheResolver). Such name requires additional assembly
specification using this option or the next option, but fully qualified class name (which always includes an assembly
specifier) is all-sufficient. See MSDN for more info about fully qualified class names. This option specifies a file
name of the assembly, where the specified resolver class can be found.
XQuery Preferences
To configure the XQuery options, open the Preferences dialog box and go to XML > XSLT/FO/XQuery > XQuery.
The generic XQuery preferences are the following:
XQuery validate with - Allows you to select the processor that validates XQuery documents. If you are validating
an XQuery file that has an associated validation scenario, Oxygen XML Editor uses the processor specified in the
scenario. If no validation scenario is associated, but the file has an associated transformation scenario, the processor
specified in the scenario is used. If the processor does not support validation or if no scenario is associated, then the
value from this combo box will be used as validation processor.
Size limit of Sequence view (MB) - When the result of an XQuery transformation is set in the transformation
scenario as sequence the size of one chunk of the result that is fetched from the database in lazy mode in one step
is set in this option. If this limit is exceed, go to the Sequence view and click More results available to extract more
data from the database.
Format transformer output - Specifies whether the output of the transformer is formatted and indented (pretty
printed).
Note: This option is ignored if you choose Sequence (lazy extract data from a database) from the associated
transformation scenario.
Create structure indicating the type nodes - If checked, Oxygen XML Editor takes the results of a query and
creates an XML document containing copies of all items in the sequence, suitably wrapped.
Note: This option is ignored if you choose Sequence (lazy extract data from a database) from the associated
transformation scenario.
Use a configuration file ("-config") - Sets a Saxon 9 configuration file that is used for XQuery transformation and
validation
Recoverable errors ("-warnings")- Allows you to choose how dynamic errors are handled. The following options
can be selected:
All ("all") - Strips all whitespace text nodes from source documents before any further processing, regardless
of any xml:space attributes in the source document.
Ignore ("ignorable") - Strips all ignorable whitespace text nodes from source documents before any further
processing, regardless of any xml:space attributes in the source document. Whitespace text nodes are ignorable
if they appear in elements defined in the DTD or schema as having element-only content.
None ("none") - Strips no whitespace before further processing.
Optimization level ("-opt") - Set the optimization level. The value is an integer in the range 0 (no optimization) to
10 (full optimization). This option allows optimization to be suppressed when reducing the compiling time is important,
optimization conflicts with debugging, or optimization causes extension functions with side-effects to behave
unpredictably.
Use linked tree model ("-tree:linked") - This option activates the linked tree model.
Enable XQuery 3.0 support ("-qversion:(1.0|3.0)") - If checked, Saxon runs the XQuery transformation with the
XQuery 3.0 support (this option is enabled by default).
The following option is available for Saxon 9.6.0.7 Professional Edition (PE) and Enterprise Edition (EE) only:
Allow calls on extension functions ("-ext") - If checked, calls on external functions are allowed. Checking this
option is recommended in an environment where untrusted stylesheets may be executed. It also disables user-defined
extension elements and the writing of multiple output files, both of which carry similar security risks.
The options available specifically for Saxon 9.6.0.7 Enterprise Edition (EE) are as follows:
Validation of the source file ("-val") - Requests schema-based validation of the source file and of any files read
using the document() or similar functions. It can have the following values:
Schema validation ("strict") - This mode requires an XML Schema and enables parsing the source documents
with strict schema-validation enabled.
Lax schema validation ("lax") - If an XML Schema is provided, this mode enables parsing the source documents
with schema-validation enabled but the validation will not fail if, for example, element declarations are not found.
Disable schema validation - This specifies that the source documents should be parsed with schema-validation
disabled.
Validation errors in the results tree treated as warnings ("-outval") - Normally, if validation of result documents
is requested, a validation error is fatal. Enabling this option causes such validation failures to be treated as warnings.
Enable XQuery update ("-update:(on|off)") - This option controls whether or not XQuery update syntax is accepted.
The default value is off.
Backup files updated by XQuery ("-backup:(on|off)") - If checked, backup versions for any XML files updated
with XQuery Update are generated. This option is available when the Enable XQuery update option is enabled.
Collection URI Resolver class name - Allows you to specify a custom implementation for the Collection URI
resolver used by the XQuery Saxon 9.6.0.7 transformer (the -cr option when run from the command line). The class
name must be fully specified and the corresponding jar or class extension must be configured from the dialog box
for configuring the XQuery extension for the particular transformation scenario.
Debugger Preferences
To configure the Debugger preferences, open the Preferences dialog box and go to XML > XSLT/FO/XQuery >
Debugger.
The following preferences are available:
Show xsl:result-document output - if checked, the debugger presents the output of xsl:result-document
instructions into the debugger output view.
Infinite loop detection - set this option to receive notifications when an infinite loop occurs during transformation.
Maximum depth in templates stack - sets how many xsl:template instructions can appear on the current
stack. This setting is used by the infinite loop detection.
Debugger layout - a horizontal layout means that the stack of XML editors takes the left half of the editing area and
the stack of XSL editors takes the right one. A vertical layout means that the stack of XML editors takes the upper
half of the editing area and the stack of XSL editors takes the lower one.
Debugger current instruction pointer - controls the background color of the current execution node, both in the
document (XML) and XSLT/XQuery views.
XWatch evaluation timeout (seconds) - specifies the maximum time that Oxygen XML Editor allocates to the
evaluation of XPath expressions while debugging.
Messages - specifies whether a debugging session is stopped, is continued, or you are asked what to do when you
are editing the source document involved in a debugging session.
Profiler Preferences
This section explains the settings available for the XSLT Profiler. To access and modify these settings, open the
Preferences dialog box and go to XML > XSLT/FO/XQuery > Profiler (see Debugger Preferences on page 1208).
The following profile settings are available:
Show time - Shows the total time that was spent in the call.
Show inherent time - Shows the inherent time that was spent in the call. The inherent time is defined as the total
time of a call minus the time of its child calls.
Show invocation count - Shows how many times the call was called in this particular call sequence.
Time scale - The time scale options determine the unit of time measurement, which may be milliseconds or
microseconds.
Hotspot threshold - The threshold below which hot spots are ignored (milliseconds).
Ignore invocation less than - The threshold below which invocations are ignored (microseconds).
Percentage calculation - The percentage base that determines what time span percentages are calculated against:
FO Processors Preferences
Oxygen XML Editor includes a built-in formatting objects processor (Apache FOP), but you can also configure other
external processors and use them in the transformation scenarios for processing XSL-FO documents.
Command line
The command line that starts the FO processor, specific to each processor. You can use one of the following editor
variables:
Output Encoding
The encoding of the FO processor output stream that is displayed in a results panel at the bottom of the Oxygen
XML Editor window.
Error Encoding
The encoding of the FO processor error stream that is displayed in a results panel at the bottom of the Oxygen XML
Editor window.
XPath Preferences
To configure the XPath options, open the Preferences dialog box and go to XML > XSLT/FO/XQuery > XPath.
Oxygen XML Editor allows you to customize the following options:
Unescape XPath expression - the entities of an XPath expressions that you type in the XPath/XQuery Builder and
the XPath toolbar are unescaped during their execution. For example the expression
//varlistentry[starts-with(@os,'s')]
is equivalent with:
//varlistentry[starts-with(@os,'s')]
Multiple XPath results - enable this option to display the results of an XPath in separate tabs in the The Results
View on page 86.
No namespace - if you enable this option, Oxygen XML Editor considers unprefixed element names of the evaluated
XPath 2.0 / 3.0 expressions as belonging to no namespace.
Use the default namespace from the root element - if you enable this option, Oxygen XML Editor considers
unprefixed element names of the evaluated XPath expressions as belonging to the default namespace declared on
the root element of the XML document you are querying.
Engine type - Combo box allowing you to choose the transformer type. There are two options: XSLT engines and
XQuery engines.
Name - The name of the transformer displayed in the dialog box for editing transformation scenarios
Description - A textual description of the transformer.
Working directory - The start directory of the transformer executable program. The following editor variables are
available for making the path to the working directory independent of the location of the input files:
Command line - The command line that must be executed by Oxygen XML Editor to perform a transformation with
the engine. The following editor variables are available for making the parameters in the command line (the transformer
executable, the input files) independent of the location of the input files:
Ant Preferences
To set Ant preferences, open the Preferences dialog box and go to XML > Ant. This panel allows you to choose the
directory containing the Apache Ant libraries (the so-called Ant Home) that Oxygen XML Editor uses to handle Ant
build files.
There are two options available:
Built-in - the path to the Ant distribution that comes bundled with Oxygen XML Editor installation kit.
Custom - the path to an Ant distribution of your choice.
Import Preferences
To configure the Import options, open the Preferences dialog box and go to XML > Import. This page allows you to
configure how empty values and null values are handled when they are encountered in imported database tables or
Excel sheets. Also you can configure the format of date / time values recognized in the imported database tables or Excel
sheets.
The following options are available:
Create empty elements for empty values - If checked, an empty value from a database column or from a text file
is imported as an empty element.
Create empty elements for null values - If checked, null values from a database column are imported as empty
elements.
Escape XML content - Enabled by default, this option instructs Oxygen XML Editor to escape the imported content
to an XML-safe form.
Add annotations for generated XML Schema - If checked, the generated XML Schema contains an annotation
for each of the imported table columns. The documentation inside the annotation tag contains the remarks of the
database columns (if available) and also information about the conversion between the column type and the generated
XML Schema type.
The section Date / Time Format specifies the format used for importing date and time values from Excel spreadsheets
or database tables and in the generated XML schemas. The following format types are available:
Unformatted - If checked, the date and time formats specific to the database are used for import. When importing
data from Excel a string representation of date or time values are used. The type used in the generated XML Schema
is xs:string.
XML Schema date format - If checked, the XML Schema-specific format ISO8601 is used for imported date / time
data (yyyy-MM-dd'T'HH:mm:ss for datetime, yyyy-MM-dd for date and HH:mm:ss for time). The
types used in the generated XML Schema are xs:datetime, xs:date and xs:time.
Custom format - If checked, you can define a custom format for timestamp, date, and time values or choose one of
the predefined formats. A preview of the values is presented when a format is used. The type used in the generated
XML Schema is xs:string.
Examples
Era designator
Text
AD
Year
Year
1996; 96
Examples
Month in year
Month
July; Jul; 07
Week in year
Number
27
Week in month
Number
Day in year
Number
189
Day in month
Number
10
Number
Day in week
Text
Tuesday; Tue
Am / pm marker
Text
PM
Number
Number
24
Hour in am / pm (0-11)
Number
Hour in am / pm (1-12)
Number
12
Minute in hour
Number
30
Second in minute
Number
55
Millisecond
Number
978
Time zone
Time zone
-0800
Pattern letters are usually repeated, as their number determines the exact presentation:
Text - If the number of pattern letters is 4 or more, the full form is used; otherwise a short or abbreviated form is
used if available.
Number - The number of pattern letters is the minimum number of digits, and shorter numbers are zero-padded to
this amount.
Year - If the number of pattern letters is 2, the year is truncated to 2 digits; otherwise it is interpreted as a number.
Month - If the number of pattern letters is 3 or more, the month is interpreted as text; otherwise, it is interpreted as
a number.
General time zone - Time zones are interpreted as text if they have names. For time zones representing a GMT offset
value, the following syntax is used:
Hours must be between 0 and 23, and Minutes must be between 00 and 59. The format is locale independent and
digits must be taken from the Basic Latin block of the Unicode standard.
RFC 822 time zone: The RFC 822 4-digit time zone format is used:
Keystore type - The type of keystore that Oxygen XML Editor uses (JKS or PKCS-12).
Keystore file - The location of the imported file.
Keystore password - The password that is used for protecting the privacy of the stored keys.
Certificate alias - The alias used for storing the key entry (the certificate or the private key) inside the keystore.
Private key password - The private key password of the certificate (required only for JKS keystores).
Validate - Press this button to verify the configured keystore and the validity of the certificate.
Load additional refactoring operations from - Use this text box to specify a folder for loading custom XML
refactoring operations. You can use editor variables by pressing the
Insert Editor Variable button or search
for a folder by using the
Browse button.
DITA Preferences
To access the DITA Preferences page, open the Preferences dialog box and go to DITA. This preferences page includes
the following sections and options:
DITA Open Toolkit Section
This section allows you to specify the default directory of the DITA Open Toolkit distribution (bundled with the Oxygen
XML Editor installation) to be used for validating and publishing DITA content. You can select from the following:
Built-in DITA-OT 1.8 - This is the default setting and the default DITA OT directory is:
[OXYGEN_DIR]/frameworks/dita/DITA-OT.
Built-in DITA-OT 2.x (with experimental DITA 1.3 support) - All defined DITA transformation scenarios will
run with DITA-OT 2.x. This also gives you access to new DITA 1.3 file templates when you create new documents
from templates. The default DITA OT directory is: [OXYGEN_DIR]/frameworks/dita/DITA-OT2.x.
Custom - In the Location field, you can either provide a new file path for the specific DITA OT that you want to
use or you can select a previously used one from the drop-down list.
The DITA Maps file patterns option allows you to set the extension of the files that will be handled as DITA maps
when opened in Oxygen XML Editor. Oxygen XML Editor can open a DITA map in the regular editor view or in the
DITA Maps Manager.
The following options are available When opening a map:
The Show console output option allows you to specify when to display the console output log. The following options
are available:
When build fails - displays the console output log if the build fails.
Always - displays the console output log, regardless of whether or not the build fails.
The following options are available for the Insert Reference and Edit Properties operations:
Always fill values for attributes - Allows you to specify that in the Insert Reference\Edit Properties dialog box,
the values for these attributes will be automatically populated with a detected value (based on the specifications),
even if it is the same as the default value.
At the bottom of the page there is a link to the Profiling Attributes preferences, where you can configure how profiling
and conditional text is displayed in Author mode.
Name - The name of the new data source driver that will be used for creating connections to the database.
Type - Selects the data source type from the supported driver types.
Help button - Opens the User Manual at the list of the sections where the configuration of supported
data sources is explained and the URLs for downloading the database drivers are specified.
Driver files (JAR, ZIP) - Lists download links for database drivers that are necessary for accessing databases
in Oxygen XML Editor.
Add Files - Adds the driver class library.
Add Recursively - Adds driver files recursively.
Remove - Removes the selected driver class library from the list.
Detect - Detects driver file candidates.
Stop - Stops the detection of the driver candidates.
Driver class - Specifies the driver class for the data source driver.
Edit
Opens the Data Sources Drivers dialog box for editing the selected driver. See above the specifications for the
Data Sources Drivers dialog box. In order to edit a data source, there must be no connections using that data source
driver.
Duplicate
Creates a copy of the selected data source.
Delete
Deletes the selected driver. In order to delete a data source, there must be no connections using that data source
driver.
Name - The name of the new connection that will be used in transformation scenarios and validation scenarios.
Data Source - Allows selecting a data source defined in the Data Source Drivers dialog box.
Depending upon the selected data source, you can set some of the following parameters in the Connection details
area:
Edit
Opens the Connection dialog box, allowing you to edit the selected connection. See above the specifications for
the Connection dialog box.
Duplicate
Creates a copy of the selected connection.
Delete
Deletes the selected connection.
Move Up
Moves the selected connection up one row in the list.
Move Down
Moves the selected connection down one row in the list.
Limit the number of cells
For performance issues, you can set the maximum number of cells that will be displayed in the Table Explorer
view for a database table. Leave this field empty if you want the entire content of the table to be displayed. By
default, this field is set to 2000. If a table that has more cells than the value set here is displayed in the Table
Explorer view, a warning dialog box will inform you that the table is only partially shown.
Maximum number of children for container nodes
In Oracle XML, a container can hold millions of resources. If the node corresponding to such a container in the
Data Source Explorer view would display all the contained resources at the same time, the performance of the
view would be very slow. To prevent this, only a limited number of the contained resources is displayed as child
nodes of the container node. Navigation to other contained resources from the same container is enabled by the Up
and Down buttons in the Data Source Explorer view. This limited number is set in the field. The default value is
200 nodes.
Download Links for Database Drivers
Below you can find instructions for getting the drivers that are necessary to access databases in Oxygen XML Editor.
Berkeley DB XML database - Copy the jar files from the Berkeley database install directory into the Oxygen XML
Editor install directory as described in the procedure for configuring a Berkeley DB data source.
IBM DB2 Pure XML database - Go to the IBM website and in the DB2 Clients and Development Tools category
select the DB2 Driver for JDBC and SQLJ download link. Fill out the download form and download the zip file.
Unzip the zip file and use the db2jcc.jar and db2jcc_license_cu.jar files in Oxygen XML Editor for
configuring a DB2 data source.
eXist database - Copy the jar files from the eXist database install directory to the Oxygen XML Editor install
directory as described in the procedure for configuring an eXist data source.
MarkLogic database - Download the MarkLogic driver from MarkLogic Community site.
Microsoft SQL Server 2005 / 2008 database - Download the appropriate MS SQL JDBC driver from the Microsoft
website. For SQL Server 2008 R2 and older go to http://www.microsoft.com/en-us/download/details.aspx?id=21599.
For SQL Server 2012 and 2014 go to http://www.microsoft.com/en-us/download/details.aspx?id=11774.
Oracle 11g database - Go to the Oracle website and download the Oracle 11g JDBC driver called ojdbc6.jar.
PostgreSQL 8.3 database - Go to the PostgreSQL website and download the PostgreSQL 8.3 JDBC driver called
postgresql-8.3-603.jdbc3.jar.
Documentum xDb (X-Hive/DB) 10 XML database - Copy the jar files from the Documentum xDb (X-Hive/DB)
10 database install directory to the Oxygen XML Editor install directory as described in the procedure for configuring
a Documentum xDb (X-Hive/DB) 10 data source.
SVN Preferences
To configure the SVN options, open the Preferences dialog box and go to SVN. In this preferences page, the user
preferences for the embedded SVN client tool are configured. Some other preferences for the embedded SVN client
tool can be set in the global files called config and servers. These files contain parameters that act as defaults
applied to all the SVN client tools that are used by the same user on his login account on the computer. To open these
files for editing, launch the embedded SVN client tool (Tools >
SVN Client) and select Global Runtime
Configuration > Edit 'config' file or Global Runtime Configuration > Edit 'servers' file from the SVN client Options
menu.
Enable symbolic link support (available only on Mac OS X and Linux) - Apache Subversion has the ability to
put a symbolic link under version control, via the usual SVN add command. The Subversion repository has no
internal concept of a symbolic link. It stores a versioned symbolic link as an ordinary file with a svn:special
property attached. On Unix/Linux, the SVN client sees the property and translates the file into a symbolic link in
the working copy. If the symbolic link support is disabled, the versioned symbolic links appear as a text file instead
of symbolic link.
Note: Windows file systems have no symbolic links, so a Windows client will not do any such translation
and the object appears as a normal file.
Allow unversioned obstructions - Controls how to handle a situation where working copy resources are ignored /
unversioned when performing an update operation and incoming files (from the repository) with the same name and
location intersect with those being ignored / unversioned. If the option is enabled, the incoming items will become
BASE revisions of the ones already present in the working copy, and those present will be made versioned resources
and will be marked as modified (exactly as if the user first made the update operation and then modified the files).
If the option is disabled, the update operation will fail when encountering files in this situation, possibly leaving
other files not updated. By default, this option is enabled.
Use unsafe copy operations - Sometimes when the working copy is accessed through Samba and the SVN client
cannot make a safe copy of the committed file due to a delay in getting a write permission, the result is that the
committed file will be saved with zero length (the content is removed) and an error will be reported. In this case,
this option should be selected so that the SVN client does not try to make the safe copy.
HTTPS encryption protocols (available if you are using Java version 1.6 or older) - Sets a specific encryption
protocol to be used when the application accesses a repository through HTTPS protocol. You can choose one of the
following values:
Results Console - Specifies the maximum number of lines displayed in the Console view. The default value is 1000.
Annotations View - Sets the color used in the editor panel for highlighting all the changes contributed to a resource
by the revision selected in the Annotations view.
Revision Graph - Enables caching for the action of computing a revision graph. When a new revision graph is
requested, one of the caches from the previous actions may be used that will avoid running the whole query again
on the SVN server. If a cache is used, it will finish the action much faster.
Working copies location - Allows you to define a location where you keep your working copies. This location is
automatically suggested when you checkout a new working copy.
Working copy administrative directory - Allows you to customize the directory name where the svn entries are
kept for each directory in the working copy.
When loading an old format working copy - You can instruct Syncro SVN Client to do one of the following:
Always ask - You are notified when such a working copy is used and you are allowed to choose what action to
be taken - to upgrade or not the format of the current working copy.
Never upgrade - Older format working copies are left untouched. No attempt to upgrade the format is made.
Note: SVN 1.6 and older working copies still need to be upgraded before loading them.
Enable working copy caching - If checked, the content of the working copies is cached for refresh operations.
Automatically refresh the working copy - If checked, the working copy is refreshed from cache. Only the new
changes (modifications with a date/time that follows the last refresh operation) are refreshed from disk. Disabled by
default.
Allow moving/renaming mixed revision directories - If enabled, the Syncro SVN Client will allow you to move
or rename a directory even if its child items have a different revision. Otherwise, an error message is displayed when
there are multiple revisions to avoid unnecessary conflicts. It is recommended to leave this option disabled and to
Update the subtree to a single revision before moving or renaming it.
Always switch to 'Modified' mode - The Synchronize action is followed automatically by a switch to Modified
mode of Working Copy view, if All Files mode is currently selected.
Never switch to 'Modified' mode - Keeps the currently selected view mode unchanged.
Always ask - The user is always asked if he wants to switch to Modified mode.
Application global ignores - Allows setting file patterns that may include the * and ? wildcards for unversioned
files and folders that must be ignored when displaying the working copy resources in the Working Copy view. These
patterns are case-sensitive. For example,*.txt matches file.txt, but does not match file.TXT.
Diff Preferences
To configure the SVN Diff options, open the Preferences dialog box and go to Diff.
Show pseudo conflicts - Specifies whether the the Compare view displays pseudo-conflicts . A pseudo-conflict
occurs when two developers make the same change, for example when they both add or remove the same line of
code.
Compare With External Application - Specifies an external application to be launched for compare operations in
the following cases:
The parameters ${firstFile} and ${secondFile} specify the positions of the two compared files in the command line
for the external diff application. The parameter ${ancestorFile} specifies the common ancestor (that is, the BASE
revision of a file) in a three-way comparison. The working copy version of a file is compared with the repository
version, with the BASE revision (the latest revision read from the repository by an Update or Synchronize operation)
being the common ancestor of these two compared versions.
Important: If the path to the external compare application includes spaces (or any of the subsequent options
or arguments), then each of these paths or tokens must be double-quoted for the Oxygen XML Editor to
correctly parse and identify them. For example, C:\Program Files\compareDir\app name.exe
must be written as "C:\Program Files\compareDir\app name.exe".
Maximum number of differences - Sets the maximum number of differences allowed in the view.
Messages Preferences
To configure the options for Messages, open the Preferences dialog box and go to SVN > Messages. This preferences
page allows you to disable the following warning messages which may appear in the application:
Show confirmation dialog when using the "Update All" action - Allows you to avoid performing accidental
update operations by requesting you to confirm them before execution.
Show confirmation dialog for drag and drop actions in Working Copy - This option avoids doing a drag and
drop when you just want to select multiple files in the Working Copy view.
Show warning dialog when editing conflicts - When the Edit Conflicts action is executed, a warning dialog box
notifies you that the action overwrites the conflicted version of the file created by an update operation. The conflicted
file is overwritten with the version of the same file which existed in the working copy before the update operation
and then proceeds with the visual editing of the conflicting file.
Show warning dialog when "svn:externals" definitions are ignored - A warning dialog box is displayed when
"svn:externals" definitions are ignored before performing any operation that updates resources of the working copy
(like Update and Override and Update).
Diff Preferences
The Diff Preferences Page has sub-pages for configuring File Comparisons and Directory Comparisons.
Files Comparison Preferences
To configure the Files Comparison options, open the Preferences dialog box and go to Diff > Files Comparison. This
preferences page allows you to configure the following options:
Default algorithm - the default algorithm used for comparing files. The following options are available:
Auto - automatic selection of the diff algorithm, based on the content and size
Algorithm strength - controls the amount of resources allocated to the application to perform the comparison. The
algorithm stops searching more differences when reaches the maximum allowed resources. A dialog box is displayed
when this limit is reached and partial results are displayed. Four settings are available: Low, Medium (default),
High and Very High.
Ignore Whitespaces - ignoring whitespaces means that before performing the comparison, the application normalizes
the content (collapses any sequence of whitespace characters (space, newline or tab characters) into a single space)
and trims its leading and trailing whitespaces.
Note: If the Ignore Whitespaces check box is selected, comparing the a b sequence with a b, Oxygen
XML Editor finds no differences, because after normalization, all whitespaces from the first sequence are
collapsed into a single space character. However, when comparing a b with ab (no whitespace between a
and b), Oxygen XML Editor signals a difference.
XML Diff Options - this set of options allows you to specify the types of XML nodes for which the differences will
be ignored (will not be reported) by the XML Fast and XML Accurate algorithms.
Merge adjacent differences - considers two adjacent differences as one when the differences are painted in the
side-by-side editors. If unchecked, every difference is represented separately.
Mark end tags as different for modified elements - end tags of modified elements are presented as differences
too, otherwise only the start tags are presented as differences.
Ignore expansion state for empty elements - empty elements in both expansion states are considered matched, that
is <element/> and <element></element> are considered equal.
Appearance Preferences
To configure the appearance options for the Files Comparison tool, open the Preferences dialog box and go to Diff >
Files Comparison > Appearance. This preferences page offers the following options:
Line wrap - Wraps at the right margin of each panel the lines presented in the two diff panels, so no horizontal
scrollbar is necessary.
Incoming color - Specifies the color used for incoming changes on the vertical bar, that shows the differences
between the compared files.
Outgoing color - Specifies the color used for outgoing changes on the vertical bar, that shows the differences between
the compared files.
Conflict color - Specifies the color used for conflicts on the vertical bar, that shows the differences between the
compared files.
Compare files by - Controls the method used for comparing two files:
Content - The file content is compared using the current diff algorithm. This option is applied for a pair of files
only if that file type is associated with a built-in editor type (either associated by default or associated by the user
when prompted to do so on opening a file of that type for the first time).
Binary Compare - The files are compared at byte level.
Timestamp (last modified date / time) - The files are compared only by their last modified timestamp.
Look in archives - If checked, archives known by Oxygen XML Editor are considered directories and their content
is compared just like regular files.
Navigation - This options control the behavior of the differences traversal actions (Go to previous modification,
Go to next modification) when the first or last difference in a file is reached:
Ask what to do next - A dialog box is displayed asking you to confirm that you want the application to display
modifications from the previous or next file.
Go to the next/previous file - The application opens the next or previous file without waiting for your confirmation.
Do nothing - No further action is taken.
Appearance Preferences
To configure the appearance options for the Directories Comparison tool, open the Preferences dialog box and go to
Diff > Directories Comparison > Appearance.
Added/Deleted - Color used for marking added or deleted files and folders.
Modified - Color used for marking modified files.
Archive Preferences
To configure Archive preferences, open the Preferences dialog box and go to Archive.
The following options are available in the Archive preferences panel:
Archive backup options - Controls if the application makes backup copies of the modified archives. The following
options are available:
Always create backup copies of modified archives - When you modify an archive, its content is backed up.
Never create backup copies of modified archives - No backup copy is created.
Ask for each archive once per session - Once per application session for each modified archive, user confirmation
is required to create the backup. This is the default setting.
Note: Backup files have the name originalArchiveFileName.bak and are located in the same
folder as the original archive.
Archive types - This table contains all known archive extensions mapped to known archive formats. Each row maps
a list of extensions to an archive type supported in Oxygen XML Editor. You can edit an existing mapping or create
a new one by associating your own list of extensions to an archive format.
Store Unicode file names in Zip archives - Use this option when you archive files that contain international (that
is, non-English) characters in file names or file comments. If this option is selected and an archive is modified in
any way, UTF-8 characters are used in the names of all files in the archive.
Plugins Preferences
You are able to add plugins that extend the functionality of Oxygen XML Editor. The plugins are shipped as separate
packages. To check for new plugins, go to http://www.oxygenxml.com/oxygen_sdk.html.
A plugin consists of a separate sub-folder in the Plugins folder of the Oxygen XML Editor installation folder. This
sub-folder must contain a valid plugin.xml file in accordance with the plugin.dtd file located in the Plugins
folder.
Oxygen XML Editor automatically detects and loads plugins installed correctly in the Plugins folder and displays
them in the Plugins preferences page. To configure plugins, open the Preferences dialog box and go to Plugins.
You can use the check-boxes in front of each plugin to enable or disable them. To display the properties of a plugin in
the second section of the Plugins preferences page, click the name of the plugin.
Name - The name of the menu entry corresponding to this tool that will be displayed in the Tools > External Tools
menu and in the External Tools drop-down menu in the Tools toolbar.
Description - The description of the tool displayed as tooltip where the tool name is used.
Working directory - The directory the external tool will use to store intermediate and final results. Here you can
use one of the following editor variables: ${cfd}, ${pd}, ${oxygenInstallDir}, ${homeDir}, ${system(var.name)},
${date(pattern)}, ${xpath_eval(expression)}.
Command line - The command line that will start the external tool. Here you can use one of the following editor
variables: ${homeDir}, ${home}, ${cfn}, ${cfne}, ${cf}, ${currentFileURL}, ${cfd}, ${cfdu}, ${tsf}, ${pd}, ${pdu},
${oxygenInstallDir}, ${oxygenHome}, ${frameworksDir}, ${frameworks}, ${ps}, ${timeStamp}, ${uuid}, ${id},
${afn}, ${afne}, ${af}, ${afu}, ${afd}, ${afdu}, ${ask('message', type, 'default_value')}, ${dbgXML}, ${dbgXSL},
${env(VAR_NAME)}, ${system(var.name)}, ${date(pattern)}, and ${xpath_eval(expression)}
Show output messages - When this option is checked all the messages emitted by the external tool are displayed in
the Results view. You can edit the following options:
Output encoding - The encoding of the output stream of the external tool that will be used byOxygen XML
Editor to read the output of the tool.
Output content type - A list of predefined content type formats that instructOxygen XML Editor how to display
the generated output. For example, setting the Output content type to text/xml enables the syntax coloring
of XML output.
When this option is unchecked only the error messages are displayed.
Error Encoding - The encoding of the error stream of the external tool that will be used byOxygen XML Editor to
read this error stream.
Shortcut key - The keyboard shortcut that launches the external tool.
Extension - The extensions of the files that will be associated with an editor type.
Editor - The type of editor which the extensions will be associated with. Some editors provide easy access to frequent
operations via toolbars (XML editor, XSL editor, DTD editor) while others provide just a syntax highlight scheme
(Java editor, SQL editor, Shell editor, etc.).
If the editor set here is not one of the XML editors (XML editor, XSL editor, XSD editor, RNG editor, WSDL editor)
then the encoding set in the preference Encoding for non XML files is used for opening and saving a file of this
type.
The files that match the Ant build patterns will be associated with the Ant editor.
The files that match the Binary file patterns patterns are handled as binary and opened in the associated system
application. Also, they are excluded from the following actions available in the Project view: File/Replace in Files,
Check Spelling in Files, Validate.
Limit search results to - specifies the maximum number of results that are displayed in the Open/Find Resource
dialog box or in the Open/Find Resources view.
Enable searching in content - enable this option to activate the In content option of the Open/Find Resource view
and Open/Find Resource dialog box. In case this option is disabled you can only use the Open/Find Resource
feature to search in file paths.
Ignore content of these files - allows you to select specific directories, files, or file types that are ignored when you
perform a search. For example, *.txt ignores all the .txt files, */topics/* ignores all the files from the
topics directory, regardless of their depth, and file:/C:/tmp/* ignores everything from the tmp directory.
Note: The specified pattern must begin with the desired protocol (in our case file) and also contain forward
flash (/).
Exact matches - this option controls whether the search results should exactly match the whole words that you
introduce in the search field of the Open/Find Resource dialog box or Open/Find Resources view.
Prefix matches - this option controls whether the search results should match documents containing words starting
with the searched terms. For instance searching for "pref page" will find documents containing also "preference
pages".
Automatically join search terms using: - select the default boolean operator that Oxygen XML Editor applies
when you perform a search. For example if the AND operator is selected and you enter "car assembly" in the dialog
box, the resulted documents must contain both of the words. If you choose OR, the resulted documents must contain
one of the selected search terms. Results containing both words are promoted to the top of the list.
Enable XML-aware searching for files with size less than - allows you to perform an XML specific search for
XML elements and attributes.
Note: Enabling this option may slow down the indexing of your documents and increase the index size on
the disk.
Stop Words - list of comma separated stop words. Words added in this list are filtered out prior to processing a
search query.
Direct connection - Specifies whether the HTTP(S) connections go directly to the target host without going through
a proxy server.
Use system settings - Specifies whether the HTTP(S) connections go through the proxy server set in the operating
system. For example, on Windows the proxy settings are the ones that Internet Explorer uses.
Attention: The system settings for the proxy cannot be read correctly from the operating system on some
Linux systems. The system settings option should work properly on Gnome based Linux systems, but it does
not work on KDE based ones as the Java virtual machine does not offer the necessary support yet.
Manual proxy configuration - Specifies whether the HTTP(S) connections go through the proxy server specified
in the Address and Port fields.
No proxy for - Specifies the hosts to which the connections must not go through a proxy server. A host needs to be
written as a fully qualified domain name (for example, myhost.example.com) or as a domain name (for example,
example.com). Use comma as a separator between multiple hosts.
User - Specifies the user necessary for authentication with the proxy server.
Password - Specifies the password necessary for authentication with the proxy server.
SOCKS Proxy - In this section you set the host and port of a SOCKS proxy through which all the connections pass.
If the Address field is empty the connections use no SOCKS proxy.
Internal Apache HttpClient Version - Oxygen XML Editor uses the Apache HttpClient to establish connections
to HTTP servers. To enable Oxygen XML Editor to benefit from particular sets of features provided by different
versions, you may choose between v3 and v4.
Note: For a full list of features, go to http://hc.apache.org/httpclient-3.x/ and
http://hc.apache.org/httpcomponents-client-ga/
Maximum number of simultaneous connections per host - Defines the maximum number of simultaneous
connections established by the application with a distinct host. Servers might consider multiple connections opened
from the same source to be a Denial of Service attack. You can avoid that by lowering the value of this option.
Note: This option accepts a minimum value of 5.
Read Timeout (seconds) - The period in seconds after which the application considers that an HTTP server is
unreachable if it does not receive any response to a request sent to that server.
Enable HTTP 'Expect: 100-continue ' handshake for HTTP/1.1 protocol - Activates Expect: 100-Continue
handshake. The purpose of the Expect: 100-Continue handshake is to allow a client that is sending a request message
with a request body to determine if the origin server is willing to accept the request (based on the request headers)
before the client sends the request body. The use of the Expect: 100-continue handshake can result in noticeable
performance improvement when working with databases. The Expect: 100-continue handshake should be used with
caution, as it may cause problems with HTTP servers and proxies that do not support the HTTP/1.1 protocol.
When unchecked, the resource type is determined by analyzing its extension. For example, a file ending in .xml is
considered to be an XML file.
Automatic retry on recoverable error - If enabled, if an HTTP error occurs when Oxygen XML Editor communicates
with a server via HTTP, for example sending / receiving a SOAP request / response to / from a Web services server,
and the error is recoverable, Oxygen XML Editor tries to send again the request to the server.
Automatically accept a security certificate, even if invalid - When enabled, the HTTPS connections that Oxygen
XML Editor attempts to establish will accept all security certificates, even if they are invalid.
Important: By accepting an invalid certificate, you accept at your own risk a potential security threat, since
you cannot verify the integrity of the certificate's issuer.
Encryption protocols (SVN Client only) - this option is available only if you run the application with Java 1.6 or
older. Sets a specific encryption protocol used when a repository is accessed through HTTPS protocol. You can
choose one of the following values:
Lock WebDAV files on open - If checked, the files opened through WebDAV are locked on the server so that they
cannot be edited by other users while the lock placed by the current user still exists on the server.
(S)FTP Preferences
To configure the (S)FTP options, open the Preferences dialog box and go to Network Connection Settings > (S)FTP.
You can customize the following options:
Encoding for FTP control connection - The encoding used to communicate with FTP servers: either ISO-8859-1
or UTF-8. If the server supports the UTF-8 encoding Oxygen XML Editor will use it for communication. Otherwise
it will use ISO-8859-1.
Public known hosts file - File containing the list of all SSH server host keys that you have determined are accurate.
The default value is ${homeDir}/.ssh/known_hosts.
Private key file - The path to the file containing the private key used for the private key method of authentication
of the secure FTP (SFTP) protocol. The user / password method of authentication has precedence if it is used in the
Open URL dialog box.
Passphrase - The passphrase used for the private key method of authentication of the secure FTP (SFTP) protocol.
The user / password method of authentication has precedence if it is used in the Open URL dialog box.
New - Allows you to manually add a new entry in the list of trusted hosts.
Delete - Allows you to remove an entry from the trusted hosts list.
SSH Preferences
To configure the SSH options, open the Preferences dialog box and go to Connection settings > SSH. The following
options are available:
SSH - Specifies the command line for an external SSH client that will be used when connecting to a SVN+SSH
repository. Absolute paths are recommended for the SSH client executable and the file paths given as arguments (if
any). Depending on the SSH client used and your SSH server configuration, you may need to specify the user name
and/or private key/passphrase in the command line . You can also choose whether to use the Default SVN user (the
same user name as the SSH client user) or Prompt for a SVN user for SVN repository operations whenever SVN
authentication is required. For example, on Windows the following command line uses the plink.exe tool as the
external SSH client for connecting to the SVN repository with SVN+SSH:
C:\plink-install-folder\plink.exe -l username -pw password -ssh -batch
host_name_or_IP_address_of_SVN_server
Preferred attribute names for display - The preferred attribute names when displaying the attributes of an element
in the Outline view. If there is no preferred attribute name specified, the first attribute of an element is displayed.
Enable outline drag and drop - Drag and drop is disabled for the tree displayed in the Outline view only if there
is a possibility to accidentally change the structure of the document by such operations.
Views Preferences
To configure the view options, open the Preferences dialog box and go to Views and contains the following preferences:
Enable drag-and-drop in Project view - Enables the drag and drop support in Project view. It should be disabled
only if there is a possibility to accidentally change the structure of the project by such drag and drop actions.
Format and indent on save - If selected, Oxygen XML Editorwill run the action Format and Indent (pretty-print)
on saving a document edited in the tree editor.
Maximum number of lines - Sets the maximum number of lines in the Information view.
Messages Preferences
To configure the Messages options, open the Preferences dialog box and go to Messages. This preferences page allows
you to disable the following warning messages which may appear in the application:
Show confirmation dialog when moving resources - Displays a confirmation dialog box when you move a resource
in the Project view, DB Explorer, and Archive Browser. In the Confirm dialog box you are able to choose not to
see this dialog box in the future.
Show warning when adding resources already included in the project - Displays a dialog box that warns you if
you try to add already existing files in your project.
Show warning for document size limit for bidirectional text, Asian languages, and other special characters Displays a warning dialog box when the opened file that contains bidirectional characters is too large and bidirectional
support is disabled.
Configuring Options
A set of options controls the behavior of Oxygen XML Editor, allowing you to configure most of the features. To offer
you the highest degree of flexibility in customizing the application to fit the needs of your organization, Oxygen XML
Editor comes with several distinct layers of option values.
In the [OXYGEN_DIR] installation folder, create a folder called preferences and copy the XML options file
into it (for example, [OXYGEN_DIR]/preferences/default.xml).
Set the path to the XML options file as the value of the com.oxygenxml.default.options system property
in the startup parameters.
The path must be specified with a URL or file path relative to the application installation folder:
-Dcom.oxygenxml.default.options=options/default.xml
Note: If you are using the Java Webstart distribution, use the optionsDir property to specify the path
of the options file (in this case, the file needs to be named default.xml), or you can edit the .jnlp file
that launches the application and set the com.oxygenxml.default.options parameter using a
property element, as in the following example:
<property name="oxy:com.oxygenxml.default.options"
value="http://host/path/to/default.xml"/>
Project Options
If you select Project Options, the preferences are stored in the project file and can be shared with other users. For
instance, if your project file is saved on a version control system (such as SVN, CVS, or Source Safe) or in a shared
folder, your team will have the same option configuration that you stored in the project file.
Notice: Some pages do not have the Project Options switch, since the options they host might contain sensitive
data (passwords, for example), unsuitable for sharing with other users.
Note: If changes have been made to the options in a preferences page and you switch between Project Options
and Global Options, a dialog box will be displayed that allows you to select one of the following:
Overwrite - The existing options from the current preferences page will be overwritten.
Preserve - The existing options from the current preferences page will be preserved.
For more information about sharing project files, see the Sharing a Project - Team Collaboration on page 164 section.
The name of the options file of Oxygen XML Editor 17.1 is oxyOptionsSa17.1.xml.
Split horizontally - Splits the editor horizontally. This is useful for comparing and merging content between
two documents.
Configure Toolbars
You can configure the toolbars in Oxygen XML Editor to personalize the interface for your specific needs. You can
choose which toolbars to show or hide in the current editor mode (Text, Author,Design, or Grid) and in the current
perspective (Editor, XSLT Debugger, XQuery Debugger, or Databse). You can also choose which actions to display
in each toolbar, add actions to toolbars, and customize the layout of the toolbars.
To configure the toolbars, open the Configure Toolbars dialog box by doing one of the following:
Scenarios Management
You can export global transformation and validation scenarios into specialized scenarios files. You can import
transformation and validation scenarios from various sources (such as project files, framework option files, or exported
Editor Variables
An editor variable is a shorthand notation for context-dependent information, such as a file or folder path, a time-stamp,
or a date. It is used in the definition of a command (for example, the input URL of a transformation, the output file path
of a transformation, or the command line of an external tool) to make a command or a parameter generic and re-usable
with other input files. When the same command is applied to different files, the notation is expanded at the execution
of the command so that the same command has different effects depending on the actual file.
You can use the following editor variables in Oxygen XML Editor commands of external engines or other external tools,
in transformation scenarios, Author mode operations, and in validation scenarios:
All frameworks are sorted, from high to low, according to their Priority setting from the Document Type
configuration dialog box. Only frameworks that have the Enabled checkbox set are taken into account.
Next, if the two or more frameworks have the same name and priority, a further sorting based on the
Storage setting is made, in the exact following order:
'message' - The displayed message. Note the quotes that enclose the message.
type - Optional parameter, with one of the following values:
Parameter
url
password
${ask('Input URL', url)} - The displayed dialog box has the name Input
URL. The expected input type is URL.
${ask('Input URL', url, 'http://www.example.com')} - The
displayed dialog box has the name Input URL. The expected input type is URL.
The input field displays the default value http://www.example.com.
generic
relative_url
combobox
${ask('File location', relative_url, 'C:/example.txt')} - The dialog box has the name
'File location'. The URL inserted in the input box is made relative to the
current edited document location.
radio
${date(pattern)} - Current date. The allowed patterns are equivalent to the ones in the Java SimpleDateFormat class.
Example: yyyy-MM-dd;
Note: This editor variable supports both the xs:date and xs:datetime parameters. For details about xs:date,
go to http://www.w3.org/TR/xmlschema-2/#date. For details about xs:datetime, go to
http://www.w3.org/TR/xmlschema-2/#dateTime.
${dbgXML} - The local file path to the XML document which is current selected in the Debugger source combo box
(for tools started from the XSLT/XQuery Debugger).
${dbgXSL} - The local file path to the XSL/XQuery document which is current selected in the Debugger stylesheet
combo box (for tools started from the XSLT/XQuery Debugger).
${tsf} - The transformation result file path. If the current opened file has an associated scenario which specifies a
transformation output file, this variable expands to it.
${dsu} - The path of the detected schema as an URL for the current validated XML document.
${ds} - The path of the detected schema as a local file path for the current validated XML document.
${cp} - Current page number. Used to display the current page number on each printed page in the Editor / Print
Preferences page.
${tp} - Total number of pages in the document. Used to display the total number of pages on each printed page in
the Editor / Print Preferences page.
${xpath_eval(expression)} - Evaluates an XPath 3.0 expression. Depending on the context, the expression can be:
static - When executed in a non-XML context. For example, you can use such static expressions to perform string
operations on other editor variables for composing the name of the output file in a transformation scenario's
Output tab.
Example:
${xpath_eval(upper-case(substring('${cfn}', 1, 4)))}
dynamic - When executed in an XML context. For example, you can use such dynamic expression in a code
template or as a value of a parameter of an Author mode operation.
Example:
${ask('Set new ID attribute', generic, '${xpath_eval(@id)}')}
${i18n(key)} - Editor variable used only at framework level to allow translating names and descriptions of Author
mode actions in multiple actions. For more details see the Localizing Frameworks on page 654 section.
Allowed values
com.oxygenxml.disable.http.protocol.handlers true or
false
Default
value
Purpose
false
com.oxygenxml.default.options
A URL-type
relative or
absolute path.
N/A
com.oxygenxml.customOptionsDir
A file system
absolute path
pointing to a
folder.
N/A
com.oxygenxml.ApplicationDataFolder
(Windows only)
A file system
absolute path
pointing to a
folder.
com.oxygenxml.editor.frameworks.url
An URL-type
absolute path.
com.oxygenxml.MultipleInstances
true or
false
com.oxygenxml.xep.location
false
A file system
absolute path
pointing to a
folder.
N/A
com.oxygenxml.additional.classpath
A list of
JAR-type
resources
separated by a
classpath
separator.
N/A
A file system
absolute path
pointing to a
folder.
Allowed values
com.oxygenxml.use.late.delegation.for.author.extensions true or
false
com.oxygenxml.stack.size.validation.threads
The number of
bytes used for
validation
threads.
com.oxygenxml.jing.skip.validation.xhtml.data.attrs true or
false
com.oxygenxml.report.problems.url
User defined
URL
Default
value
true
Purpose
All Java extensions in a document
type configuration are instantiated in
a separate class loader. When true,
the JAR libraries used in a certain
document type configuration will have
priority to resolve classes before
delegating to the parent class loader.
When false, the parent class loader
will take precedence.
N/A
4. Update the language element to reflect the new language. Set the description attribute to Spanish and the
lang attribute to es_ES.
5. For each key element translate the comment (optional) and val elements. Set the lang attribute to es_ES.
Note: After you are finished, the file should look like:
<translation>
<languageList>
<language description="Espaol" lang="es_ES"/>
</languageList>
<key value="New">
<comment>El Archivo / Nueva accin. Crea un nuevo documento.</comment>
<val lang="es_ES">Nuevo</val>
</key>
<key value="New_folder">
<comment>Crea una carpeta en la vista del proyecto.</comment>
<val lang="es_ES">Nueva carpeta</val>
</key>
.....
</translation>
6. Open the Preferences dialog box and go to Global and enable the Other language option. Browse for the
translation.xml file.
7. Restart the application.
Restart Oxygen XML Editor. Go to Help > About and verify the amount of memory that is actually available (see the
last row in the About dialog box). If Oxygen XML Editor does not start and you receive and error message saying that
it could not start the JVM, decrease the -Xmx parameter and try again.
For Windows Vista/7/8/10, copy the oxygen17.1.vmoptions to your desktop (or to any other folder with write
access), modify it there, then copy it back to the Oxygen XML Editor installation folder.
Ctrl Single-Click (Command Single-Click on OS X) (or right-click) the Oxygen XML Editor icon in Finder.
From the contextual menu, select Show Package Contents.
Go to the contents directory and edit the Info.plist file.
Note: You can open this file either with the Property List Editor, or the TextEdit.
Look for the VMOptions key and adjust the -Xmx parameter to a larger value (for example -Xmx1500m)
Note: For a Mac kit bundled with Java 7, look for the VMOptionArray key and add the -Xmx parameter
in a new string element from the array element. For example, for 1500 MB use the following:
<string>-Xmx1500m</string>
Tip: Try not to use more than half of your existing physical RAM if possible.
You can also set a system property through a parameter prefixed with -Doxy in the command line used to start the
application:
oxygen17.1.exe "-Doxyproperty.name=value"
All system properties are displayed in the System properties tab of the About dialog box.
To view the list of Oxygen XML Editor system properties, go to Custom System Properties on page 1246.
Disabling DPI Scaling
Some users may prefer the look of smaller icons in a HiDPI display. To achieve this, display scaling needs to be disabled
for high DPI settings. To disable the DPI scaling, set the following property in .vmoptions (or in the .bat script):
sun.java2d.dpiaware=false
custom_commons.vmoptions - The parameters and their values of this file will be included in all the startup
launchers.
custom_<app name>.vmoptions - The <app name> is the name of the executable application or tool (for
example, custom_diffFiles.vmoptions for the Compare Files tool). The parameters and their values of
this file will be included in the startup launcher for this particular executable.
To be recognized and included, these custom startup parameter files must be saved in the installation directory of Oxygen
XML Editor.
Chapter
21
Common Problems
Topics:
Performance Problems
Common Problems and Solutions
Performance Problems
This section contains solutions for some common performance problems that may appear when running Oxygen XML
Editor.
External Processes
The Memory available to the built-in FOP option controls the amount of memory allocated to generate PDF output with
the built-in Apache FOP processor. If Oxygen XML Editor throws an Out Of Memory error, open the Preferences dialog
box, go to XML > XSLT-FO-XQuery > FO Processors, and increase the value of the Memory available to the
built-in FOP option.
For external XSL-FO processors, XSLT processors, and external tools, the maximum value of the allocated memory is
set in the command line of the tool using the -Xmx parameter set to the Java virtual machine.
Details to Submit in a Request for Technical Support Using the Online Form
What details should I add to my request for technical support on the online form in the product website?
When completing a request for Technical Support using the online form, include as many details as possible about your
problem. For problems where a simple explanation may not be enough for the Technical Support team to reproduce or
address the issue (such as server connection errors, unexpected delays while editing a document, an application crash,
etc.), you should generate a log file and attach it to the problem report. In the case of a crash, you should also attach the
crash report file generated by your operating system.
To generate an Oxygen XML Editor log file, follow these steps:
2.
3.
4.
5.
The resulting log file is named oxygen#.log (for example, oxygen.log, oxygen.log.1, oxygen.log.2,
etc.) and is located in the Desktop\oxygenLog folder.
Make sure that you close other files before opening the large file.
You can set the default editing mode in the Preferences dialog box. The Text editing mode uses less memory than
other editing modes.
Run the transformation in the Editor perspective and make sure the Open in Browser/System Application option is
enabled.
Run the transformation in the XSLT Debugger perspective, save the text output area to a file, and use a browser
application for viewing it (for example Firefox or Internet Explorer).
After Installing Oxygen XML Editor I Cannot Open XML Files in Internet Explorer Anymore
Before installing Oxygen XML Editor I had no problems opening XML files in Internet Explorer. Now when I try to
open an XML file in Internet Explorer it opens the file in Oxygen XML Editor. How can I load XML files in Internet
Explorer again?
XML files are opened in Oxygen XML Editor because Internet Explorer uses the Windows system file associations for
opening files and you associated XML files with Oxygen XML Editor in the installer panel called File Associations
therefore Internet Explorer opens XML files with the associated Windows application.
By default the association with XML files is disabled in the Oxygen XML Editor installer panel called File Associations.
When you enabled it the installer displayed a warning message about the effect that you experience right now.
For opening XML files in Internet Explorer again you have to set Internet Explorer as the default system application
for XML files, for example by right-clicking an XML file in Windows Explorer, selecting Open With > Choose
Program, selecting IE in the list of applications and selecting the checkbox Always use the selected program. Also
you have to run the following command from a command line:
wscript revert.vbs
where revert.vbs is a text file with the following content:
function revert()
Set objShell = CreateObject("WScript.Shell")
objShell.RegWrite "HKCR\.xml\", "xmlfile", "REG_SZ"
objShell.RegWrite "HKCR\.xml\Content Type", "text/xml", "REG_SZ"
end function
revert()
I Cannot Associate Oxygen XML Editor With a File Type on My Windows Computer
I cannot associate the Oxygen XML Editor application with a file type on my Windows computer by right clicking a
file in Windows Explorer, selecting Open With > Choose Program and browsing to the file oxygen17.1.exe. When I
select the file oxygen17.1.exe in the Windows file browser dialog box, the Oxygen XML Editor application is not added
to the list of applications in the Open With dialog box. What can I do?
Find all the Oxygen XML Editor installations on your hard drive.
Delete them by dragging them to the Trash.
Clear the Trash.
Unpack the Oxygen XML Editor installation kit on your desktop.
Copy the contents of the archive into the folder / Applications / Oxygen.
Restart the application, reproduce the error, close the application and send the file logging.log generated in the
install directory to [email protected].
Having images without any resolution information saved in them allows you to control the image resolution from the
configuration file for all referenced images.
The processed file does not exist. Fix the file reference before executing the transformation scenario again.
The processed file has a name that contains space characters. To solve the issue, remove any spacing from the
file name and run the transformation scenario again.
The PDF Processing Fails to Use the DITA OT and Apache FOP
There are cases when publishing DITA content fails when creating a PDF file. This topic lists some common problems
and solutions.
The FO processor cannot save the PDF at the specified target. The console output contains messages like:
[fop] [ERROR] Anttask - Error rendering fo file: C:\samples\dita\temp\pdf\oxygen_dita_temp\topic.fo <Failed
to open C:\samples\dita\out\pdf\test.pdf>
Failed to open samples\dita\out\pdf\test.pdf
.............
[fop] Caused by: java.io.FileNotFoundException: C:\Users\radu_coravu\Desktop\bev\out\pdf\test.pdf
(The process cannot access the file because it is being used by another process)
Such an error message usually means that the PDF file is already opened in a PDF reader application. The solution
is to close the open PDF before running the transformation.
One of the DITA tables contains more cells in a table row than the defined number of colspec elements. The console
output contains messages like:
[fop] [ERROR] Anttask - Error rendering fo file:
D:\projects\eXml\samples\dita\flowers\temp\pdf\oxygen_dita_temp\topic.fo
<net.sf.saxon.trans.XPathException: org.apache.fop.fo.ValidationException:
The column-number or number of cells in the row overflows the number of fo:table-columns specified for the
table. (See position 179:-1)>net.sf.saxon.trans.XPathException: org.apache.fop.fo.ValidationException: The
column-number or number of cells in the row overflows the number of fo:table-columns specified for the table.
(See position 179:-1)
[fop] at org.apache.fop.tools.anttasks.FOPTaskStarter.renderInputHandler(Fop.java:657)
[fop] at net.sf.saxon.event.ContentHandlerProxy.startContent(ContentHandlerProxy.java:375)
............
[fop] D:\projects\samples\dita\flowers\temp\pdf\oxygen_dita_temp\topic.fo ->
D:\projects\samples\dita\flowers\out\pdf\flowers.pdf
There is a broken link in the generated XSL-FO file. The PDF is generated but contains a link that is not working.
The console output contains messages like:
[fop] 1248 WARN [ main ] org.apache.fop.apps.FOUserAgent - Page 6: Unresolved ID reference
"unique_4_Connect_42_wrongID" found.
The TocJS Transformation Does not Generate All Files for a Tree-Like TOC
The TocJS transformation of a DITA map does not generate all the files needed to display the tree-like table of contents.
To get a complete working set of output files you should follow these steps:
1. Run the XHTML transformation on the same DITA map. Make sure the output gets generated in the same output
folder as for the TocJS transformation.
2. Copy the content of DITA_OT_DIR/plugins/com.sophos.tocjs/basefiles folder in the transformation's
output folder.
3. Copy the DITA_OT_DIR/plugins/com.sophos.tocjs/sample/basefiles/frameset.html file
in the transformation's output folder.
4. Edit frameset.html file.
5. Locate element <frame name="contentwin" src="concepts/about.html">.
6. Replace "concepts/about.html" with "index.html".
Navigation to the web page was canceled when viewing CHM on a Network Drive
When viewing a CHM on a network drive, if you only see the TOC and an empty page displaying Navigation to the
web page was canceled note that this is normal behavior. The Microsoft viewer for CHM does not display the topics
for a CHM opened on a network drive.
As a workaround, copy the CHM file on your local system and view it there.
Alignment Issues of the Main Menu on Linux Systems Based on Gnome 3.x
On some Linux systems based on Gnome 3.x (Ubuntu 11.x, 12.x), the main menu of Oxygen XML Editor has alignment
issues when you navigate it using your mouse.
To fix this issue, go to the Microsoft website and get the latest MSXML 4.0 service pack.
Chapter
22
Glossary
Topics:
Active cell
Apache Ant
Block element
Bookmap
DITA Map
DITA_OT_DIR
Inline element
Java Archive
Named User
Active cell
The selected cell in which data is entered when you begin typing. Only one cell is active at a time. The active cell is
bounded by a heavy border.
Apache Ant
Apache Ant (Another Neat Tool) is a software tool for automating software build processes.
Ant
Block element
A block element is an one that is intended to be visually separated from its siblings, usually vertically. For instance, a
paragraph or a list item are block elements. It is distinct from a inline element which has no such separation.
Bookmap
A bookmap is a specialized DITA map used for creating books. A bookmap supports book divisions such as chapters
and book lists such as indexes.
DITA Map
A DITA map is a hierarchical collection of DITA topics that can be processed to form an output. Maps do not contain
the content of topics, but only references to them. These are known as topic references. Usually the maps are saved on
disk or in a CMS with the extension .ditamap.
Maps can also contain relationship tables that establish relationships between the topics contained within the map.
Relationship tables are also used to generate links in your published document.
You can use your map or bookmap to generate a deliverable using an output type such as XHTML, PDF, HTML Help
or Eclipse Help.
DITA_OT_DIR
DITA_OT_DIR is the default directory that is specified for your DITA Open Toolkit distribution in the Options >
Preferences > DITA preferences page.
For example, if you are using DITA 1.8, the default DITA OT directory is:
[OXYGEN_DIR]/frameworks/dita/DITA-OT.
Inline element
An inline element is one that is intended to be displayed in the same line of text as its siblings or the surrounding text.
For instance, strong and emphasis in HTML are inline elements. It is distinct from a block element, which is visually
separated from its siblings.
Java Archive
JAR (Java ARchive) is an archive file format. JAR files are built on the ZIP file format and have the .jar file extension.
Computer users can create or extract JAR files using the jar command that comes with a JDK.
Java Archive (JAR)
JAR
Named User
Named User is defined as an individual full or part-time employee who is authorized by You (the individual or entity
who owns the rights to Oxygen XML Editor) to use the software regardless of whether the individual is actively using
the software at any given time. To avoid any doubt, Named User licenses cannot be shared amongst multiple individuals
and separate Named User licenses must be purchased for each individual user.
A Named User license may not be reassigned to another employee except in the following circumstances:
(a) Upon termination of the Named Users employment with your company.
(b) Permanent reassignment of a Named User to a position that does not involve the use of the Software.
For example, suppose Jane has been assigned an Oxygen XML license and she leaves your company. When she leaves,
you can simply reassign her license to John, her replacement. In the event that you do reassign the Named User license
in accordance with the restrictions above, you do not need to notify Syncro of such a reassignment.
Note: This definition is taken from the Oxygen XML Editor End User License Agreement.
Index
:has pseudo-class 715
A
Add button 857
Add favicon to WebHelp 855
Add Form Controls 781
StylesFilter API for adding form controls 781
Add items to a project 33, 156
Archives 899, 900, 903
browse 900
edit 903
file browser 900
modify 900
Author Editing Mode 186
roles: content author, framework developer 186
Author Editor 93, 94, 96, 97, 98, 99, 101, 109, 112, 116, 166, 186,
189, 195, 197, 199, 200, 202, 203, 204, 205, 207, 227,
246
Accessibility 94, 195
attributes view 112
Author mode contextual menu 189
breadcrumb 94
change tracking 197, 199, 200, 202, 203, 204, 205, 207
callouts 205
manage changes 199
managing comments 203, 204
the Review view 207
track changes behavior 200
track changes limitations 202
edit content 195
editing XML 186
edit markup 195
elements view 116
external references 98
find/replace 197
navigation 94, 96, 97
bookmarks 97
display the markup 96
outline view 109
position information tooltip 97
reload content 227
validation 99, 246
whitespace handling 101, 166
versions differences 166
WYSIWYG editing 186
Author Mode Settings 630
menus 630
main menu 630
Author Settings 627, 628, 629, 631, 632, 633, 634, 647, 648, 650,
672, 676, 677, 683, 686, 687, 690, 692, 694
actions 627, 628, 629
insert section 628
insert table 629
Author default operations 634
content 633
configuring the content completion 633
content completion customization wizard 633
B
Bidirectional text 90, 92, 122
Author Mode 122
Grid Mode 92
Text Mode 90
bookmap 478
creating a bookmap 478
Built-in Form Controls 737, 738, 740, 741, 743, 744, 745, 748, 749,
750
built-in form controls 737
button form control 743
button group form control 744
checkbox form control 740
check box form control 740
combobox form control 738
combo box form control 738
date picker form control 749
HTML content form control 750
popup form control 741
pop-up form control 741
text area form control 745
Text field form control 737
URL chooser form control 748
C
Common Problems 1254
Comparing and Merging Documents 1124, 1125, 1126, 1127, 1128,
1130, 1131, 1132, 1134, 1135
Compare Directories tool 1125, 1126, 1127, 1128
compare images view 1128
D
Databases 869, 905, 906, 925, 926, 944, 945, 946, 947, 948, 969
debugging with MarkLogic 947
limitations of the MarkLogic debugger 947
native XML databases (NXD) 925
Native XML databases (NXD) 926
Relational databases 906
SharePoint connection 969
WebDAV connection 948
XQuery 869, 944, 945, 946
debugging 946
drag and drop from the Data Source Explorer 944
transformation 945
validation 869
Debugging XSLT/XQuery Documents 876, 880, 889, 892
Java extensions 892
layout 876, 880, 889
information views 880
multiple output documents in XSLT 2.0 889
XSLT/XQuery debugger 889
Debugging XSLT / XQuery Documents 877
layout 877
Control toolbar 877
Define keys in DITA maps 488
deploying WebHelp with Feedback 834
Develop an oXygen Plugin 976, 990
example - UppercasePlugin 990
introduction 976
E
Edit 133, 134, 135, 137, 140, 141, 142, 143, 150, 155, 209, 259,
261, 263, 264, 461, 463, 467, 468, 903, 1144, 1248
archives 903
associating a file extension 468
change the user interface language 1248
change user interface language 1248
Character map 135
check spelling 461
check spelling in files 463
close documents 155
conditional text 209
copy/paste 259
F
Facebook widget 841
File Menu 137, 140, 141, 142, 155, 227, 259, 954, 955, 957, 960
Close 155
Close All 155
Close Other Files 155
Import Database Data 957
Import HTML File 960
Import MS Excel File 955
Import Text File 954
New 137
Open 140
Open URL 140
Print 259
Print Preview 259
Reload 227
Reopen 140
Save 142
Save All 142
Save as 142
Save to URL 142
View in Browser System Application 141
Find/Replace 197, 261, 262, 263, 264
Author editor 197
Find All Elements/Attributes dialog box 262
Find/Replace (continued)
keyboard shortcuts 264
Quick Find toolbar 263
Find Menu 150, 175, 258, 261, 262, 263, 264
Back 258
Find/Replace 261
Find/Replace in Files 264
Find All Elements 262
Forward 258
Go to 175
Last Modification 258
Open/Find Resource 150
Quick Find 263
Flagging content 857
Floating license key replacement 54, 56
Format and indent 177
Format and Indent 1181
Form Controls 752
edit processing instructions with form controls 752
pi form control 752
G
Generate Documentation for an XML Schema 381
customizing the PDF output 381
Generate IDs 229
DITA 229
DocBook 229
TEI 229
Generating Documentation for WSDL Documents 407
generating WSDL documentation in HTML format 407
Getting Started 24, 63, 64, 65, 66, 67, 1124, 1238
dockable views and editors 1238
perspectives 63, 64, 65, 66, 67, 1124
database 67
editor 64
tree editor 1124
XQuery debugger 66
XSLT debugger 65
Google Analytics integration 844
Google Plus widget 842
Google Search Integration 843
grid editor 92
navigation 92
collapse all 92
collapse children 92
collapse others 92
expand all 92
expand children 92
Grid Editor 90, 91, 92, 183, 184
add nodes 183
clear column content 183
copy/paste 184
drag and drop 184
duplicate nodes 183
inserting table column 183
insert table row 183
layouts (grid and tree) 91
navigation 92
refresh layout 184
sort table column 183
start and stop editing a cell value 184
H
Help menu 34
Accessibility 34
Check for a New Version 34
Check for updates 34
install add-ons 34
online help 34
Register 34
Report problem 34
Support center 34
Tip of the day 34
Highlight Component Occurrences 449
HTTP Authentication Schemes 148
NTLM 148
I
Import color themes 1150
copy color themes 1150
Import from Excel 957
2007 957
2010 957
2013 957
Importing data 953
Importing Data 954, 957, 960
from a database 957
table content as XML document 957
from HTML files 960
from text files 954
Importing data from Excel 955
Insert DITA content key reference 504
conkeyref 504
Insert DITA Content Reference 503
Insert page break in PDF 537
Insert Reusable Component 513
Insert table in DITA 524
CALS 524
Simple table 524
Installation 39, 40, 41, 42, 43, 44, 45, 46
all platforms version 40, 41, 43, 44, 46
Linux 42, 45
multiple instances (Unix / Linux server) 46
OS X installation 41
unattended (Windows and Linux only) 39, 43
Windows installation 39, 44
Windows terminal server 44
installing WebHelp with Feedback 834
integrate WebHelp plugin with DITA 845
integrate WebHelp plugin with DocBook 849
Integrating Social Media in WebHelp 841
Integrating the Ant tool 1144
Integrating the WebHelp plugin with DITA OT 845
J
JATS NISO Journal Article Tag Suite 614
Author Mode Actions 614
JATS NISO Journal Article Tag Suite Document Type 614
K
Kerberos authentication 148
L
License 48, 49, 50, 51, 52, 55, 57, 58
floating (concurrent) license 50
floating license server 55
floating license servlet 52
license server installed on OS X Linux Unix 57
multiple named-user licenses 51
named-user license 49
register a license key 48
release floating license 51
releasing a license key 58
transferring a license key 58
unregistering a license key 58
localize WebHelp with Feedback system emails 851
Localizing WebHelp Output 844
M
Manage IDs 176, 276
highlight ID occurrences in Text mode 176
search and refactor actions of ID IDREFS 276
Managing Highlights 204
Remove highlights 204
Master Files 166
Model view 84, 115, 238
streamline with content completion 84, 115, 238
the Model panel 84, 115, 238
Moving DITA Resources 481
Moving Renaming Schematron resources 448
N
Native XML Databases 921
resource management 921
Table Explorer view 921
Native XML Databases (NXD) 917, 925, 926, 927, 928, 929, 930
database connections configuration 926, 927, 929
Berkeley DB XML 926
Documentum xDb (X-Hive/DB) 929
eXist 927
data sources configuration 925, 926, 927, 928, 929
Berkeley DB XML 926
Documentum xDb (X-Hive/DB) 929
eXist 927
MarkLogic 928
resource management 917, 930
Data Source Explorer view 917, 930
O
Options Menu 1148, 1228, 1237, 1241
Export Global Options 1237
Export Global Transformation Scenarios 1241
P
Pasting tables in DocBook 217
Performance Problems 1254
external processes 1254
large documents 1254
problems on Linux/Solaris 1254
Predefined XML refactoring operations 285
Preferences 1148
Pretty print 177
Profile DITA step by step 542
conditional text 542
profiling tutorial 542
Profiling 540, 542, 896
conditional text 542
filter content 542
filter content 540
conditional text 540
XSLT stylesheets and XQuery documents 896
Profiling XSLT Stylesheets and XQuery Documents 896, 897
profiling information 896, 897
Hotspots view 897
Invocation tree view 896
XSLT/XQuery profiler 897
Project Menu 77, 107, 163
Change Search and Refactor operations scope 77, 107, 163
Enable Master Files Support 77, 107, 163
Filters 77, 107, 163
Q
Querying Documents 389, 860, 861, 865, 866, 867, 869
running XPath and XQuery expressions 861
XPath/XQuery Builder view 861
running XPath expressions 860
XPath toolbar 860
XQuery 389, 865, 866, 867, 869
Input view 867
Outline view 389, 866
syntax highlight and content completion 865
transforming XML documents; advanced Saxon B/SA options
869
validation 869
Quick Assist Support 176
R
Refactoring 176
Quick Assist 176
Refactoring XML Documents 282
XML Refactoring Tool 282
register license for WebHelp plugin 846
Relational Databases 906, 907, 908, 909, 910, 911, 912, 913, 914,
915, 916, 917, 921, 923, 925, 930
connections configuration 906, 907, 909, 911, 912, 914, 916
generic JDBC 911
IBM DB2 connection 907
JDBC-ODBC connection 916
Microsoft SQL Server 909
MySQL 912
Oracle 11g 914
PostgreSQL 8.3 916
data sources configuration 906, 908, 910, 911, 913, 915
generic JDBC data source 910
IBM DB2 906
Microsoft SQL Server 908
MySQL 911
Oracle 11g 913
PostgreSQL 8.3 915
resource management 917, 921, 930
Data Source Explorer view 917, 930
Table Explorer view 921
SQL execution support 923, 925
drag and drop from the Data Source Explorer 923
executing SQL statements 925
SQL validation 925
Relax NG Schema Editor 416
contextual editing 416
Renaming DITA Resources 481
render PDF images 224
Resolve schema through xml catalog mappings 271
Retina HiDPI images 646
Accessibility 646
S
Schematron Quick Fixes 282
SharePoint Browser 970
SharePoint Connection 969, 972, 973
actions at connection level 972
actions at file level 973
actions at folder level 972
configuration 969
Sharing extended document type 697
framework 697
Sharing frameworks 696
Sharing preferences 1236
global options 1236
project options 1236
Sharing Preferences 164
project options file 164
Sharing Transformation Scenarios 164
Sharing Validation Scenarios 164
Social media 841
Social Media 841, 842, 844
Social plugin 841
Sort entire table 219
Sorting content in list items 219
Sorting content in tables 219
Sort list items 222
Sort selected rows 220
Sort table with merged cells 222
Spell Checking 463
automatic spell check 463
SQF 282
Startup parameter 1249, 1250
application launchers parameters 1249
command line scripts parameters 1250
Startup parameters 1249
Storing preferences 1236
global options 1236
project options 1236
Subject scheme 478
creating a Subject scheme 478
Supported document types 554
frameworks 554
SVN Branches/Tags 1062, 1064, 1066, 1067, 1068, 1070, 1074,
1075
create a branch/tag 1062
merging 1064, 1066, 1067, 1068, 1070
merge changes 1066
merge two different trees 1070
reintegrate a branch 1068
reverse merge 1066
synchronize branch 1067
relocate a working copy 1075
switch the repository location 1074
SVN Client 1028, 1036, 1037, 1038, 1040, 1041, 1044, 1045, 1050,
1060, 1061, 1062, 1076, 1087, 1088, 1089, 1090, 1091,
1100, 1105, 1106, 1107, 1108, 1110, 1113, 1114, 1115,
1116, 1117, 1120
Annotations view 1110
T
TEI ODD document type 601
association rules 601
Author extensions 601
catalogs 601
schema 601
TEI ODD Document Type 601, 605
Author extensions 601, 605
templates 605
transformation scenarios 605
TEI P4 document type 605
association rules 605
Author extensions 605
catalogs 605
schema 605
TEI P4 Document Type 605, 609
Author extensions 605, 609
templates 609
transformation scenarios 609
TEI P5 document type 609, 610
association rules 609
Author extensions 610
catalogs 610
schema 609
TEI P5 Document Type 609, 610, 613
Author extensions 610, 613
templates 613
transformation scenarios 613
Text Editing Mode 70, 148, 177, 182, 259
compare file 177
insert file at cursor position 177
Manage highlighted content 182
open file at cursor position 177
print a file 259
shortcut actions 177
switch between opened tabs 148
Text mode editor 70
Text Mode Editor 70
Accessibility 70
breadcrumb 70
navigation 70
Tools 1027
Tools Menu 274, 282, 371, 375, 383, 384, 386, 409, 435, 459, 1028,
1124, 1125, 1128, 1137, 1138, 1140, 1141, 1142, 1143,
1144
Canonicalize 1137
Compare Directories 1125
Compare Files 1128
Convert DB Structure to XML Schema 383
External Tools 1144
Flatten Schema 384
Generate/Convert Schema 274
Generate Documentation 375
XML Schema Documentation 375
Generate Sample XML Files 371
Hex Viewer 1142
Large File Viewer 1141
Sign 1138
SVG Viewer 459, 1143
SVN Client 1028
Tree Editor 1124
Verify Signature 1140
WSDL SOAP Analyzer 409
XML Refactoring 282
XML Schema Regular Expression Builder 386
XML to JSON 435
Transformation Scenario 788, 789, 790, 791, 792, 794, 817, 818
built-in transformation scenarios 818
new transformation scenario 788, 789, 790, 791, 792, 794, 817
additional XSLT stylesheets 792
configure transformation scenario 788
create a transformation scenario 817
XML transformation with XSLT 789
XQuery parameters 790
XSLT/XQuery extensions 791, 794
XSLT parameters 790
sharing transformation scenarios 818
Transforming Documents 787, 788, 819, 821, 823, 824, 828
custom XSLT processors 823
output formats 828
supported XSLT processors 821
transformation scenario 788
Transformation Scenarios view 819
XSL-FO processors 824
XSLT processors extensions paths 823
Tweet Button 842
Twitter Widget 842
U
Unicode 1181
Uninstalling the application 60
Upgrade 58
check for new version 58
upgrade WebHelp plugin for DITA 846
upgrading WebHelp plugin for DocBook 850
V
Validate and Check for Completeness 497
Validating DITA Map 497
Validating Schematron Files 443
Validating XML Documents 244
W
WebApp 1018, 1019, 1024
Deploying the WebApp 1019
integrate GitHub 1024
OAuth authentication method 1024
Open files as read-only 1018
WebApp server requirements 1019
WebApp software requirements 1019
WebApp Component 1010
WebApp CSS limitations 1013
WebApp Customizing Frameworks 1012
WebApp Customizing Options 1011
WebApp Customizing Plugins 1014
WebDAV Connection 948, 949
actions at connection level 948
actions at file level 949
actions at folder level 949
configuration 948
WebHelp 845
command line 845
external process 845
outside oxygen 845
WebHelp Administrative page 836
Admin Panel 836
WebHelp GET parameters 856
WebHelp Internationalization 844, 845
DITA WebHelp localization 844
WebHelp i18n 844
DocBook WebHelp localization 845
WebHelp i18n 845
WebHelp Output 839
WebHelp Skin Builder 839
WebHelp plugin to run external DITA transformations 846
WebHelp System 828
WebHelp with Feedback 836
comment management 836
manage comments 836
WebHelp with Feedback System 831
whitespace 1181
Whitespace handling 177
Window Menu 63, 88, 120, 1238
Export Layout 1238
Hide current view 1238
Load Layout 1238
Maximize/Restore Editor Area 1238
Next editor 1238
Open Perspective 63
Previous editor 1238
Reset Layout 1238
Results 88, 120
Close 88, 120
Close All Tabs 88, 120
Close Other Tabs 88, 120
Print Results 88, 120
Save Results 88, 120
Show View 1238
Split Editor Horizontally 1238
Split Editor Vertically 1238
X
XHTML document type 597
association rules 597
Author extensions 597
catalogs 597
CSS 597
schema 597
XHTML Document Type 597, 598, 601
Author extensions 598, 601
templates 601
transformation scenarios 601
XML Outline View 79, 80, 81, 82, 110, 111, 112, 257, 258
Author 111
outline filters 111
contextual menu 111
document structure change 80, 81, 110, 257
contextual menu 81
document tag selection 82, 112, 258
drag and drop actions 80, 110, 257
modification follow-up 80, 110, 257
outline filters 81
XML document overview 80, 110, 257
XML Quick Fixes 280
Accessibility 280
XML Schema 126, 364
Outline view 126, 364
XML Schema Diagram Editor 124, 125, 128, 130, 131, 336, 343,
346, 347, 348, 349, 351, 352, 353, 354, 355, 356, 357,
358, 359, 360, 361
Attributes view 128
editing actions 336
edit schema namespaces 361
Facets view 130
group schema components 359, 360
attributes 359
constraints 359
substitutions 360
navigation 125
schema components 343, 346, 347, 348, 349, 351, 352, 353,
354, 355, 356, 357, 358
xs:alternative 351
xs:any 354
xs:anyAttribute 355
xs:assert 358
xs:attribute 346
xs:attributeGroup 347
xs:complexType 348
xs:element 343
xs:field 357
xs:group 352
xs:import 352
xs:include 352