Symbol outline / search: Customizable display text

Fixes redhat-developer#220

Signed-off-by: azerr <[email protected]>

docs/Symbols.md

@@ -1,5 +1,9 @@
 # Symbols
 
+## xml.symbols.enabled
+
+Enable/disable document symbols (Outline). Default is `true`. No symbols are given if `\"xml.symbols.enabled\": false`.
+
 ## xml.symbols.maxItemsComputed
 
 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.
 If the limit is set to 0, no symbols are computed.
 If the limit is set to a negative number, all the symbols will be computed.
 
-If `xml.symbols.showReferencedGrammars` is enabled, the referenced grammar symbols are included in the count.
+If [xml.symbols.showReferencedGrammars](#xmlsymbolsshowreferencedgrammars) is enabled, the referenced grammar symbols are included in the count.
 If symbols are disabled, this setting has no effect.
 
 ## xml.symbols.showReferencedGrammars
@@ -22,5 +26,144 @@ The following are also listed:
 
 ![An XML document that references two grammars. The referenced grammars are listed in the outline](./images/Symbols/ShowReferencedGrammars.png)
 
-This option has no effect if symbols are disabled through `xml.symbols.enabled`.
-The displayed symbols are affected by `xml.symbols.maxItemsComputed`
+This option has no effect if symbols are disabled through [xml.symbols.enabled](#xmlsymbolsenabled).
+The displayed symbols are affected by [xml.symbols.maxItemsComputed](#xmlsymbolsmaxitemscomputed)
+
+## xml.symbols.filters
+
+By default Outline (symbols) display `DOM elements`, `processing instruction` and `DTD element, entity, attribute list declarations`.
+
+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.
+
+Here a sample Outline with maven `pom.xml`:
+
+![Outline of pom.xml without filter](images/Symbols/SymbolsPOMWithoutFilter.png)
+
+In maven context, the text nodes information are important and we should prefer showing text nodes in the Outline:
+
+![Outline of pom.xml with text filter](images/Symbols/SymbolsPOMWithTextFilter.png)
+
+In Spring context, the `@Id` attribute information are important and we should prefer showing those attributes in the Outline:
+
+![Outline of Spring beans with @id filter](images/Symbols/SymbolsBeansWithIdAttrFilter.png)
+
+In other words, displaying attributes or text nodes depends on the XML file.
+
+`xml.symbols.filters` gives the capability to define filter (to include or exclude) some attributes, some text nodes for a given XML file kind.
+
+Symbols filter are composed with:
+
+* `pattern` (required) : a regular expression matching the file names to which this filter should apply.
+* `expressions` (required) : defines a list of expression. An expression is composed by:
+  *  `xpath` (required) : defines a basic xpath to declare the attribute, the text node which is concerned by the expression.
+  * `excluded` (optional): true if the node which matches the xpath must be excluded or not. By default the excluded is set to false.
+
+The order of the expression item are important, because each expression are applied by using the order of the expressions array.
+
+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.
+
+### Filter samples
+
+#### Text nodes sample
+
+For `pom.xml`, to obtain this Outline:
+
+![Outline of pom.xml with text filter](images/Symbols/SymbolsPOMWithTextFilter.png)
+
+you must declare this filter in the settings.json:
+
+```json
+"xml.symbols.filters": [
+   // Declaration of symbols filter for maven 'pom.xml' to show all text nodes in the Outline.
+   {
+      "pattern": "pom.xml",
+      "expressions" :[
+         {
+            "xpath": "//text()"
+         }
+      ]
+   }
+]
+```
+
+#### Attributes sample
+
+For Spring `beans.xml`, to obtain this Outline:
+
+![Outline of Spring beans with @id filter](images/Symbols/SymbolsBeansWithIdAttrFilter.png)
+
+you must declare this filter in the settings.json:
+
+```json
+"xml.symbols.filters": [
+   // Declaration of symbols filter for Spring beans to show all @id of the elements in the Outline.
+   {
+      "pattern": "bean*.xml",
+      "expressions" :[
+         {
+            "xpath": "//@id"
+         }
+      ]
+   }
+]
+```
+
+#### Exclude sample
+
+If you want to define a filter which `includes all attributes except the optional attribute`, you can write the filter like this:
+
+```json
+"xml.symbols.filters": [
+   // Declaration of symbols filter for Spring beans to show all @id of the elements in the Outline.
+   {
+      "pattern": "foo*.xml",
+      "expressions" :[
+         // Exclude optional attribute 
+         {
+            "xpath": "//@optinal"
+            "excluded": true
+         },
+         // Include other attributes
+         {
+            "xpath": "//@*",
+         }
+      ]
+   }
+]
+```
+
+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.
+
+```json
+"xml.symbols.filters": [
+   // Declaration of symbols filter to exclude description elements and their children in the Outline.
+   {
+      "pattern": "file*.xml",
+      "expressions" :[
+         {
+            "xpath": "//description",
+            "excluded": true
+         }
+      ]
+   }
+]
+```
+
+### XPath expression
+
+The syntax of XPath expression are basic and doesn't support advanced XPath expression.
+
+Here some sample for attribute XPath expression:
+
+* `//@*` : display all attributes.
+* `//@id` : display all ID attribute.
+* `//bean/@id` : display ID attribute only for all bean element.
+* `//beans/bean/@id` : display ID attribute only for bean element which have beans parent element.
+* `//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.
+* `//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.
+
+Here some sample for text XPath expression:
+
+* `//text()` : display all text nodes.
+* `//bean/text()` : display text node only for bean element.
+* `//beans/bean/text()` : display text node only for bean element which have beans parent element.

package.json

@@ -139,21 +139,21 @@
           "items": {
             "type": "object",
             "properties": {
-              "systemId": {
-                "type": "string",
-                "description": "The path or URL to the XML schema (XSD or DTD)."
-              },
               "pattern": {
                 "type": "string",
                 "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"
+              },
+              "systemId": {
+                "type": "string",
+                "description": "The path or URL to the XML schema (XSD or DTD)."
               }
             },
             "required": [
-              "systemId",
-              "pattern"
+              "pattern",
+              "systemId"
             ]
           },
-          "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```",
+          "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```",
           "scope": "window"
         },
         "xml.format.enabled": {
@@ -336,7 +336,7 @@
         "xml.symbols.enabled": {
           "type": "boolean",
           "default": true,
-          "markdownDescription": "Enable/disable document symbols (Outline). Default is `true`. No symbols are given if `\"xml.symbol.enabled\": false`.",
+          "markdownDescription": "Enable/disable document symbols (Outline). Default is `true`. No symbols are given if `\"xml.symbols.enabled\": false`.",
           "scope": "window"
         },
         "xml.symbols.excluded": {
@@ -359,6 +359,44 @@
           "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.",
           "scope": "window"
         },
+        "xml.symbols.filters": {
+          "type": "array",
+          "default": [],
+          "items": {
+            "type": "object",
+            "properties": {
+              "pattern": {
+                "type": "string",
+                "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"
+              },
+              "expressions": {
+                "type": "array",
+                "default": [],
+                "items": {
+                  "type": "object",
+                  "description": "The XML symbol expression.",
+                  "properties": {
+                    "xpath": {
+                      "type": "string",
+                      "markdownDescription": "The XPath expression of the filter."
+                    },
+                    "excluded": {
+                      "type": "boolean",
+                      "description": "Exclude/Include the node which matches the XPath expression ."
+                    }
+                  }
+                },
+                "markdownDescription": "Array of XML symbol expressions"
+              }
+            },
+            "required": [
+              "pattern",
+              "expressions"
+            ]
+          },
+          "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```",
+          "scope": "window"
+        },
         "xml.extension.jars": {
           "type": "array",
           "default": [],