CustomizationGuide

This page aims to help you to write mapping definition files. They are really simple to create and test.

Example

Following file is a simple mapping definition file:

<?xml version="1.0" encoding="UTF-8"?>
<xstructure xmlns="http://plugins.intellij.net/xstructure"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://plugins.intellij.net/xstructure http://plugins.intellij.net/xstructure/ns/xstructure_1_1.xsd"
            implType="default" name="Wiki test" version="1.1" priority="10">
  <supported-schemas>
    <schema uri="http://www.sample.org/model/wiki_test_1_.*.xsd"/>
  </supported-schemas>
  <mappings defaultSkip="none">
    <mapping match="/beans" label="{display-name}-{@version}" tip="{description}"/>
    <mapping match="/beans/description" skip="all"/>
    <mapping match="/beans/bean" label="{@id}" tip="{description}"/>
    <mapping match="/.*/property" label="{@name}" icon="/nodes/property.png"/>
    <mapping match="/.*/property/description" label="{.}" maxlength="30"/>
    <mapping match="/.*/property/(list|map)" skip="this"/>
    <mapping match="/.*/property/list/value" label="{.}"/>
    <mapping match="/.*/property/map/entry" label="{@key}={value}" skip="children"/>
  </mappings>
</xstructure>

Get the idea ? You specify which schemas/DTD your mappings target, and then you define nodes you'd like to see inside structure view and how they should be displayed.

Format is simple, and editing is even simplier since an XML Schema is provided to allow completion inside IDEA. This schema is explained below.

Mapping definition file schema

• xstructure

• Content: container for supported schemas and mapping definitions

• Attributes:

  • name: a logical name to identify this file. It will be display so user may choose a mapping definition file when several are available.
  • version: release number for this definition file. Mappings definition files are versionned since mappings or supported schemas may be updated.
  • priority: useful when several mapping definition files are available for the same file. They will be sorted by priority, and mappings with lowest priority will be selected by default
  • implType: implementation type. xStructure supports different implementations to resolve nodes. Recommended implementation is default, which is based on regular expressions. You could also used xpath implementation which provides more flexibility but is slower. See [ImplementationTypes] page for more details about implementation types.

• supported-schemas

• Content: container for supported schemas. May contain multiple schema nodes.

• schema

• Attributes:

  • uri: URI of any supported schema. This may be a DTD location (public or system URI) or an XML Schema location. Supports regular expressions (such as supported in Java).

• mappings

• Content: container for mapping definitions

• Attributes:

  • defaultSkip: specify default skip mode for nodes. When a node is not matched by any mappings, this settings define if it should be displayed or not. This value is overriden by skip attribute of mappings. See this attribute for accepted values

• mapping

• Attributes:

  • match: path used to identify which nodes are concerned by this mapping. Path format depends on implementation type. See [ImplementationTypes][3] page for more details about implementation types.
  • label: defines how matched nodes should be displayed. This expression is based on node context and typically uses children nodes text or attributes values. If not specified and skip mode is set to none, tag name will be used. Expression format depends on implementation type.
  • tip: defines optional tooltip for matched nodes. This expression is based on node context and typically uses children nodes text or attributes values. Expression format depends on implementation type.
  • icon: a path to an icon file which will be displayed as node icon. This path is relatived and applied from:
    • first, $IDEA_SETTINGS_DIR/config/xstructure/_icons directory. This directory stores icons which are not bundled with xStructure plugin
    • then, from IDEA and xStructure classpath. This means you may define icon by reusing IDEA icons (see $IDEA_DIR/lib/icons.jar)
  • maxlength: size limit for displayed text
  • skip: specify skip mode for matched nodes, overriding optional defaultSkip attribute of mappings element. Skip mode allows to hide some nodes which don't provide relevant information.

Accepted values for skip/defaultSkip attributes are:

• none: node is displayed using its label expression (default value)
• this: node is hidden but its children are displayed by default (according to their mappings). This allows to skip container elements.
• children: node is displayed buts its children are hidden by default (according to their mappings)
• all: node and its children are hidden (recursively)