XMLTreeEditHelp

XML Tree Editor

Changing XML document with XML Tree Editor is done by manipulating with tree view representation, there is no plain text view, syntax highlight etc. Most commands can be accessed through main and popup menus or pressing keyboard shortcuts. Note that XML Tree Editor is highly configurable program, so any references to command names and shortcuts are meant to be "default" ones, provided with the original distribution, as they can be changed by users.

• XML Tree Editor
  • Opening XML file
    • Reference Tree
  • Editing XML document
    • Adding Nodes
    • Editing Nodes
    • Other Node Manipulation commands
  • Drag and Drop support
  • Finding nodes
  • Configuration files
    • Global configuration
    • Local (user) configuration
    • Translation file
  • Command-line options

[XMLTreeEditBackup]

Opening XML file

The canonical way: click File -> Open, then navigate and choose the file in the dialogue.

When XML Tree Editor is just started, double click on empty tree area will do the trick. This will bring the same open file dialogue as above.

As convenience feature the open file dialogue automatically navigates to the last open file, so in order to open it one just needs to click Open button.

To select one of the recently opened files click File -> Open Recent

To create a new XML file click File -> New, navigate to the destination folder and enter file name, then click Open. The program will ask about root node name - enter a valid name and click OK. The valid name must start with a letter, is case-sensitive and can contain only letters, numbers and "_", "-" and "." characters; the last two are not advised.

To rename an XML file first open it then click File -> Save As..., navigate to desired folder and enter new name, then click Save.

There is no "Save" command, as all changes in the XML document are saved into the file immediately; the file on disk is always re-written as the whole. This behaviour can be changed with Read-Only switch (see below).

Note: There is a Read-Only switch under the Tree menu entry. It does not prevent from changing the document, but if it's set ON, the changes won't be flushed to the disk immediately. If one opens the XML document while Read-Only is ON, the notification will appear on the screen. If the user does not have "write" permissions on the file, another notification is shown and Read-Only switch is set ON automatically; it cannot be changed in this case.

Reference Tree

Reference Tree is another read-only XML document, which can be open in a separate window to copy information from it into main document. There are three options available: copy tag name, copy tag text (both mean into clipboard) and replicate the whole tag with all its attributes and child nodes into main document (see "Replicate From Reference" below).

Editing XML document

XML Tree Editor displays XML documents in tree views, with every node representing a single XML tag with optional text and optional attributes. The following document will refer to "nodes" instead of "tags" to keep in with visual representation.
Editing nodes means changing node name, text and attributes in one place - the Edit Node form, shown below.

Adding Nodes

There are three commands to add nodes to the document, and the difference is the position of the new node in relation to the highlighted node on the tree. All three commands call Edit Node form first, where one must enter at least node name, then on Save click, the new node is created and positioned.

Add Child Node adds the new node to the end of its children list.

Add Above positions the new node just before the selected item on the same level. This option is not available for the root node (a single node on the top of the tree).

Add Below puts the new node right after selected item on the same level.

Add Comment opens Multi-line Editor to type the comment text, then places the comment depending of the type of selected node. For nodes without text (shown as folders in the tree view), the new comment is the first child. For nodes with text the comment is placed just above the selected node.

Editing Nodes

To edit a node select it on the tree and invoke Edit Node command or just double-click on it. Depending whether the selection is XML tag or comment either Edit Node form or Multi-line Editor is open. On clicking Save (the shortcut is Ctrl+Enter) updated information is written back to the document. It worth to mention again, that unless Read-Only checkbox is ON, the whole file on disk is re-written immediately.

Apart from simple editing node name, text and unlimited number of attributes, Edit Node form provides some extra features. Most extra commands are available through popup menus.

If either node name or attribute name contains illegal characters, the field is marked with warning colour and Save function becomes disabled.

The attributes must have both names and values, so the simplest way to delete the attribute is to clear either its name or value field.

Frequently used node names can be saved for later re-use with Save Node Name command. Stored names appear in the drop-down list in the Node Name field.

The attribute name can be saved for re-use same way with Save Attribute Name command. To retrieve it there is Get Attribute Name command which opens the saved list.

Node Text can be filled with extended information using commands from popup menu, assigned to the button next to the field.

Multi-line Editor opens another form with simple editor, which allows to enter line breaks and tabs (press Ctrl+Tab) and preserves them in the text field. Word-wrap feature allows to see and edit long lines without adding actual breaks.

File Name opens file selection dialogue and saves chosen file name.

Load Text File opens same file selection dialogue and reads the content of the selected text file into Node Text field without altering it. The program internally handles escapes (replacements for illegal characters), so the text file can be, for example, another XML document.

Load Binary File works the similar way, but performs Hex-to-String conversion.

Load Color opens system colour selection dialogue and saves colour value as hexadecimal RGB representation.

Add Attribute and Delete Attribute commands added for convenience to overtake somewhat unexpected grid behaviour.

Other Node Manipulation commands

The below commands change nodes as the whole with all their attributes and child nodes. They are intentionally not implemented as drag-and-drop actions, prone to confusion and user errors, but instead are two or three steps operations with ability to cancel.

Move Node saves information about the selected mode and opens a simple dialogue window shown below.

One must select another node as reference position and choose how the node is going to be placed relatively to this position. On clicking Move the node with all its children and attributes is re-positioned.

Replicate Node works the same way as above, but the original node is not deleted, so two copies are present after operation is completed.

Delete Node displays the confirmation dialogue, then removes the node with all its children.

Replicate From Reference is only available if the reference tree in a separate window is open. The selected node in the reference tree is what is going to be cloned, and the selected node in the main document window shows where its copy to be inserted.

Drag and Drop support

Since version 0.1.0.21 XML Tree Editor supports drag-and-drop operations for Move / Replicate / Replicate from Reference commands. To initiate drag-and-drop operation one must press a modifier keyboard key and holding it, drag the node with left mouse button. The default modifiers are:

Ctrl - for Replicate and Replicate from Reference commands

Alt - for Move command (this may conflict with Linux Window Manager move window command)

The dragged node is positioned below the new selected node. If Shift key is also pressed, the node is positioned above the selected item. "Add as Child" is not available for drag-and-drop operations.

Modifier keys can be changed through the Options menu; their Ids are "dragCopy" and "dragMove". The value is a zero-based position of the key in the following list: Shift, Alt, Ctrl, Left, Right, Middle, Double, Meta, Super, Hyper, AltGr.

Finding nodes

There are two commands to find nodes with certain information; they are Find (Ctrl+F) and Find Next (F3) under Tree menu.

Find opens a small dialogue shown below

where one can type the search model and activate search. Clicking "Find" button performs search from the beginning of the document; "Next" searches from the current position down. There is no backward search option. Either names of nodes and attributes or both names and test values are included into search, depending on In Text checkbox state.

Configuration files

XML Tree Editor works with three configuration files (which may not exist). They are XML files and can be open and edited by XML Tree Editor.

Global configuration

The "global" configuration file - XMLTreeEdit.cfg, is included into distribution and contains all configurable options. One can edit it or make several copies for specific purposes. Command-line parameter -c or --config allows running the program with specified configuration. Its default location, unless specified by --config option, is:

Windows - same folder where the executable resides

Linux - /etc/

XML Tree Editor does not save anything into this file while running. As per version 0.1.0.14 this file contains comments to make its modification easier.

Local (user) configuration

The "local" configuration file does not exist until created by the program on its first run by the user. It has same name as "global" one, but resides in user local directory, which is "~/.config/XMLTreeEdit" in Linux. In Windows it depends on Windows version.
This file keeps all user-related parameters and histories of running program and changes on virtually every user action.

There is no point of opening and editing this file unless on special needs.

Translation file

The translation file - Translation.xml, sits in the same folder where the global configuration file is, and provides translation of program controls and messages to a given language. Currently there is only Russian translation available.

Command-line options

There are two command-line options available currently. They both require fully specified path + file name.

-c (short) or --config to run with specific global configuration file.
Syntax examples:
Windows

-c C:\folder\subfolder\file.cfg

--config=D:\Directory\AnotherDirectory\FileName.config

Linux

--config=/usr/share/program/config.cfg

-f or --file to open XML file for editing at start up.

One can omit -f/--file option and provide file name for opening as first command-line parameter.

Backup

Starting from version 0.1.0.16 XML Tree Editor provides backup feature to reduce the risk of data loss in the event of hardware/software failure and user errors. The objective for this new feature is that the XML file is re-written as the whole on every content change, so there is possible risk of total file loss, if its structure was damaged by some reason.

How Backup works

When backup is activated XML Tree Editor counts internally every act of saving the content, and when the number of saves reached a certain value, another copy of the XML document is saved onto the disk with the same name, as the original one, and an extra extension ".backup.xx", where "xx" is the backup number. So if one works, for example, with the file named "ABC.xml", one can find backup files in the same folder, called "ABC.xml.backup.00", "ABC.xml.backup.01" and so on. When backup number reached its maximum value (configurable, up to 100), it starts with 00 again, re-writing existing files.

Configurable Options

There are three options to enable/disable backup feature and set up its parameters.

First is a "Tree" menu entry called "Auto Backup". It is also presented in Options under name "allowBackup" with possible values 0 and 1.

The number of backup copies is governed by "backupCopies" integer option, which can be set to up to 100; the default value is 10.

The backup file is saved not on every change, so the number of steps between two backups is set by "autoBackup" integer option. Its default value is also 10.

Recovery Procedures

Let's assume that you accidentally deleted one top level node with all its multi-level contents; the document is still open in XML Tree Editor. One of the possible scenarios for recovery would be:

1. Disable Backup feature (temporarily)
2. Open the external file manager, navigate to the folder with the troubled document to see its backup copies
3. Choose one you think is the best, based on its date/size/backup number or other information
4. Open the chosen backup as Reference tree and replicate missed node into main document
   OR
5. Open the chosen backup as main document and save it under its original name; you may lose a few editing steps here
6. re-enable Backup feature