Skip to content

Commit

Permalink
added BindingWithGrammar.md to document vscode-xml grammar binding
Browse files Browse the repository at this point in the history
  • Loading branch information
Alexander Chen committed Jul 29, 2021
1 parent e903708 commit e4cc8e5
Show file tree
Hide file tree
Showing 10 changed files with 119 additions and 18 deletions.
114 changes: 114 additions & 0 deletions docs/BindingWithGrammar.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
# Binding with Grammar

[vscode-xml](https://github.com/redhat-developer/vscode-xml) provides support for automatic XML schema/grammar binding through generation and/or using an existing `.xsd/.dtd` file.

[Validation with XSD grammar](Validation.md#validation-with-xsd-grammar) and [Validation with DTD grammar](Validation.md#validation-with-dtd-grammar) provide more information on manual binding of an XML document.

In the following sections, we would like to bind the XML document `foo.xml`:

```xml
<foo>
<bar />
</foo>
```

with an associated grammar file.

## Binding with Existing Grammar

Consider an XSD document, `foo.xsd` file (in the same directory as foo.xml) defined as follows :

```xsd
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="foo">
<xs:complexType>
<xs:sequence>
<xs:element name="bar" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
```

This file (or a corresponding `.dtd` file) can be bound using the [XML Binding Wizard](#the-xml-binding-wizard), which can be triggered by [Command](#command), [CodeLens](#codelens) or [Quick Fix](#quick-fix).

### The XML Binding Wizard

After opening the binding wizard using one of the methods mentioned above, a dropdown with the following 2 options will appear at the Command Palette:

![Binding Wizard Dropdown](./images/BindingWithGrammar/BindingWizardDropdown.png)

1. Standard (xsi, DOCTYPE)

This option will bind the grammar file by adding the `xmlns:xsi` (with the value as "http://www.w3.org/2001/XMLSchema-instance") and `xsi:noNamespaceSchemaLocation` (with the value as the path to the grammar file) attributes to the root tag:

```xml
<foo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="foo.xsd">
<bar />
</foo>
```

2. XML Model association

This option will bind the grammar file by adding the `xml-model` tag at the beginning of the file, with an `href` value as the path to the grammar file:

```xml
<?xml-model href="foo.xsd"?>
<foo>
<bar />
</foo>
```

After selecting an option, you can select the desired grammar file using your file explorer.

### Command

The command "XML: Bind to grammar/schema file" can be executed from the VSCode command palette, as well as be bound to a shortcut.

![Bind To Grammar Command](./images/BindingWithGrammar/BindToGrammarCommand.png)

If the current XML document is not bound using an `xml-model` tag or a root element doesn't have a `xsi:noNameSpaceLocation` attribute, the command will have the user select a existing `.xsd/.dtd` grammar file to bind to the XML document.

Otherwise, an error will be thrown on the client if the XML document already has a bound grammar/schema.

### CodeLens

When [CodeLenses](./Preferences.md#code-lens) are enabled, an unbound XML document will display a CodeLens above the root element as follows:

![Bind To Grammar Command](./images/BindingWithGrammar/BindToGrammarCodeLens.png)

### Quick Fix

For any unbound XML document, a Quick Fix suggestion will appear beside the root element.

![Bind To Grammar CodeAction](./images/BindingWithGrammar/BindToGrammarCodeAction.png)

With the cursor on the first opening tag, use `Ctrl + .`, `Quick Fix...` or the lightbulb that appears and select the "Open binding wizard to bind existing grammar/schema"

![Bind To Grammar CodeAction Dropdown](./images/BindingWithGrammar/BindToGrammarCodeActionDropdown.png)

## Binding with New Grammar

Consider the case where the directory only contains `foo.xml` (i.e. there does not exist an appropriate `.xsd/.dtd` file to bind).

A file can be generated using a [Quick Fix](#quick-fix-1).

### Quick Fix

#### Generate XSD from XML

When an unbound XML file is open, an XML Schema/XSD file can be generated from the opening tag in the XML file.

With the cursor on the first opening tag, use `Ctrl + .` or `Quick Fix...` or the lightbulb that appears and select "Generate foo.xsd and bind with *" to create the file in the the same directory.

![GenerateXSDFromXML](./images/BindingWithGrammar/GenerateXSDFromXML.gif)

#### Generate DTD from XML

When an unbound XML file is open, a Document Type Definition/DTD file can be generated from the opening tag in the XML file.

With the cursor on the first opening tag, use `Ctrl + .` or `Quick Fix...` or the lightbulb that appears and select "Generate foo.dtd and bind with *" to create the file in the the same directory.

![GenerateDTDFromXML](./images/BindingWithGrammar/GenerateDTDFromXML.gif)
22 changes: 4 additions & 18 deletions docs/Features/XMLFeatures.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,27 +126,13 @@ There is also validation based on grammar when a XSD or DTD file is associated w

See [XML Validation](../Validation.md#xml-validation) for more details.

## Generate Grammar from XML
## Binding Grammar to an XML Document

### Generate XSD from XML
For any XML document, should you need to bind a grammar or schema with the file, you can do by either using an existing grammar file, or by generating one using the built-in schema generator.

Using an XML file, an XML Schema/XSD file can be generated from the opening tag in the XML file. With the cursor on the first opening tag, use `Ctrl + .` or `Quick Fix...` and select `Generate foo.xsd and bind with *` to create the file in the the same directory.
See [Binding with Existing Grammar](../BindingWithGrammar.md#binding-with-existing-grammar) for info on binding to an existing schema.

![GenerateXSDFromXML](../images/Features/GenerateXSDFromXML.gif)

#### Read more

See [Validation with XSD Grammar](../Validation.md#validation-with-xsd-grammar) for more.

### Generate DTD from XML

Using an XML file, a Document Type Definition/DTD file can be generated from the opening tag in the XML file. With the cursor on the first opening tag, use `Ctrl + .` or `Quick Fix...` and select `Generate foo.dtd and bind with *` to create the file in the the same directory.

![GenerateDTDFromXML](../images/Features/GenerateDTDFromXML.gif)

#### Read more

See [Validation with DTD Grammar](../Validation.md#validation-with-dtd-grammar) for more.
See [Binding with New Grammar](../BindingWithGrammar.md#binding-with-new-grammar) for info on grammar generation.

## Selection Range

Expand Down
1 change: 1 addition & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ Welcome to the [vscode-xml](https://github.com/redhat-developer/vscode-xml) docu
* [Troubleshooting](Troubleshooting.md#troubleshooting): Info on troubleshooting and fixes to issues.
* [Features](Features.md#features): Notable info and demos on features available to use.
* [Proxy](Proxy.md#proxy): Instructions for setting up vscode-xml to work behind a proxy.
* [Binding With Grammar](BindingWithGrammar.md#binding-with-grammar): Extension feature to bind an XML document to a grammar/schema file.

## Developer Guide

Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit e4cc8e5

Please sign in to comment.