Table of Contents
- Background: Why RELAX-NG?
- Version History
RELAX-NG is an emerging alternative to W3C XML Schema, which is said to be very complex and hard learn/use/maintain.
This plugin implements an IntelliJ IDEA feature request (IDEA-13734) to add full support for RELAX-NG to IntelliJ IDEA 7.0. It supports both the authoring of RELAX-NG schemas with many kinds of features IntelliJ IDEA is known for, and also improves the editing of XML documents that conform to a certain RELAX-NG schema.
The following sections list some of the main features, like on-the-fly error highlighting, code completion and refactoring. For a quick start, please see the section |#Configuration.
Error Highlighting for RELAX-NG Files
Error highlighting exists for various aspects of editing RELAX-NG documents. Unless otherwise stated, all of those are available in both the XML syntax as well as the Compact Syntax for RELAX-NG.
First, there is the validation of references to named patterns ("define") in RELAX-NG schemas. Unresolved references are highlighted and a Quick Fix is offered to create the missing declaration.
Namespace Prefix Validation
Namespace prefixes that are used in element- or attribute-declarations are checked whether they are bound to an actual namespace declaration, either by an
xmlns:XXX="..." attribute in the XML syntax or an equivalent
namespace XXX = "..." declaration in the compact syntax.
In both cases a QuickFix is offered to create an appropriate declaration for an unbound prefix.
The validation for the complete RELAX-NG model is performed by parsing and validating the currently opened RELAX-NG schema to report any violations about the model, such as invalid recursive usage of named patterns, missing start-elements (unless the file is included anywhere), and a lot more. This validation is performed by an external library (RNGOM) and is invoked by IDEA only when no other problems are present in the current file.
Unused Define Inspection
Not quite an error, but just like IDEA highlights other unused symbols, the plugin provides an inspection that looks for named patterns that aren't used anywhere and can be removed. This helps to create and maintain schemas that don't contain any unnecessary overhead.
The completion feature is split into two parts: Completion for references when editing RELAX-NG schemas and element- and attribute names while editing XML documents that are associated with a RELAX-NG schema.
In RELAX-NG files there is code completion for named patterns which offers all the named patterns that are visible inside the current scope. Of course, this also works both for the XML syntax as well as the Compact Syntax. In fact, in the compact syntax there's also the possibility to complete keywords, like "grammar" or "namespace".
When editing XML documents that are associated with a RELAX-NG schema, there will be completion for element- and attribute names at the current editing location. The completion offers are as precise as possible, but are not based on a full check of the underlying RELAX-NG model. That's similar to the completion IDEA offers for DTD or W3C XML schemas, which is basically a list of "what's theoretically possible". Although that bears some risk of completing something that's not correct, it enables the user to start making modifications that are not - yet - valid.
The plugin also provides an own RELAX-NG schema for RELAX-NG in XML syntax, which automatically supports the completion of RELAX-NG element names, such as "grammar", "define", etc. which are comparable with keywords in the Compact Syntax.
Refactoring and Navigation
Rename & Find Usages
References to named patterns can be renamed just like any other identifier in IDEA. The plugin will rename the declaration and all of its usages inside the visible scope. Navigation-features like "Find Usages", "Highlight Usages in File", "Goto Declaration (Ctrl-B)", etc. are available as well to navigate between named patterns and their references.
Overrides/Is Overridden Markers
For any pattern-definition that overrides a definition from an included file, an "overrides" marker will be displayed. For the overridden definition, an "is overridden" marker is displayed, both with the possibility to navigate to the respective target when clicking the gutter-icon.
Named pattern definitions can be searched for with the "Goto Symbol" feature, without having to know in which file exactly they are located.
When editing an XML document that is associated with a RELAX-NG schema, a complete validation will performed. The validation is split into two parts: An internal validation that checks whether an element, an attribute or attribute value is completely unknown and incorrect, and an external validation based on Jing that performs the full validation once no other problems are encountered.
It's possible to display documentation and comments for RELAX-NG constructs while editing XML documents using IDEA's standard "Quick Documentation Lookup" action. While editing RELAX-NG documents this can e.g. display comments about referenced define-patterns.
To convert schemas between different formats, there's a frontend to the conversion utility Trang which can do the following conversions:
- Convert RELAX-NG between XML- and Compact syntax
- Convert XML- and Compact Syntax RELAX-NG schemas into W3C XML Schema syntax
- Convert RELAX-NG schemas to and from XML 1.0 DTD syntax
- Create RELAX-NG schemas from XML instance documents
For the output type "XSD" as well as the input type "DTD", it is possible to tweak some conversion options in the "Advanced..." dialog. The options are explained in detail in the Trang manual.
Errors and warnings from the conversion process will be displayed in the "Messages" toolwindow.
With the action "Tools -> Validate" from the Main Menu it is possible to perform a manual validation of XML documents with the bundled RELAX-NG validator Jing. Messages from the validation process are displayed in the "Messages" toolwindow and can also be exported to a text file.
There's really not much to configure to make use of the plugin's support for working with RELAX-NG. Schemas in XML syntax are automatically recognized in any XML file by their namespace URI. Additionally, the extension "rng" is, if not already done, automatically registered with the XML file type. Compact Syntax files are recognized in files with the extension "rnc" by default, but this can be customized via
Settings | File Types by mapping any other extension to the "RELAX NG Compact Syntax" file type.
To get the full support when editing XML documents, the document's root tag namespace should be mapped to a RELAX-NG schema that describes the document. This can be done either by using IDEA's automatic download (the "Fetch External Resource" Quick Fix) in case the namespace URI directly references a RELAX-NG file or by manually setting up such a mapping via
Settings | External Resources.
For non-namespace documents this works a bit differently though. For such documents, it is possible to configure a RELAX-NG schema together with other per-file highlighting settings by clicking the little "Hector"-icon in the status bar. For non-namespace files, this popup will allow to select the path of the RELAX-NG schema to use for editing the file.
Background: Why RELAX-NG?
RELAX-NG is a lot simpler to read and write than W3C XML Schema, but can actually describe more complex structures. It also doesn't suffer from various inconsistencies in XML Schema, such as the different treatment of elements and attributes.
Currently RELAX-NG is gaining more and more momentum as it is being adopted by popular technologies like DocBook 5, XHTML 2.0, OpenOffice, etc. There's no doubt that, unless someone is a real expert in XML Schema, a RELAX-NG to model for a custom XML schema should be considerably easier to create, and would require less effort to document and maintain. Give it a try!
Some References about RELAX-NG
- Elliotte Rusty Harold, http://cafe.elharo.com/xml/relax-wins/
- James Clark, http://www.imc.org/ietf-xml-use/mail-archive/msg00217.html
- Griffin Brown, http://www.griffinbrown.co.uk/blog/PermaLink,guid,9aebb083-a961-42b1-9748-a57e06a0f19a.aspx
The plugin is available for IntelliJ IDEA 7.0 via the built-in plugin manager and at the IntelliJ Plugin Repository.
Version 0.9 (2007-11-13)
- Initial version
Version 1.0 (2007-11-21)
- Added conversion of RELAX-NG schemas with Trang (Tools -> Convert Schema...) as well as the possibility to create RELAX-NG schemas from XML instance documents (Tools -> Generate Schema from XML file...)
- Added ability to validate XML documents with RELAX-NG schemas via Tools -> Validate
- Added better support for Quick Documentation Lookup when authoring RNG files
Version 1.1 (2007-11-26)
- Improved handling of included files
- Inspection "UnusedDefine" works in Compact Syntax files and can be suppressed
- Added the possibility to associate non-namespace documents with a RELAX-NG schema. This can be done in the "Hector Popup" in the statusbar that also configures other per-file highlighting settings.
- Bugfixes & internal cleanup
Version 1.2 (2007-12-10)
- Display overridden/overrides markers for named patterns
- Initialize output path for schema conversion, ask to overwrite existing files
Version 1.2.1 (2007-12-13)
- Fixed some caching issues (changes in schema were not picked up)
- Suppress duplicate errors from Tools | Validate
Version 1.2.2 (2008-01-22)
- Fixed path issue in JARs on non-Windows systems
- Support for IDEA 8.x
Version 1.5.3 (2009-03-16)
- Correct attribute value validation for token datatype
Version 1.5.4 (2010-04-13)
- Support for IDEA 9.x