XML Editor Help

(This information is preliminary)

Help Topics:

 

Overview

XMLEdit is a simple application which presents you with three views:

  1. The leftmost view is a collapsible tree which contains one item for each tag in the XML file being edited. The tree can also either show or hide attributes.
  2. The center view is a collapsible property grid which is used to display and edit attributes and/or sub-tags of the tag currently selected in the tree.
  3. The rightmost view is a simple text edit window which shows the value of the tag or attribute item currently selected in the tree.

XMLEdit uses "profiles" to turn it into a custom editor. It is supplied with two custom editor profiles:

  1. Profile Editor - for creating or modifying editor profiles
  2. Property Grid Editor - for creating or modifying property grids used with editor profiles

 

XMLEdit Profiles

A profile allows XMLEdit to recognize tags in the XML file it is editing in order to display the appropriate image in the tree and select the appropriate property grid for editing the tag's attributes. It also allows XMLEdit to select an appropriate label for each item in the tree.

An XMLEdit profile contains:

Item Description Tree Image
(Default)
profile "Header" item...
  • One and only one per profile
  • The "root" item

item Associates tags in XML data with property grid descriptions
  • One item for each unique tag to be recognized
  • Sub-item of profile

Contains the following properties:

  • tag to be recognized
  • file name identifying propertygrid for editing the associated tag's attributes
  • file name specifying 16x15 bitmap image to display where this tag occurs in the tree.
  • attribute to be displayed as tree item text (instead of the tag itself)

 

XMLEdit Property Grids

Property Grid Basics

A property grid is a scrollable, collapsible list of properties which are operated on by any of a number of control types, depending on the characteristics of the property. For example, a file name would be operated on using a file selection dialog; a quantity value might be operated on via either a slider or a spin control; a simple yes/no value might be operated on using a checkbox.

Property grids contain "categories", which in turn contain property control items. By default, a category appears as a line item with a gray background. Since categories contain control items, a property grid always has to contain at least one category.

Property grids are also fully hierarchical. That means that a control can contain other controls; you can use any control as a sub-category, so to speak.

Property Grid Descriptions

A property grid description tells XMLEdit what controls are to appear in the property grid and what attribute each is mapped to. A property grid description file is required for each tag entry in an XMLEdit profile.

A property grid description file contains:

Item Description Tree Image
(Default)
propertygrid "Header" item...
  • One and only one per property grid description file
  • The "root" item
  • Usually requires its "id" property set to the tag the property grid is intended to edit

category Instantiates a "category" in the property grid
  • Must be at least one
  • Sub-item of propertygrid
  • Doesn't usually use the "id" property, but may

control Instantiates a control item in the property grid
  • One control operates on one attribute
  • "id" property specifies the attribute which the control is to edit
  • Control must be a sub-item of a category or another control

Additionally, the property grid description may also contain the following entries:

Item Description Tree Image
(Default)
include the include construct allows for the creation of more complex, structured property grids
  • Note that the name of the included file is implemented as a tag value, not an attribute.
  • If include is a sub-item of propertygrid, included file must have a category as its root item.
  • If include is a sub-item of either category or control, included file must have a control as its root item.

constraint constraints are actually static drop-down list items.
  • sub-items of text/drop-list controls only.

help This is actually an optional sub-item of propertygrid. It allows you to specify parameters for the help area

 

Creating Your Own Custom Editor Profile

The general steps for creating a custom editor profile are:

  1. Create the profile:
    1. Start XMLEdit and open an XML document for which you want to build an XMLEdit profile.
    2. Choose Tools|Create Profile from the XMLEdit menu. You will be prompted for the name and location of your new profile. 
    3. Select a location and file name for your new profile. After you have entered a file name for the profile, the Profile Editor will appear.
      Hint: you may want to create a separate folder to contain the new profile as it will eventually contain a collection of files.
    4. (Optional) Give your profile a name by entering it in the name box. This name will appear in XMLEdit's window title whenever it is using your profile.
    5. Save the profile if you made any changes, and close the Profile Editor. You will be returned to the XML Editor (containing your XML document) which will ask if you want to use the new profile immediately; choose "Yes". If you gave your profile a name in step 2, the name should now appear in XMLEdit's window title.

     

  2. Create a property grid for each unique tag in the XML data

    For each unique tag:
    1. Right-click a tag in the tree, and choose Edit Property Grid for Tag from the context menu. If no property grid has been created for this tag, XMLEdit will create a new property grid and will prompt you to supply a file name for it; otherwise, the Property Grid Editor will appear and you can skip step 2.
    2. Select a file name for the property grid. After you have entered a file name for the property grid, the Property Grid Editor will appear.
      Hint: you should place it in the same folder as the profile it belongs with. 
    3. Edit the property grid definition as desired (explained further below), save any changes, and close the property grid editor. You will be returned to your XML document. The property grid should update to reflect your changes.

     

  3. Create property grid controls for each attribute. When editing the property grid as in step 3 above:
    1. Select the appropriate tree item (usually a category item)
    2. Click on the "Add Item" toolbar button . A list of available item types will appear. The contents of this list will depend on what has been set up in the current profile.
    3. Choose the desired item from the list (control, in most cases). The item will be added to the property grid description and automatically selected.
    4. Set the properties for the new control as desired. Be sure to set the id property to match the attribute you want the control to edit.
    5. Repeat steps 1-4 as required.
    6. Save the property grid description and close the property grid editor. You will be returned to your XML document.

 

Selecting an Existing Profile

There are two ways to select a profile for XMLEdit to use (the active profile):

  1. While XMLEdit is open, choose Tools|Setup from the XMLEdit menu; enter the name of the profile or click the "..." button for a file selection dialog.

  2. When setting up a Windows shortcut for XMLEdit, type "-E:<file-spec>" as the first parameter following the program name, where <file-spec> identifies the desired profile. For example:

    C:\MyTools\XMLEdit.exe -E:C:\MyTools\ProfileEditor\ProfileEditor.xep

    Remember: you will need to enclose filenames in quotes if they contain spaces, for example:

    "C:\Program Files\XMLEdit\XMLEdit.exe" -E:"C:\Program Files\XMLEdit\ProfileEditor\ProfileEditor.xep"

Editing an Existing Profile

There are several ways to access existing profiles in order to edit them, depending on situation

Editing the Active Profile

You can edit the active profile in either of the following ways:

Editing Other Profiles

To edit a profile which has not been set as the active profile:

  1. Select the Profile Editor to be the active profile (see Selecting an Existing Profile)
  2. Use File|Open to open and edit the profile

Editing Property Grids

To edit the property grid definition for a tag you are viewing in the tree, simply right-click on it and choose Edit Property Grid for Tag from the context menu. If no definition file for the tag exists in the active profile, one will be created.

You can also select the Property Grid Editor and use File|Open from the menu to edit any property grid definition.

Working With Include

You can use the "include" construct to reuse sections of property grid definitions. The contents of an include file always contains a single root item (either control or category); within the root control or category, you can place any number of controls. This means that when you use control as the root item, you will typically end up with an extra level of indentation or nesting for the included controls, however there is a way around this.

To defeat the visual indenting which occurs when you place a control within a control, make the parent control type "None".

Working With the ID Property

When you enter a tag in an id property, it will be interpreted as relative if it does not contain the dot notation, and absolute (starting from the root of the document) if it does. For example: "dog", "head",  "body", and "nose" would all be interpreted as relative tags, but "dog.head", "dog.head.nose", and "head.nose" would all be interpreted as absolute. So, in the following XML:

<dog>
  <head>
    <nose/>
  </head>
  <body>
  </body>
</dog>

you could not use "head.nose" as a valid tag, because XMLEdit would interpret it as absolute and expect "head" to be the root item.

If you want your property grid to display a different hierarchy than occurs in your XML file (either flattening out or building up portions of it), you can't use the dot notation because of the previous point about absolute vs relative paths. However, there is another approach with appropriate use of the "Text" and "None" control types in combination with appropriate use of the id property.