FlexDoc/XML - DiagramKit - FAQ

Diagram Settings

How to customize generated diagrams?

Run FlexDoc/XML+DiagramKit to invoke the Template Processor (Generator) (e.g. by running generator.bat). You will see the Generator Dialog:

With the one of XSDDoc/WSDLDoc main templates selected (that you will use to generate your XSD/WSDL documentation), click the «Params» button on the right.

In the Parameter Inspector dialog that will show up, you will see a large tree of various parameters. Go to the bottom of that tree and open «DiagramKit» parameter group, which is shown in the fully expanded form on the following screenshot. These are currenly all settings that control DiagramKit (i.e. the generation of diagrams):

When you select particular parameter in that dialog, the bottom pane will be loaded with the corresponding parameter description, where you can read what this parameters means and how to use it. The same descriptions can be found on the page:
FlexDoc/XML | DiagramKit | Parameters
or by click each parameter on the screenshot above.

«DiagramKit» parameter group is present in all main templates of both XSDDoc and WSDLDoc. However, it is enabled only when the DiagramKit Plugin is active.

See Also:

How to show/hide annotations?

The generation of component descriptions visible on diagrams is controlled by the parameter:
DiagramKit | Show in Diagram | Annotations
as well as the parameter sub-tree below it (which together are called parameter group).

Using that parameter, you can specify whether to show in the diagrams:

The description text comes from the <xs:annotation> elements found in the XML schema in the definitions of components.

Wrapping of annotation

The annotation text may be of any length. However, it can occupy only limited width on the diagram that forms a column into which the entire text is wrapped. That wrapping is the subject of a compromise: This parameter group will help you to achieve the best result you need:
DiagramKit | Show in Diagram | Annotations | Wrapping
Two parameters in that group are most important:

How to show/hide element/attribute properties?

Displaying of element/attribute properties is controlled the parameter group «DiagramKit | Show in Diagram | Properties».

For further details, please see: FlexDoc/XML | DiagramKit | FAQ | Component Properties

How to show/hide substitution groups?

Substitution groups are shown in diagrams:

As member chains

Any substitution group can be shown on diagrams as a chain of diagram nodes depicting all substitution group members (or hierarchy of them) attached to the substitution group's head element.

On the following two diagrams, you can see the same substitution group with its members highlighted in red and its head element 'product' highlighted in green. On the left diagram, 'product' is the diagram's root node (i.e. the diagram depicts its content model). On the right diagram, 'product' is an ordinary node, just one among others:

That substitution group is actually multilevel one. The elements 'blouse' and 'tShirt' are members of own substitution group headed by 'shirt' element, which itself is a member of 'product' substitution group.

The showing of substitution group member chains is controlled by the parameter:
DiagramKit | Show in Diagram | Substitution Groups
which allows three settings:
always
Show the member chain by every depiction of substitution group's head element (as shown above)
by diagram root only
Show the member chain only when the substitution group's head element is the diagram's root node (as on the left diagram above).

Such a requirement may arise when there are too many substitution groups and/or they are too large, so showing them by every depiction of a corresponding root element will bloat the diagram to unmanageable size. As an example see “XML schema for MathML 3.0”, which extensively uses multilevel substitution groups.

none
Do not show the member chains

With element properties

Besides the member chains, another way to display substitution groups on diagrams is using these two element properties: How those properties look can be seen on the following diagrams:
These are the same diagrams as above, however, generated with the «DiagramKit | Show in Diagram | Substitution Groups» parameter set to 'by diagram root only'. On the second diagram. the member chain is not present, however the fact that 'products' is a substitution group head can be recognized by its substWith property.

How to stretch/shrink things shown on diagram?

About diagram nodes

Diagrams generated by DiagramKit are built of rectangular objects called nodes, which represent The leftmost node is the diagram's root node. It is special because the purpose of the whole diagram is typically to depict the content model of the XSD component represented by the root node. Sometimes, the whole diagram consists of the only root node, or the root node encloses all other nodes.

The relations between XSD components are depicted on the diagram in two ways:

Those diagram nodes that enclose other nodes are called complex nodes. When a node encloses no other nodes, it is called simple nodes. The majority of nodes on a typical diagram are simple ones.

For example, on the following diagram, all 7 simple nodes are highlighted in red and other 3 nodes are complex ones:

Controlling node widths

The width of a complex node is determined entirely by its content (i.e. the widths and layout of the nodes contained in it). That is calculated automatically and cannot be influenced from outside.

Some complex nodes may include a description of the XSD component represented by the entire node (e.g. <xs:complexType>). Such a description is shown at the top of the node rectangle and will be wrapped inside it. As the minimal wrapping width of any descriptions is controlled by the parameter: «DiagramKit | Show in Diagram | Annotations | Wrapping | Minimal Width», that may also influence the width of the node.

In the case of a simple node, its width is also calculated automatically so as to display the maximum information about the component. However, the width of a simple node is always kept within the range specified with the parameters: It works as follows:
  1. First, the node's preferred width is determined according to its content (e.g. the name of the XSD component it represents).
  2. When the preferred width is smaller than the minimal one specified with «Nodes | Minimal Width» parameter, the node's border is extended horizontally up to the required minimum.

    The effect can be seen on the following screenshots of the same XSD component (an element group with a very short name). On the left, the minimal node width was 10 px. On the right, it was 50 px (default).

  3. When the preferred width is larger than the maximal one specified with «Nodes | Maximal Width» parameter, some content of the node will be clipped so as to fit it into the maximal allowed width (and the ellipsis added to the displayed text to indicate the clipping).

    The effect can be seen on the following screenshots of the same XSD element component. On the left, the maximal node width was 350 px (default). On the right, it was 200 px.

Notes:

Node height

The height of a diagram node (both simple and complex) is not limited anyhow and will be determined by the particular node type and its content.

How to make diagrams look the same as in XMLSpy?

Some people ask, how to make the diagrams generated by DiagramKit to have the same color schema as the XSD diagrams in XMLSpy.

For instance, how to change the light blue background of the component diagrams to the familiar (to the clients) light yellow of XMLSpy?

Here is how to do that:

Go to the parameter group «DiagramKit | Styling» and specify the color parameters inside that group as follows:

Base Type Panel | Caption Color  = 808080
Base Type Panel | Background  = FFFFC0
Base Type Panel | Border Color  = 808080
Annotations | Color  = 808080
Colors can be both chosen interactively and specified in the field as hexadecimal value:
  1. Uncheck the default checkbox
  2. Click over the colored rectangle to activate the code text editor