<oXygen/> XML Editor User Guide

Opening and closing documents

As with most editing applications, <oXygen/> lets you open existing documents, save your changes and close them as required.

Creating new documents

The New dialog

<oXygen/> supports a large number of document types. Use the following procedure to create documents.

Procedure 4.1. Creating new documents

  1. Select File-> New (Ctrl+N) or press the New toolbar button. The New dialog is displayed which contains the supported Document Types: XML, XSL, XML Schema, Document Type Definition, Relax NG Schema, XQuery, Web Services Definition Language, Schematron Schema, CSS File , Text File, Java File, JavaScript File, C File, C++ File, Batch File, Shell File, Properties File, SQL File, PHP File and PERL File.

    Figure 4.2. The New dialog

    The New dialog
  2. Select a document type, then click OK. If XML was selected the "Create an XML Document" dialog is displayed otherwise a new document is opened in the Editor Panel.

  3. The Create an XML Document dialog enables definition of a XML Document Prolog using the system identifier of a XML Schema, DTD, Relax NG (full or compact syntax) schema or NRL (Namespace Routing Language) schema. As not all XML documents are required to have a Prolog, you may choose to skip this step by clicking OK. If the prolog is required complete the fields as the following.

    Figure 4.3. The Create an XML Document Dialog - XML Schema Tab

    The Create an XML Document Dialog - XML Schema Tab

    Complete the dialog as follows:

    Use a DTD, XML Schema, Relax NG or NRL schema

    When checked enables selection between DTD, XML Schema, Relax NG schema or NRL schema.

    URL

    Specifies the location of an XML Schema Document (XSD).

    Namespace

    Specifies the document namespace.

    Document Root

    Populated from the elements defined in the specified XSD, enables selection of the element to be used as document root.

    Description

    Shows a small definition for the currently selected element.

    Figure 4.4. The Create an XML Document Dialog - DTD Tab

    The Create an XML Document Dialog - DTD Tab

    Complete the dialog as follows:

    Use a DTD, XML Schema, Relax NG or NRL schema

    When checked enables selection between DTD, XML Schema, Relax NG schema or NRL schema.

    System ID

    Specifies the location of a Document Type Definition (DTD).

    Public ID

    Specifies the PUBLIC identifier declared in the Prolog.

    Document Root

    Populated from the elements defined in the specified DTD, enables selection of the element to be used as document root.

    Description

    Shows a small definition for the currently selected element.

    Figure 4.5. The Create an XML Document Dialog - Relax NG Tab

    The Create an XML Document Dialog - Relax NG Tab

    Complete the dialog as follows:

    Use a DTD, XML Schema, Relax NG or NRL schema

    When checked enables selection between DTD, XML Schema, Relax NG schema or NRL schema.

    URL

    Specifies the location of a Relax NG schema in XML or compact syntax (RNG/RNC).

    XML syntax

    When checked the specified URL refers to a Relax NG schema in XML syntax. It will be checked automatically if the user selects a document with the .rng extension.

    Compact syntax

    When checked the specified URL refers to a Relax NG schema in compact syntax. It will be checked automatically if the user selects a document with the .rnc extension.

    Namespace

    Specifies the root element namespace.

    Document Root

    Populated from the elements defined in the specified RNG or RNC document, enables selection of the element to be used as document root.

    Figure 4.6. The Create an XML Document Dialog - NRL Tab

    The Create an XML Document Dialog - NRL Tab

    Complete the dialog as follows:

    Use a DTD, XML Schema, Relax NG or NRL schema

    When checked enables selection between DTD, XML Schema, Relax NG schema or NRL schema.

    URL

    Specifies the location of a NRL schema (NRL).

Creating Documents based on Templates

Templates are documents containing a predefined structure. They provide starting points on which one can rapidly build new documents that repeat the same basic characteristics. <oXygen/> installs a rich set of templates for a number of XML applications. You may also create your own templates and share them with other users.

The Templates dialog enables you to select predefined templates or templates that have already been created in previous sessions or by other users. Open a template using the following options:

Figure 4.7. The Templates dialog

The Templates dialog

Open a template using the following options:

Standard

Populates the Templates list to show templates supplied with the <oXygen/> installation package.

User defined

Populates the Templates list to show previous saved personal templates.

From URL

Enables definition of a URL location containing Templates.

Templates List

Displays the available templates for Standard, From File and From URL options.

Procedure 4.2. Creating Documents based on Standard Templates

  1. Select File-> New from Templates or press the New from templates toolbar button. The Templates dialog is displayed and is used to discover, select and open a new document based on an existing template document. Template documents act as starting points that have predefined properties such as file type, prolog, root element, containers and even existing content.

    Figure 4.8. The Templates dialog

    The Templates dialog
  2. Select the Standard option from the Load Templates Group. The Templates list displays standard <oXygen/> templates.

  3. Scroll the Templates list and select the required Template Type.

  4. Click OK. A new document is opened that already contains structure and content provided in the template starting point.

Procedure 4.3. Creating Documents based on Personal Template Files

  1. Select File-> New from Templates or press the New from templates toolbar button. The Templates dialog is displayed.

    Figure 4.9. The Templates dialog

    The Templates dialog
  2. Select the User defined option from the Load Templates Group. The Templates list displays person templates.

  3. Scroll the Templates list and select the required Template Type.

  4. Click OK. A new document is opened that already contains structure and content provided in the template starting point.

Procedure 4.4. Creating Documents based on URL Template Files

  1. Select File-> New from Templates or press the New from templates toolbar button. The Templates dialog is displayed.

    Figure 4.10. The Templates dialog

    The Templates dialog
  2. Select the From URL option from the Load Templates Group. The From URL field is enabled.

  3. Enter the URL location of the templates, then click Load. The list of templates is retrieved from the URL and displayed in the Templates list.

  4. Scroll the Templates list and select the required Template Type.

  5. Click OK. A new document is opened that already contains structure and content provided in the template starting point.

Saving documents

The edited document can be saved with one of the actions:

  • File-> Save (Ctrl+S) or press the Save toolbar button to save the current document. If the document does not have a file, displays the Save As dialog.

  • File->Save As: Displays the Save As dialog, used to name and save an open document to a file; or save an existing file with a new name.

  • File->Save To URL or press the Save To URL ... toolbar button to display the Save to URL dialog, used to name and save an open document to a file; or saves an existing file with a new name, using FTP/WebDAV.

  • File->Save All: Saves all open documents. If any document does not have a file, displays the Save As dialog.

Opening existing documents

Documents can be opened using one of the actions:

  • File-> Open (Ctrl+O) or press the Open toolbar button to display the Open dialog used to discover, select and open one or more files.

  • File->Open URL ... or press the Open URL ... toolbar button to display the Open URL dialog, used to open a document using FTP/WebDAV.

  • File->Revert: Loads the last saved file content. All unsaved modifications are lost.

  • File->Reopen: Displays a list of recently opened document files. Select a file to open.

  • Project panel contextual menu->Open : Opens the selected file from the Project panel.

In addition <oXygen/> supports direct opening of files from the command prompt. Use the following command syntax:

  • On Windows:

    oxygen.bat FileToOpen.xml

  • On Unix/Linux:

    sh ./oxygen.sh FileToOpen.xml

  • On Mac OS X:

    sh ./oxygenMac.sh FileToOpen.xml

Also when the Tree Editor perspective is activated the current document in the Editor perspective will be opened and displayed as a tree of XML elements.

Opening and Saving Remote Documents via FTP/WebDAV

<oXygen/> supports editing remote files, using the FTP and WebDAV protocols. The remote opened files can be edited exactly as the local ones. They can be added to the project, and can be subject to XSL and FO transformations.

Figure 4.11. Open URL dialog

Open URL dialog
[Note]Note

The WebDAV access is implemented using the Slide package of the Apache Software Foundation. The FTP part is using passive access to the FTP servers. Make sure the server you are trying to connect to is supporting passive connections.

The FTP/WebDAV capabilities have been extensively tested with various servers running on Windows (IIS), Mac OS X and Linux (Apache).

[Note]Note

If you have set a proxy server to be used by <oXygen/>, make sure it supports the WebDAV protocol. If it does not, make sure you uncheck the "Use proxy server" from the Options/Preferences/Proxy Configuration pane, otherwise you will not be able to connect to a WebDAV server.

To open the remote files, choose from the main menu File->Open URL ... The displayed dialog is composed of three parts.

  • The first one is an editable combo box, in which it can be specified directly the URL to be opened or saved.

    [Tip]URLs that can be directly opened

    You can type in here an URL like http://some.site/test.xml, in case the file is accessible through normal HTTP protocol, or ftp://anonymous@some.site/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.

  • The second part is controlling the access credentials. If you want to browse for a file on a server, you have to specify the user and password. This information is bound to the selected URL displayed in the "File URL" combo box, and used further in opening/saving the file. If the check box "Save" is selected, then the user and password are saved between editing sessions. The password is kept encrypted into the options file.

    [Note]Note

    Your password is well protected. In the case the options file is moved to another installation, on other machine, the password will become unreadable, since the encryption is user and machine dependent. This is also true if you add URLs having user and password to your project.

  • The third part contains the server combo and the "Autoconnect" check box. Into the server combo it may be specified the protocol (HTTP, HTTPS or FTP), the name or IP of the server and, in case of WebDAV, the path to the WebDAV directory.

    [Tip]Server URLs

    When accessing a FTP server, you need to specify only the protocol and the host, like: ftp://server.com, ftp://ftp.apache.org, or if using a nonstandard port: ftp://server.com:7800/ etc.

    When accessing a WebDAV server, along with the protocol and the host, it must be specified also the directory of the WebDAV repository.

    [Important]Important

    Make sure that the repository directory ends in a slash "/".

    Ex: https://www.some-webdav-server.com:443/webdav-repository/, http://devel:9090/webdav/

    By pressing the "Browse" button the directory listing will be shown in the component bellow. When "Autoconnect" is selected then at every time the dialog is shown, the browse action will be performed.

  • The last part consists of a tree view of the documents stored on the server. You can browse the directories, and make multiple selections. Additionally, you may use the "Rename", "Delete", and "New Folder" to manage the file repository.

If you want to access a WebDAV repository across an insecure network <oXygen/> allows you to load and save the documents over the HTTPS protocol (if the server understands this protocol) so that any data exchange with the WebDAV server is encrypted.

When a WebDAV repository is first accessed over HTTPS the server hosting the repository will present a security certificate to <oXygen/> as part of the HTTPS protocol, without any user intervention. <oXygen/> will use this certificate to decrypt any data stream received from the server. For the authentication to succeed you should make sure the security certificate of the server hosting the repository can be read by <oXygen/>. This means that <oXygen/> can find the certificate in the key store of the Java Runtime Environment in which it runs. You know the server certificate is not in the JRE's key store if you get the error "No trusted certificate found" when trying to access the WebDAV repository:

Figure 4.12. The server certificate is not available

The server certificate is not available

You can add a certificate to the key store by exporting it to a local file using any HTTPS-capable Web browser (for example Internet Explorer) and then importing this file into the JRE using the keytool executable bundled with the JRE. The steps are the following using Internet Explorer (if you use other browser the procedure is similar):

Procedure 4.5. Import a HTTPS server certificate

  1. Export the certificate into a local file

    1. Point your HTTPS-aware Web browser to the repository URL. If this is your first visit to the repository it will be displayed a security alert stating that the security certificate presented by the server is not trusted.

      Figure 4.13. Security alert - untrusted certificate

      Security alert - untrusted certificate
    2. Press the button "View Certificate".

    3. Select the "Details" tab.

    4. Press the button "Copy to file ...". This will start the Certificate Export Wizard on Windows

    5. Follow the indications of the wizard to save the certificate to a local file, for example server.cer .

  2. Import the local file into the JRE running <oXygen/>

    1. Open a text-mode console.

    2. Go to the lib/security subdirectory of your JRE directory, that is of the directory where it is installed the JRE running <oXygen/>, for example on Windows C:\Program Files\Java\j2re1.4.2\lib\security

    3. Run the following command:..\..\bin\keytool.exe -import -trustcacerts -file local-file.cer -keystore cacerts where local-file.cer is the file containing the server certificate, created during the previous step. Keytool requires a password before adding the certificate to the JRE keystore. The default password is "changeit". If somebody changed the default password then he is the only one who can perform the import. As a workaround you can delete the cacerts file, re-type the command and enter as password any combination of at least 6 characters. This will set the password for future operations with the key store.

  3. Restart <oXygen/>

Closing documents

To close documents use one of the following methods:

  • File-> Close (Ctrl+W) : Closes only the selected tab. All other tab instances remain.

  • File->Close All: Closes all opened documents. If a document is modified or has no file, a prompt to save, not to save, or cancel the save operation is displayed.

  • Close - accessed by right-clicking on an editor tab: Closes the selected editor.

  • Close other files - accessed by right-clicking on an editor tab: Closes the other files except the selected tab.

  • Close all - accessed by right-clicking on an editor tab: Closes all open editors within the panel.

Creating and sharing new document templates

Creating a new document template

<oXygen/> enables user defined templates to be created. Templates are created by adding an existing document to the Template library.

Procedure 4.6. Creating New Templates

  1. Open the document that will be used to create the Template.

  2. Modify the structure and content as required.

  3. File->Add to Templates or press the toolbar button Add to templates to display the Add Templates dialog used to define the name by which the template will be recognized in the New from templates option.

  4. Enter the name by which the template will be known. Click OK the document is added to the list of Personal Templates.

  5. Test the template using the From File option.

Sharing document templates

<oXygen/> stores Personal Templates in an XML file called .com.oxygenxml/templates.xml, located in the Home folder of the <oXygen/> user. By copying this file to a Web Server folder and making it accessible via HTTP, other <oXygen/> users can use the From URL option to access the templates.

Procedure 4.7. Sharing Templates

  1. Create one or more Personal Templates.

  2. Copy [user home dir]\com.oxygenxml\templates.xml into an accesible directory on your web server.

  3. Test the template using the From URL option.

Viewing file properties

You can quickly access informations about the current edited document like the character encoding, full path on the filesystem, schema used for content completion and document validation, associated transformation scenario, if bidirectional text (left to right and right to left) is enabled, indent size by going to File-> Properties