Skip to content

Commit 89579ca

Browse files
angelozerrdatho7561
angelozerr
authored and
datho7561
committed
Symbol outline / search: Customizable display text
Fixes #220 Signed-off-by: azerr <azerr@redhat.com>
1 parent 316f3b3 commit 89579ca

File tree

6 files changed

+192
-11
lines changed

6 files changed

+192
-11
lines changed

‎docs/Symbols.md‎

Lines changed: 146 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Symbols
22

3+
## xml.symbols.enabled
4+
5+
Enable/disable document symbols (Outline). Default is `true`. No symbols are given if `\"xml.symbols.enabled\": false`.
6+
37
## xml.symbols.maxItemsComputed
48

59
Use `xml.symbols.maxItemsComputed` to limit the number of symbols that are computed for each XML document.
@@ -10,7 +14,7 @@ The default limit is 5000.
1014
If the limit is set to 0, no symbols are computed.
1115
If the limit is set to a negative number, all the symbols will be computed.
1216

13-
If `xml.symbols.showReferencedGrammars` is enabled, the referenced grammar symbols are included in the count.
17+
If [xml.symbols.showReferencedGrammars](#xmlsymbolsshowreferencedgrammars) is enabled, the referenced grammar symbols are included in the count.
1418
If symbols are disabled, this setting has no effect.
1519

1620
## xml.symbols.showReferencedGrammars
@@ -22,5 +26,144 @@ The following are also listed:
2226

2327
![An XML document that references two grammars. The referenced grammars are listed in the outline](./images/Symbols/ShowReferencedGrammars.png)
2428

25-
This option has no effect if symbols are disabled through `xml.symbols.enabled`.
26-
The displayed symbols are affected by `xml.symbols.maxItemsComputed`
29+
This option has no effect if symbols are disabled through [xml.symbols.enabled](#xmlsymbolsenabled).
30+
The displayed symbols are affected by [xml.symbols.maxItemsComputed](#xmlsymbolsmaxitemscomputed)
31+
32+
## xml.symbols.filters
33+
34+
By default Outline (symbols) display `DOM elements`, `processing instruction` and `DTD element, entity, attribute list declarations`.
35+
36+
The DOM attributes and text nodes are not displayed in the outline. Indeed to ensure good performance, symbols must be limited; displaying attributes and text nodes in the outline could generate a lot of symbols.
37+
38+
Here a sample Outline with maven `pom.xml`:
39+
40+
![Outline of pom.xml without filter](images/Symbols/SymbolsPOMWithoutFilter.png)
41+
42+
In maven context, the text nodes information are important and we should prefer showing text nodes in the Outline:
43+
44+
![Outline of pom.xml with text filter](images/Symbols/SymbolsPOMWithTextFilter.png)
45+
46+
In Spring context, the `@Id` attribute information are important and we should prefer showing those attributes in the Outline:
47+
48+
![Outline of Spring beans with @id filter](images/Symbols/SymbolsBeansWithIdAttrFilter.png)
49+
50+
In other words, displaying attributes or text nodes depends on the XML file.
51+
52+
`xml.symbols.filters` gives the capability to define filter (to include or exclude) some attributes, some text nodes for a given XML file kind.
53+
54+
Symbols filter are composed with:
55+
56+
* `pattern` (required) : a regular expression matching the file names to which this filter should apply.
57+
* `expressions` (required) : defines a list of expression. An expression is composed by:
58+
* `xpath` (required) : defines a basic xpath to declare the attribute, the text node which is concerned by the expression.
59+
* `excluded` (optional): true if the node which matches the xpath must be excluded or not. By default the excluded is set to false.
60+
61+
The order of the expression item are important, because each expression are applied by using the order of the expressions array.
62+
63+
NOTE: when you change `xml.symbols.filters` in `settings.json`, the Outline is not refreshed automatically (see vscode [vscode issue 108722](https://github.com/microsoft/vscode/issues/108722)). You must refresh at hand the Outline by updating the XML file or closing/opening the XML file.
64+
65+
### Filter samples
66+
67+
#### Text nodes sample
68+
69+
For `pom.xml`, to obtain this Outline:
70+
71+
![Outline of pom.xml with text filter](images/Symbols/SymbolsPOMWithTextFilter.png)
72+
73+
you must declare this filter in the settings.json:
74+
75+
```json
76+
"xml.symbols.filters": [
77+
// Declaration of symbols filter for maven 'pom.xml' to show all text nodes in the Outline.
78+
{
79+
"pattern": "pom.xml",
80+
"expressions" :[
81+
{
82+
"xpath": "//text()"
83+
}
84+
]
85+
}
86+
]
87+
```
88+
89+
#### Attributes sample
90+
91+
For Spring `beans.xml`, to obtain this Outline:
92+
93+
![Outline of Spring beans with @id filter](images/Symbols/SymbolsBeansWithIdAttrFilter.png)
94+
95+
you must declare this filter in the settings.json:
96+
97+
```json
98+
"xml.symbols.filters": [
99+
// Declaration of symbols filter for Spring beans to show all @id of the elements in the Outline.
100+
{
101+
"pattern": "bean*.xml",
102+
"expressions" :[
103+
{
104+
"xpath": "//@id"
105+
}
106+
]
107+
}
108+
]
109+
```
110+
111+
#### Exclude sample
112+
113+
If you want to define a filter which `includes all attributes except the optional attribute`, you can write the filter like this:
114+
115+
```json
116+
"xml.symbols.filters": [
117+
// Declaration of symbols filter for Spring beans to show all @id of the elements in the Outline.
118+
{
119+
"pattern": "foo*.xml",
120+
"expressions" :[
121+
// Exclude optional attribute
122+
{
123+
"xpath": "//@optinal"
124+
"excluded": true
125+
},
126+
// Include other attributes
127+
{
128+
"xpath": "//@*",
129+
}
130+
]
131+
}
132+
]
133+
```
134+
135+
An another sample of exclusion is when you have a large XML file and you want to show a part of the XML content. You can exclude some elements with xpath.
136+
137+
```json
138+
"xml.symbols.filters": [
139+
// Declaration of symbols filter to exclude description elements and their children in the Outline.
140+
{
141+
"pattern": "file*.xml",
142+
"expressions" :[
143+
{
144+
"xpath": "//description",
145+
"excluded": true
146+
}
147+
]
148+
}
149+
]
150+
```
151+
152+
### XPath expression
153+
154+
The syntax of XPath expression are basic and doesn't support advanced XPath expression.
155+
156+
Here some sample for attribute XPath expression:
157+
158+
* `//@*` : display all attributes.
159+
* `//@id` : display all ID attribute.
160+
* `//bean/@id` : display ID attribute only for all bean element.
161+
* `//beans/bean/@id` : display ID attribute only for bean element which have beans parent element.
162+
* `//beans/bean[@name='ABCD']/@id` : display ID attribute only for bean element which have beans parent element and which have a name attribute equals to ABCD.
163+
* `//beans/bean[@name='ABCD'][@name2='ABCD']/@id` : display ID attribute only for bean element which have beans parent element and which have a name and name2 attributes equals to ABCD.
164+
165+
Here some sample for text XPath expression:
166+
167+
* `//text()` : display all text nodes.
168+
* `//bean/text()` : display text node only for bean element.
169+
* `//beans/bean/text()` : display text node only for bean element which have beans parent element.

‎docs/images/Symbols/ShowReferencedGrammars.png‎

-37 KB
Loading

‎docs/images/Symbols/SymbolsBeansWithIdAttrFilter.png‎

34.9 KB
Loading

‎docs/images/Symbols/SymbolsPOMWithTextFilter.png‎

28.2 KB
Loading

‎docs/images/Symbols/SymbolsPOMWithoutFilter.png‎

28.7 KB
Loading

‎package.json‎

Lines changed: 46 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -139,21 +139,21 @@
139139
"items": {
140140
"type": "object",
141141
"properties": {
142-
"systemId": {
143-
"type": "string",
144-
"description": "The path or URL to the XML schema (XSD or DTD)."
145-
},
146142
"pattern": {
147143
"type": "string",
148144
"markdownDescription": "File glob pattern. Example: `**/*.Format.ps1xml`\n\nMore information on the glob syntax: https://docs.oracle.com/javase/tutorial/essential/io/fileOps.html#glob"
145+
},
146+
"systemId": {
147+
"type": "string",
148+
"description": "The path or URL to the XML schema (XSD or DTD)."
149149
}
150150
},
151151
"required": [
152-
"systemId",
153-
"pattern"
152+
"pattern",
153+
"systemId"
154154
]
155155
},
156-
"markdownDescription": "Allows XML schemas/ DTD to be associated to file name patterns. Please refer to [XML file association with XSD](command:xml.open.docs?%5B%7B%22page%22%3A%22Validation%22%2C%22section%22%3A%22xml-file-association-with-xsd%22%7D%5D) or [XML file association with DTD](command:xml.open.docs?%5B%7B%22page%22%3A%22Validation%22%2C%22section%22%3A%22xml-file-association-with-dtd%22%7D%5D) for more information. \n\nExample:\n```json\n[{\n \"systemId\": \"path/to/file.xsd\",\n \"pattern\": \"file1.xml\"\n},\n{\n \"systemId\": \"http://www.w3.org/2001/XMLSchema.xsd\",\n \"pattern\": \"**/*.xsd\"\n}]\n```",
156+
"markdownDescription": "Allows XML schemas/ DTD to be associated to file name patterns. Please refer to [XML file association with XSD](command:xml.open.docs?%5B%7B%22page%22%3A%22Validation%22%2C%22section%22%3A%22xml-file-association-with-xsd%22%7D%5D) or [XML file association with DTD](command:xml.open.docs?%5B%7B%22page%22%3A%22Validation%22%2C%22section%22%3A%22xml-file-association-with-dtd%22%7D%5D) for more information. \n\nExample:\n```json\n[{\n \"pattern\": \"file1.xml\",\n \"systemId\": \"path/to/file.xsd\"\n},\n{\n \"pattern\": \"**/*.xsd\",\n \"systemId\": \"http://www.w3.org/2001/XMLSchema.xsd\"\n}]\n```",
157157
"scope": "window"
158158
},
159159
"xml.format.enabled": {
@@ -336,7 +336,7 @@
336336
"xml.symbols.enabled": {
337337
"type": "boolean",
338338
"default": true,
339-
"markdownDescription": "Enable/disable document symbols (Outline). Default is `true`. No symbols are given if `\"xml.symbol.enabled\": false`.",
339+
"markdownDescription": "Enable/disable document symbols (Outline). Default is `true`. No symbols are given if `\"xml.symbols.enabled\": false`.",
340340
"scope": "window"
341341
},
342342
"xml.symbols.excluded": {
@@ -359,6 +359,44 @@
359359
"markdownDescription": "Show referenced grammars in the Outline. Default is `true`. Please see [here](command:xml.open.docs?%5B%7B%22page%22%3A%22Symbols%22%2C%22section%22%3A%22xmlsymbolsshowreferencedgrammars%22%7D%5D) for more information.",
360360
"scope": "window"
361361
},
362+
"xml.symbols.filters": {
363+
"type": "array",
364+
"default": [],
365+
"items": {
366+
"type": "object",
367+
"properties": {
368+
"pattern": {
369+
"type": "string",
370+
"markdownDescription": "File glob pattern. Example: `**/*.Format.ps1xml`\n\nMore information on the glob syntax: https://docs.oracle.com/javase/tutorial/essential/io/fileOps.html#glob"
371+
},
372+
"expressions": {
373+
"type": "array",
374+
"default": [],
375+
"items": {
376+
"type": "object",
377+
"description": "The XML symbol expression.",
378+
"properties": {
379+
"xpath": {
380+
"type": "string",
381+
"markdownDescription": "The XPath expression of the filter."
382+
},
383+
"excluded": {
384+
"type": "boolean",
385+
"description": "Exclude/Include the node which matches the XPath expression ."
386+
}
387+
}
388+
},
389+
"markdownDescription": "Array of XML symbol expressions"
390+
}
391+
},
392+
"required": [
393+
"pattern",
394+
"expressions"
395+
]
396+
},
397+
"markdownDescription": "Allows XML symbols filter to be associated to file name patterns. See [here](command:xml.open.docs?%5B%7B%22page%22%3A%22Symbols%22%2C%22section%22%3A%22xmlsymbolsfilters%22%7D%5D) for more information.. \n\nExample:\n```json\n[\n {\n \"pattern\": \"pom.xml\",\n \"expressions\": [\n {\n \"xpath\": \"//text()\"\n }\n ]\n }\n]\n```",
398+
"scope": "window"
399+
},
362400
"xml.extension.jars": {
363401
"type": "array",
364402
"default": [],

0 commit comments

Comments
 (0)
⚡