Web Symbols Integration with Language Features
IDEs provide built-in support for Web Symbols integration with main language features of HTML, CSS, and JavaScript. Contribution of static symbols can be achieved through Web Types or Custom Elements Manifest, or by creating and registering a WebSymbolsQueryConfigurator extension.
The implementation of WebSymbolsQueryConfigurator requires overriding getScope(). This process involves the creation of a WebSymbolScope list, depending on the provided PsiElement (element parameter) and WebSymbolContext (context parameter). The following list of supported language features outlines the types of PsiElements that can be expected for each supported language feature.
Namespace: html
Kind: elements
Web Symbols representing available HTML elements. HTML element symbols can be contributed statically or dynamically (through WebSymbolsQueryConfigurator). The statically contributed symbols are available globally, depending on the context setting of the contributing Web Types file.
For dynamic contributions, the WebSymbolsQueryConfigurator.getScope()'s element parameter can be:
HtmlTag- Web Symbols should represent available HTML elements. The HTML tag's actual name should not be taken into account when building the scope.CssElement- Web Symbols should represent available HTML elements within a particular CSS file.
The matched Web Symbol is taken as a scope for matching HTML attributes of the tag.
Namespace: html
Kind: attributes
Web Symbols representing available HTML attributes. HTML attribute symbols can be contributed statically or dynamically (through WebSymbolsQueryConfigurator). The statically contributed symbols are available globally, depending on the context setting of the contributing Web Types file. If the containing tag is matched to a Web Symbol, it is added to the scope for attribute matching.
For dynamic contributions, the WebSymbolsQueryConfigurator.getScope()'s element parameter can be:
XmlAttribute- Web Symbols should represent available HTML attributes for matching. The HTML attribute actual name should not be taken into account when building the scope. However, the parent HTML tag and other attributes can be taken into account when building the scope.HtmlTag- Web Symbols should represent available HTML attributes for matching. The HTML tag and other attributes can be taken into account when building the scope.
Dedicated support for WebSymbol interface properties:
required- iftrue, a warning will be shown if the attribute is missing. Does not apply tovirtualattributes.default- the default value of the attribute, ifattributeValue.defaultisnull.attributeValue- provides information about the attribute value, seeattributeValuereference.
Namespace: css
Kind: properties
Web Symbols representing available CSS properties. Custom CSS properties (variables) names should be prefixed with --. CSS properties can be contributed statically or dynamically (through WebSymbolsQueryConfigurator). The statically contributed symbols are available globally, depending on the context setting of the contributing Web Types file.
Within a CSS file, the additional scope for matching properties is built from Web Symbols matching HTML element names from terminal selectors from the enclosing ruleset.
Within an HTML element style attribute value, an additional scope is built from Web Symbols matching the enclosing HTML element.
Scope for custom properties (variables) references (arguments for var() function) is built the same way as for properties. Only properties with names starting with -- are taken into account.
For dynamic contributions, the WebSymbolsQueryConfigurator.getScope()'s element parameter can be:
CssDeclaration- Web Symbols should represent available CSS properties for matching. The CSS declaration actual name should not be taken into account when building the scope.
Namespace: css
Kind: pseudo-elements
Web Symbols representing available CSS pseudo-elements. Symbols names should not be prefixed with ::. CSS pseudo-elements can be contributed statically or dynamically (through WebSymbolsQueryConfigurator). The statically contributed symbols are available globally, depending on the context setting of the contributing Web Types file.
The additional scope for matching pseudo-elements is built from Web Symbols matching HTML element name preceding the pseudo-element keyword.
For dynamic contributions, the WebSymbolsQueryConfigurator.getScope()'s element parameter can be:
CssPseudoSelector- Web Symbols should represent available CSS pseudo-elements for matching. The CSS pseudo-element actual name should not be taken into account when building the scope.
Dedicated support for WebSymbol interface properties:
properties[WebSymbol.PROP_ARGUMENTS]-trueif pseudo-element keyword accepts arguments.
Namespace: css
Kind: pseudo-classes
Web Symbols representing available CSS pseudo-classes. Symbols names should not be prefixed with :. CSS pseudo-classes can be contributed statically or dynamically (through WebSymbolsQueryConfigurator). The statically contributed symbols are available globally, depending on the context setting of the contributing Web Types file.
The additional scope for matching pseudo-classes is built from Web Symbols matching HTML element name preceding the pseudo-class keyword.
For dynamic contributions, the WebSymbolsQueryConfigurator.getScope()'s element parameter can be:
CssPseudoSelector- Web Symbols should represent available CSS pseudo-classes for matching. The CSS pseudo-class actual name should not be taken into account when building the scope.
Dedicated support for WebSymbol interface properties:
properties[WebSymbol.PROP_ARGUMENTS]-trueif pseudo-class keyword accepts arguments.
Namespace: css
Kind: functions
Web Symbols representing available CSS functions. CSS functions can be contributed statically or dynamically (through WebSymbolsQueryConfigurator). The statically contributed symbols are available globally, depending on the context setting of the contributing Web Types file.
The additional scope for matching functions is built from Web Symbols matching the CSS property name, the value of which is being calculated.
For dynamic contributions, the WebSymbolsQueryConfigurator.getScope()'s element parameter can be:
CssFunction- Web Symbols should represent available CSS functions for matching. The CSS function actual name should not be taken into account when building the scope.
Namespace: css
Kind: classes
Web Symbols representing available CSS classes. Symbols names should not be prefixed with .. CSS classes can be contributed statically or dynamically (through WebSymbolsQueryConfigurator). The statically contributed symbols are available globally, depending on the context setting of the contributing Web Types file.
Within CSS file, an additional scope for matching classes is built from Web Symbols matching HTML element name preceding the class keyword.
Within HTML attribute class the additional scope for matching classes is built from Web Symbols matching the enclosing HTML element name.
For dynamic contributions, the WebSymbolsQueryConfigurator.getScope()'s element parameter can be:
CssClass- Web Symbols should represent available CSS classes for matching. The CSS class actual name should not be taken into account when building the scope.XmlAttributeValue- Web Symbols should represent available CSS classes for matching within the attribute value.
2023.2+
Namespace: css
Kind: parts
Web Symbols representing available HTML element parts for matching with CSS ::part pseudo-element. CSS parts can be contributed statically or dynamically (through WebSymbolsQueryConfigurator). The statically contributed symbols are available globally, depending on the context setting of the contributing Web Types file.
Within CSS file, an additional scope for matching classes is built from Web Symbols matching HTML element name preceding the ::part keyword.
For dynamic contributions, the WebSymbolsQueryConfigurator.getScope()'s element parameter can be:
CssTermImpl- Web Symbols should represent available CSS parts for matching. The CSS part's actual name should not be taken into account when building the scope.
2023.2+
Namespace: js
Kind: string-literals
Web Symbols representing JavaScript or TypeScript string literals available in a particular location. Only dynamically contributed string literal symbols (through WebSymbolsQueryConfigurator) have built-in support.
The WebSymbolsQueryConfigurator.getScope()'s element parameter can be:
a
JSLiteralExpressionan unqualified
JSReferenceExpression, which parent is notJSIndexedPropertyAccessExpression,JSCallExpressionorJSProperty
2023.2+
Namespace: js
Kind: properties
Web Symbols represent properties of an object, which is a result of a JavaScript or TypeScript expression. Only dynamically contributed properties symbols (through WebSymbolsQueryConfigurator) have built-in support.
The WebSymbolsQueryConfigurator.getScope()'s element parameter can be:
JSObjectLiteralExpression- Web Symbols should represent expected propertiesJSExpression- Web Symbols should represent available properties the expression's result. Parent expression isJSReferenceExpressionorJSIndexedPropertyAccessExpression.
Dedicated support for WebSymbol interface properties:
type- if the type isJSType, it will be used in JavaScript type evaluator as the type of the propertyrequired- the JavaScript property is treated as non-optionalproperties[WebSymbol.PROP_READ_ONLY]- the JavaScript property is treated as read-only
2023.2+
Namespace: js
Kind: symbols
Web Symbols representing JavaScript symbols available for resolve of an unqualified JavaScript reference expression. Only dynamically contributed symbols (through WebSymbolsQueryConfigurator) have built-in support.
The WebSymbolsQueryConfigurator.getScope()'s element parameter can be:
an unqualified
JSReferenceExpression- Web Symbols should represent possible symbols to which JavaScript reference could resolve. The reference to actual name should not be taken into account when building the scope.
Dedicated support for WebSymbol interface properties:
type- if the type isJSType, it will be used in JavaScript type evaluator as the type of the symbolproperties[WebSymbol.PROP_KIND]- the kind of the symbol, one ofWebSymbolJsKindenum values. The kind will be used to render the appropriate icon in the code completion popupIntegration with unqualified reference resolution is not available in TypeScript code
Namespace: js
Kind: events
Web Symbols representing available DOM events. DOM events can be contributed statically or dynamically (through WebSymbolsQueryConfigurator). The statically contributed symbols are available globally, depending on the context setting of the contributing Web Types file.
The additional scope for matching DOM events is built from Web Symbols matching enclosing HTML element name.
For dynamic contributions, the WebSymbolsQueryConfigurator.getScope()'s element parameter can be:
HtmlTag- Web Symbols should represent available DOM events for matching.
When a language feature, such as an HTML element, is capable of representing an entity from a framework, like a Vue component, it may be beneficial to use a custom symbol kind with a domain-specific name (for example, vue-components), and establish a mapping from this to the language feature via a pattern:
{
"contributions": {
"html": {
"elements": [
{
"name": "Vue component",
"pattern": {
"items": "/html/vue-components"
},
"attributes": [
{
"name": "Component property",
"pattern": {
"or": [
{
"items": "props",
"priority": "highest"
}
]
},
"value": {
"type": "of-match"
}
}
]
}
]
}
}
}Note that in this example, attributes are produced from html/props symbols. For Vue component, a set of named values, which can be provided to the component instance are called props. Now, our Vue component definition can have a more domain-specific look:
{
"contributions": {
"html": {
"vue-components": [
{
"name": "MyVueComponent",
"description": "This is the component you always needed in your application",
"props": [
{
"name": "listen-to",
"type": "string | HTMLElement | Document | Window | (() => HTMLElement)",
"description": "The scrolling element to listen to.",
"default": "document"
}
]
}
]
}
}
}