FlexDoc/XML - DiagramKit
1. What is DiagramKit?
DiagramKit is the FlexDoc/XML native diagramming engine. It creates beautiful XSD component diagrams, which can be generated/inserted simultaneously along with the documentation generated by XSDDoc/WSDLDoc (with the support of all possible hyperlinks).DiagramKit is implemented as a diagramming plugin, which is a replaceable part of FlexDoc/XML that provides some graphical representations of XML elements. It is another add-on to FlexDoc/XML and licensed separately.
Below are two sample diagrams generated by DiagramKit (click on the screenshots to view each diagram inside the documentation):
For more sample documentation with diagrams generated by DiagramKit, please see:
2. Key Features
Generation of XSD (XML Schema) component diagrams:-
The diagrams are generated (as PNG image files) for the following components:
- Global and local elements
- Named complex types
- Element (model) groups
- Attribute groups
-
The focus of each diagram is to depict the result content model (elements/attributes) represented by the component:
- All possible child elements (their allowed compositions and cardinalities)
- When a depicted element is the head of a substitution group, a special branch attached to it shows all group member (substituting elements)
- All possible attributes (with their cardinalities)
- Base type / element type (all components inherited from them are shown within a separate panel)
- Element/attribute groups
- Compositors (all/choice/sequence)
- Attribute prohibitions (only those specified in the definition of the given component)
-
Diagrams can also include descriptions to everything mentioned above (obtained from the corresponding
<xs:annotation>
elements). The wrapping of annotation text is optimized so as to maximally utilize the empty space arisen in the diagram because of its particular layout, thereby minimizing the bloating of the diagram by annotations themselves. This allows making the whole diagram more compact, as shown on this screenshot: See also: FlexDoc/XML | DiagramKit | FAQ | Diagram Settings | How to show/hide annotations? -
Since the version 2.0, DiagramKit supports showing in diagrams properties of elements and attributes.
Properties provide extra information such as the element/attribute type, content, facets, default value etc. Properties are displayed in the little grid embedded within the diagram node that depicts the element/attribute. Some of the properties are hyperlinked to the corresponding pieces of the documentation.
For further details, please see: FlexDoc/XML | DiagramKit | FAQ | Component Properties.
The following screenshots show two diagrams of the same XSD component. The diagram on the left is with element/attribute properties. On the right, it is without the properties. Click on the screenshots to see each diagram within the corresponding documentation:
-
Our XSD diagrams largely follow the notation used in XMLSpy with the following differences:
-
Both restricted and extended base types are equally shown in the diagram (including everything inherited from them).
XMLSpy diagrams show only extended base types. The restricted base types are absent at all. The attributes inherited from them are joined with those defined in the given component, however highlighted with the yellow background.
- Abstract elements/complexTypes are highlighted with the italic font
-
The annotations can be shown for anything that may contain them (including for base/element types) as
- The first sentence of the annotation text
- The full annotation text
The wrapping of annotations is optimized so as to maximally use the empty space available in the diagram because of its layout, thereby making the whole diagram more compact.
-
More diagram hyperlinks are generated (basically from any visible feature or label),
including from the depictions not hyperlinked anyhow in XMLSpy diagrams:
- From base/element types to their details (e.g. the title of the blue panel in the screenshots above)
- From compositors (all/choice/sequence) to the corresponding locations in schema XML source where they are defined
- From element/attribute wildcards to their details
- From attribute groups to their details
- From the values of some element/attribute properties
- Our diagrams also look cleaner because no collapse/expand buttons are shown on each diagram element.
-
Both restricted and extended base types are equally shown in the diagram (including everything inherited from them).
-
What exactly the diagrams include and how they look can be configured with the special template parameters controlling DiagramKit
(available in both XSDDoc/WSDLDoc):
3. Running FlexDoc/XML + DiagramKit
Since DiagramKit is a part of FlexDoc/XML software, it will be pre-installed together with FlexDoc/XML.Error occurred during initialization of boot layer
java.lang.module.FindException: Module javafx.base not found, required by flexdoc.xml.diagramkit
Where to get JavaFX?
In order to run DiagramKit, all JavaFX dependencies must be resolved. That can be achieved either:- By installing some JRE (i.e. Java Runtime Environment) that already includes all necessary JavaFX modules by default
- By installing JavaFX separately and specifying the path to its modules in the script/build files running FlexDoc/XML+DiagramKit
But since Java 11, Oracle has moved JavaFX into a separate project found on openjfx.io. Now, those who need JavaFX should download JavaFX SDK separately from there, install it and specify all JavaFX dependencies in their Java application according to that installation. That, of course, is too complicated for many ordinary users, and breaks down the whole idea of using some generic JRE pre-installed on user's computer (independently on FlexDoc/XML).
However, as a compensation for all that perturbation (and actually as its goal), since Java 11, anyone could build their own custom JRE (called «runtime image») that would include in itself any 3rd party modules necessary to run a given application on a particular computer platform.
Now, we took that new opportunity and prepared our own FlexDoc JRE (OpenJDK+JavaFX images) to run FlexDoc/XML+DiagramKit on Windows, Linux and macOS immediately. Just download this Java from our website and don't bother with anything else!
Both possibilities are described below:
Using FlexDoc JRE
We offer a custom JRE (called «FlexDoc JRE»), which is a set of {OpenJDK+JavaFX} images prepared to run FlexDoc/XML+DiagramKit immediately. Here is the step-by-step instruction according to your OS: We assume that you have already downloaded FlexDoc/XML archive and unpacked it at some location, which we shall designate as'{flexdoc-xml}'
.
Using FlexDoc JRE on Windows
-
Go to the downloads page once again and download from there:
“FlexDoc JRE (OpenJDK+JavaFX) to run FlexDoc/XML+DiagramKit | Windows/x64 (zip)”
flexdoc-jre-17_windows.zip
-
Unpack it into
{flexdoc-xml}
. You will have a folder:{flexdoc-xml}\jre
-
Go to:
{flexdoc-xml}\DiagramKit\
Now, you can immediately start
generator.bat
anddesigner.bat
found there to run Template Processor / Template Designer with DiagramKit activated as the diagramming engine.
Using FlexDoc JRE on Linux
-
Go to the downloads page once again and download from there:
“FlexDoc JRE (OpenJDK+JavaFX) to run FlexDoc/XML+DiagramKit | Linux/64 (tar.gz)”
flexdoc-jre-17_linux.tar.gz
-
Unpack it into
{flexdoc-xml}
. You will have a folder:{flexdoc-xml}/jre
-
Go to:
{flexdoc-xml}/DiagramKit/linux/
You will find
generator.sh
anddesigner.sh
prepared to run respectively Template Processor / Template Designer with DiagramKit activated as the diagramming engine. -
Set a permission to allow executing
generator.sh
/designer.sh
as a program. -
Now, everything must be ready to run
generator.sh
/designer.sh
!
Using FlexDoc JRE on macOS
However, we take advantage of that Apple still allows the macOS users to install and run on their computer the executables built by those users themselves. So, instead of preparing a ready to install & run FlexDoc JRE, we offer you an easy way to build it by yourself (which differs from the former mostly by the size of the downloaded archive file).
-
Go to the downloads page once again and download from there:
“FlexDoc JRE (OpenJDK+JavaFX) to run FlexDoc/XML+DiagramKit | macOS/64 (zip)”
flexdoc-jre-17_macOS.zip
-
Unpack it into
{flexdoc-xml}
. You will have a folder:{flexdoc-xml}/build_jre
-
openjdk-17_macos-x64_bin.tar.gz
– from https://jdk.java.net/17/ -
openjfx-17.0.0.1_osx-x64_bin-jmods.zip
– from https://gluonhq.com/products/javafx/
-
-
Now, in order to build the real JRE, you only need to execute the following script found in the same folder:
{flexdoc-xml}/build_jre/build_jre.command
Although, macOS won't allow you to run'build_jre.command'
straight, that is easy to overcome:-
First, open
'build_jre.command'
with TextEdit (confirm in the warning box that it is OK to open it). Then, simply resave that file via File | Save menu. With that procedure, you will sign'build_jre.command'
as its owner/creator, which is a precondition to be able running it. -
On top of that, you will need also to assign
'build_jre.command'
with the executable privilege. Run the Terminal and type in it'chmod u+x'
followed by a space and the full pathname of the script file (instead of typing it, just drag'build_jre.command'
from the Finder into the Terminal window). Then, press Enter.
'build_jre.command'
from the Finder just by clicking twice on it. -
First, open
-
After executing
'build_jre.command'
, a new directory will be created:{flexdoc-xml}/jre
'build_jre'
folder can be deleted then.) -
Go to:
{flexdoc-xml}/DiagramKit/macOS/
You will find
generator.command
anddesigner.command
prepared to run respectively Template Processor / Template Designer with DiagramKit activated as the diagramming engine.But again, to be able to run any of those script files, first you need to- Resave the script file using TextEdit.
-
Assign it with the executable privilege (by running the Terminal, typing in it
'chmod u+x'
followed by a space, draggingscript.command
into the Terminal window and pressing Enter).
Using standard Java + JavaFX SDK
If for some reasons you cannot use our FlexDoc JRE (for instance, in case of Maven), you may use any other (standard) Java installed on your system.Then, you will need:
- To specify the location of your Java in the script files running FlexDoc/XML+DiagramKit.
-
To download JavaFX SDK from openjfx.io,
install it on your system and specify the path to its modules in the script/build files running FlexDoc/XML+DiagramKit.
Concerning the compatibility of different versions of Java (JDK) and JavaFX. As of Aug 2021, all currently released JavaFX versions 11-17 will work with JDK 11 or later.
Using standard Java + JavaFX SDK on Windows
-
Go to openjfx.io (or directly to https://gluonhq.com/products/javafx/)
and download “JavaFX Windows SDK”, e.g.:
openjfx-17_windows-x64_bin-sdk.zip
Do not download “JavaFX Windows jmods” archive also available there! That is not a proper JavaFX SDK. Although, JMOD files contain some compiled images of Java modules, they can be processed only by jlink command, used to build a custom JRE.
Unpack the downloaded archive somewhere. You will get a folder like this:C:\javafx-sdk-17
-
Go to:
{flexdoc-xml}\DiagramKit\
Edit
generator.bat
/designer.bat
found in that directory, in these lines:::----------------------------------------------------------------------
:: Specify the location of Java 11 (or later) here. The default setting:
::
:: set JAVA_HOME=%FDH%\jre
::
:: assumes the installation of FlexDoc JRE (OpenJDK+JavaFX),
:: which you can download from http://www.flexdoc.xyz/downloads/
::----------------------------------------------------------------------
set JAVA_HOME=C:\Program Files\Java\jdk-17
::----------------------------------------------------------------------
:: Specify the location of JavaFX SDK 'lib' directory, e.g.:
:: C:\javafx-sdk-17\lib
::
:: Note: When you use FlexDoc JRE, leave this setting empty
::----------------------------------------------------------------------
set PATH_TO_FX=C:\javafx-sdk-17\lib -
Now, you can start
generator.bat
/designer.bat
to run Template Processor / Template Designer with DiagramKit activated as the diagramming engine.
Using standard Java + JavaFX SDK on Linux
-
Go to openjfx.io (or directly to https://gluonhq.com/products/javafx/)
and download “JavaFX Linux SDK” archive, e.g.:
openjfx-17_linux-x64_bin-sdk.zip
Do not download “JavaFX Linux jmods” archive also available there! That is not a proper JavaFX SDK. Although, JMOD files contain some compiled images of Java modules, they can be processed only by jlink command, used to build a custom JRE.
Unpack the downloaded archive somewhere. You will get a folder like this:/home/user/javafx-sdk-17
-
Go to:
{flexdoc-xml}/DiagramKit/linux/
You will find
generator.sh
anddesigner.sh
prepared to run respectively Template Processor / Template Designer with DiagramKit activated as the diagramming engine.Edit
generator.sh
/designer.sh
in these lines:#----------------------------------------------------------------------
# Specify the location of Java 11 (or later) here. The default setting:
#
# JAVA_HOME="$FDH/jre"
#
# assumes the installation of FlexDoc JRE (OpenJDK+JavaFX),
# which you can download from http://www.flexdoc.xyz/downloads/
#----------------------------------------------------------------------
JAVA_HOME="/home/user/jdk-17"
#----------------------------------------------------------------------
# Specify the location of JavaFX SDK 'lib' directory, e.g.:
# /home/user/javafx-sdk-17/lib
#
# Note: When you use FlexDoc JRE, leave this setting empty
#----------------------------------------------------------------------
PATH_TO_FX="/home/user/javafx-sdk-17/lib" -
Set a permission to allow executing
generator.sh
/designer.sh
as a program. -
Now, everything must be ready to run
generator.sh
/designer.sh
.
Using standard Java + JavaFX SDK on macOS
-
Go to openjfx.io (or directly to https://gluonhq.com/products/javafx/)
and download “JavaFX macOS SDK” archive, e.g.:
openjfx-17_osx-x64_bin-sdk.zip
Do not download “JavaFX Mac OS X jmods” archive also available there! That is not a proper JavaFX SDK. Although, JMOD files contain some compiled images of Java modules, they can be processed only by jlink command, used to build a custom JRE.
Unpack the downloaded archive somewhere. You will get a folder like this:/Users/Shared/javafx-sdk-17
-
Go to:
{flexdoc-xml}/DiagramKit/macOS/
You will find
generator.command
anddesigner.command
prepared to run respectively Template Processor / Template Designer with DiagramKit activated as the diagramming engine.Edit
generator.command
/designer.command
in these lines:#----------------------------------------------------------------------
# Specify the command used to invoke JVM (Java 11 or later) here.
# The default setting:
#
# JAVA_COMMAND="$FDH/jre/bin/java"
#
# assumes the installation of FlexDoc JRE (OpenJDK+JavaFX),
# which you can download from http://www.flexdoc.xyz/downloads/
#----------------------------------------------------------------------
JAVA_COMMAND="java"
#----------------------------------------------------------------------
# Specify the location of JavaFX SDK 'lib' directory, e.g.:
# /Users/Shared/javafx-sdk-17/lib
#
# Note: When you use FlexDoc JRE, leave this setting empty
#----------------------------------------------------------------------
PATH_TO_FX="/Users/Shared/javafx-sdk-17/lib" -
To be able to run
generator.command
, first, open it with TextEdit (confirm in the warning box that it is OK to open it). Then, simply resave that file via File | Save menu. By doing that you will signgenerator.command
as its owner/creator, which is a precondition to be able running it.Then, you need to assign
generator.command
with the executable privilege. Run the Terminal and type in it'chmod u+x'
followed by a space and the full pathname of the script file (instead of typing it, just draggenerator.command
from the Finder into the Terminal window). Then, press Enter.Now, you can run
generator.command
from the Finder just by clicking twice on it. -
Equally with
designer.command
.
Integration with Ant/Maven
A demo about that you can find in your FlexDoc/XML installation:{flexdoc-xml}/DiagramKit/ant/
{flexdoc-xml}/DiagramKit/maven/
{flexdoc-xml}/DiagramKit/README.html
- FlexDoc/XML | DiagramKit | FAQ | Generator Setups | Running with Apache Ant
- FlexDoc/XML | DiagramKit | FAQ | Generator Setups | Running with Apache Maven
4. Licensing / Processing Modes
DiagramKit works with both XSDDoc and WSDLDoc, however, it is licensed separately.That's because you can choose to use another diagramming plugin (e.g. XMLSpy Integration or OxygenXML Integration) or none at all instead.
To accommodate all possibilities concerning licensing, DiagramKit will work in the following modes:Demo Mode
When you have no particular license for DiagramKit, the Demo License is activated that enables a special demo mode. The purpose of that mode is to allow you without much hassle to see what DiagramKit basically can and in some cases even to use it for free.In demo mode, DiagramKit will work together with either XSDDoc/WSDLDoc when no other licenses are installed for both DiagramKit and the given template set. If you run XSDDoc or WSDLDoc, you will see a message like this:
Just click OK to continue.
In demo mode, DiagramKit will generate only limited number of component diagrams. How many depends on the demo limits of a particular main template. However, any diagrams generated in demo mode will be complete and without trial markers.
When demo mode is disabled
Because of programming limitations, DiagramKit can work in demo mode only with a template set (i.e. XSDDoc/WSDLDoc) also running in demo mode. When you already have a Full License for that template set (and no for DiagramKit), you will see a message like this:After clicking OK, you can continue using that template set (according to your license for it), however DiagramKit will be disabled:
- No component diagrams will be generated
-
All DiagramKit template parameters will be disabled too:
- Uninstall your license for the given template set (then it will work in demo mode too)
- Request a trial for DiagramKit
- Purchase the full license for DiagramKit
- Licensing | Demo License
- FlexDoc/XML | XSDDoc | Licensing | Demo Mode
- FlexDoc/XML | WSDLDoc | Licensing | Demo Mode
Trial Mode
Trial mode is activated in the presence of a Trial License for DiagramKit, which will work with full functionality and generate all possible diagrams (with all hyperlinks). However, there are following limitations:- All diagrams will contain trial watermarks, like on this screenshot:
- All generated output documents will be specifically distorted by replacing some letters with shade ('░') characters (as well as contain special messages).
- Any output documents or diagrams may be used only for evaluation of this software. Any other usage is prohibited!
- Trial license is limited to 30 days.
Then, you will be redirected to Try | Trial License page with “FlexDoc/XML” preselected in the «Product» field.
'flexdoc-xml.license'
file, which you will receive by email.
'lib'
directory (near 'flexdoc-xml.jar'
file):
{flexdoc-xml}/lib/
where '{flexdoc-xml}'
denotes your FlexDoc/XML installation directory.
See Also:
- Licensing | Trial License
- Licensing | Multiple Licenses
- FlexDoc/XML | XSDDoc | Licensing | Trial License
- FlexDoc/XML | WSDLDoc | Licensing | Trial License
Full Mode
Full mode is activated in the presence of a Full License for “FlexDoc/XML DiagramKit”. It allows you using DiagramKit without limitations. All diagrams will be generated clean (without any watermarks).Please Note:
- The license for DiagramKit covers only the generation of diagrams.
- Although, you can combine it with any other FlexDoc/XML licenses, it makes sense to purchase it only together with a license for XSDDoc or WSDLDoc.