Installation and Administration Getting Started Command Line Configuration Eclipse Plugin Reference Manual API
Show on single page Show on multiple pages
Configuration Guide > Defining Highlights > Highlights Syntax Reference

Highlights Syntax Reference

Tip

The XML Schema for the highlights bundle is described in highlights.xsd.

Highlight Definition Types

The Bundle element accepts the following sub-elements:

  • Role (mandatory) allows grouping several highlight definitions for a particular role. This element has a mandatory name attribute where you can specify a role ID.

  • Filters (mandatory) allows grouping several highlight definitions for a particular artefact type. This element has a mandatory type attribute where you can specify an artefact type.

  • TopArtefacts is a type of highlight definition used to retrieve artefacts with the biggest value for a given measure.

  • TopDeltaArtefacts is a type of highlight definition used to retrieve artefacts with the biggest variation in the value of a given measure since an earlier version.

  • TopNewArtefacts is a type of highlight definition used retrieve artefacts that are new in the current version, sorted according to the value of a given measure.

Common Attributes

The common attributes for all highlight definitions types are as follows:

  • TopArtefacts allows the following attributes:

    • id (mandatory) is the id of the highlight definition.

    • name (deprecated) is unused.

    • artefactTypes (optional, default: any) defines the types of artefacts to filter on.

    • excludingTypes (optional, default: none) lists the artefact types for which the metric should not be displayed. This allows refining the types entered in the main filter above.

    • measureId (optional, default: the measureId associated with the root indicator) is the name of the measure Id to filter on.

    • order (optional, default: ASC) is the sort order for the list according to the reference measure ID. Valid values are ASC and DESC.

    • altMeasureId (optional, default: empty) is the second measure ID to use for sorting.

    • altOrder (required if altMeasureId is set, default: empty) is the sort order for the second measure ID. Valid values are ASC and DESC.

    • resultSize (mandatory) is the number of results to include in the list. Use 10 to display 10 artefacts or * to display all artefacts.

Output Customisation

All highlight definitions support the following nested elements, to customise the output:

  • Column is used to add a column to the list of artefacts returned by the highlight definition.

  • Where is used to specify extra filtering conditions for the artefacts to return.

  • OrderBy is used to specify sorting directives, in addition to the one already specified in the highlight definition.

Column

The Column allows the following attributes:

  • measureId or indicatorId or infoId (mandatory) is the ID of the measure, indicator or textual information to display

  • artefactTypes (optional, default: the parent value of artefactTypes ) lists the artefact types for which the metric should be displayed. This allows refining the types entered in the main filter above.

  • excludingTypes (optional, default: the parent value of excludingTypes ) lists the artefact types for which the metric should not be displayed. This allows refining the types entered in the main filter above.

  • headerDisplayType (optional, default: NAME) is the label to display in the header. The supported values are:

    • NAME for the metric's name

    • MNEMONIC for the metric's mnemonic

  • displayType (optional, default: VALUE) sets the value display type. The supported values are:

    • VALUE for the metric's numeric value

    • RANK for the indicator's rank

    • ICON for the indicator's rank icon

    • NAME for the indicator level's name

    • MNEMONIC for the indicator level's mnemonic

    • DATE for the metric's value, displayed as a UTC date

    • DATETIME for the metric's value, displayed as a UTC date and time

    • TIME for the metric's value, displayed as a UTC time

    For DATE, DATETIME and TIME, you can specify the required format using the dateStyle, timeStyle and datePattern attributes described below.

  • decimals (optional, default: 2) sets the number of decimals, used when the displayType is VALUE.

  • dateStyle (optional, default: DEFAULT): the date formatting style, used when the displayType is one of DATE or DATETIME.

    • SHORT is completely numeric, such as 12.13.52 or 3:30pm.
    • MEDIUM is longer, such as Jan 12, 1952.
    • DEFAULT is MEDIUM.
    • LONG is longer, such as January 12, 1952 or 3:30:32pm.
    • FULL is pretty completely specified, such as Tuesday, April 12, 1952 AD or 3:30:42pm PST.

  • timeStyle (optional, default: DEFAULT): the time formatting style, used when the displayType is one of DATETIME or TIME. See above for available styles.

  • datePattern (formerly dateFormat) (optional, default: empty): the date pattern, used when the displayType is one of DATE, DATETIME or TIME.

    • "yyyy.MM.dd G 'at' HH:mm:ss z" is "2001.07.04 AD at 12:08:56 PDT".
    • "EEE, d MMM yyyy HH:mm:ss Z" is "Wed, 4 Jul 2001 12:08:56 -0700".

    If this attribute is set, both dateStyle and timeStyle attributes are ignored. The date is formatted using the supplied pattern. Any format compatible with the Java Simple Date Format can be used. Refer to http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html for more information.

  • suffix (optional, default: empty) is the label displayed after the value of the metric in the UI

  • useBackgroundColor (optional, default: false) allows you to use the indicator level as the background colour of the cell. This is only valid when using a column with indicatorId . You can also control the transparency of the background colour with the attribute alpha (optional, default: 100) which accepts a value between 0 (transparent) and 255 (opaque).

Either measureId , infoId or indicatorId is required. Note that all display related tags, except headerDisplayType and displayType are ignored when infoId is used.

Where

The Where allows the following attributes:

  • measureId (mandatory) is the ID of the measure

  • infoId (optional) is the ID of the textual information

  • value (optional, default: empty) is the value of the measure

  • bounds (optional, default: empty) sets bounds values for the measure.

Either measureId or infoId is required.

Either value or bounds is required. Note that bounds is not supported if infoId .

OrderBy

OrderBy allows the following attributes:

  • measureId (mandatory) is the ID of the measure

  • order (mandatory) is the sort order for measure. Supported values are:

    • ASC for ascending

    • DESC for descending

Prev Up Next
Understanding Highlights Home | ToC Chapter 13. Building Tutorials
Squore 18.0.18
© 2019 Squoring Technologies All rights reserved. This material may not be reproduced, displayed, modified or distributed without the express prior written permission of the copyright holder. Squore is protected by an Interdeposit Certification registered with Agence pour la Protection des Programmes under the Inter Deposit Digital Number IDDN.FR.001.390035.001.S.P.2013.000.10600.