About Stamp Variants

Stamp template writers can specify named variants for a particular stamp type. When a DivePort administrator selects the stamp type in the stamp portlet edit dialog, if multiple variants are present in the template, the administrator can choose between the variants. There are two ways in which stamp rendering can be affected based on the variant chosen: stamp variables and visibility settings.

Each variant must have a name which is used to reference the variant in visibility settings throughout the stamp file, and accessed via the $(STAMP_VARIANT) macro. Optionally, the variant can have a label, which is used to display in the Variants pulldown on the stamp portlet edit dialog and also in the stamps list if the variant has self service enabled, and accessed via the $(STAMP_VARIANT_LABEL) macro.

If a property is a forced Boolean, it can be either a Boolean (True | False`) or a string. If it is a string, it can be a macro expression containing macros up to and including stamp-level macros. After any macro expression sare evaluated, the string is mapped to a Boolean as follows:

• "true" or "TRUE" (case insensitive) -> true

• "false" or "FALSE" (case insensitive) -> false

• "1" -> true

• "0" -> false

If the result of the macro evaluation is not one of the above, the property functions as if it were not set and might cause errors.

Examples:

Many properties can be conditionalized using an if= attribute. The value of the if= attribute must be a string that is forced to Boolean as described above. For example `property if=false` is identical to omitting the property, while `property if=true` is equivalent to `property`, so plain Booleans are unnecessary and not supported.)

Examples:

  options {
    dimension if="$(MACRO myBoolean)" 
    //where the macro myBoolean is set to true - a dimension is required in configuration.
    multivalue if="$(MACRO myNumber)" 
    //where the macro myNumber is set to 0, only one value is required in configuration.
    measure-categories                
    //the if attribute can be omitted, resulting in the value being true
  }

  always-include-zero if="$(MACRO myBoolean)"
  //where the macro myBoolean is set to false - the chart is not forced to include 0 in its numeric axis.
  always-include-zero if="bad value"         
  //because the mapping to boolean fails, the property is ignored - the chart includes 
  //zero or not according to the default for the specific type of chart.

Not all tags can be conditionalized using if=. The following tags can be:

for-self-service

within 'options':

dimension

multidimension

multivalue

no-value

measure-categories

pulldown-width (within quickview component)

popup (within portal-page click action)

width (column width for measures and matrix columns)

use-percent-comparison (within matrix comparison column)

within chart or measures components:

num-items

show-others

hide-nulls

within measures components:

show-totals

hide-odd-row-coloring

sort-by

sort-by-column

within chart components:

sort "up/down"

always-include-zero

navigable (within calendar-state)

within chart values:

show-median

show-mean

secondary-axis

Reusable, named values can be set within a stamp template. There are two locations where they can be set: the constants list and within a variant in the variants list. Variants do not need to be present in a stamp in order to use the constants list. Settings within a variant override those within the constants list with the same variable names.

constants {
  set "name-of-variable" "value-of-variable"
  set "numeric-variable-name" 3.1
  set "boolean-variable-name" false
}
variants {
  variant "boolean is actually true" {
    set "boolean-variable-name" true //overrides above
  }
}

Stamp variables can be accessed within the stamp template using the $(STAMP_VAR) macro. This macro takes two arguments: a variable name and a fallback value. For example, "$(STAMP_VAR numeric-variable-name)" evaluates to 3.1 based on the settings above. The fallback value, which defaults to an empty string if omitted, is only applied if the variable named is not set in the currently chosen variant. Here is an example:

variants {
  variant "one" {
    set "A" "false"
  }
  variant "two" {
    set "A" "bad value"
  }
  variant "three"
}
...
chart type="column" {
  always-include-zero if="$(STAMP_VAR A true)"
  ...
}

When the "one" variant is selected, the if attribute on always-include-zero evaluates to false, so the chart is not forced to include 0 in its numeric axis.

When the "two" variant is selected, the if attribute on always-include-zero fails to map to a Boolean value, and the chart includes zero or not according to the default for the specific type of chart.

When the "three" variant is selected, and no A variable is defined for that variant, the fallback value of true is used, and the chart is forced to include 0 in its numeric axis.

A best practice is to omit spaces and special characters from variable names, to avoid the need to escape quotes and other characters when putting the variable names into macro expressions.

Stamp variables can also be named directly in color lists:

colors {
  rgb 100 100 100
  stamp-variable "my-color"
  stamp-variable "my-color" "rgb(100, 100, 100)" 
  //a fallback is optional; works the same as the fallback argument in the STAMP_VAR macro call
}

 

Certain elements in a stamp template can be set to render or not render based on either stamp variables or the selected variant.

The following elements can have a visibility setting as a child tag:

• Components (chart, text, image, indicator, matrix, measures, and quickview)

• Click actions (analysis, crosslink, portal-page)

• Values (`value` tags) in chart components

• Non-primary dimensions in chart components (category, group, source, target)

• Columns in matrix components (group, end-group, measure-column, column)

• Columns in measures components (`column` tags)

• Dimensions in measures components (in the `dimensions` list—be sure to hide dimensions along with their corresponding columns.)

A visibility setting is one of the following:

• show if="$(MACRO EXPRESSION)"

• hide if="$(MACRO EXPRESSION)"

• show-for-variants "one" "or" "more" "variant" "names" "here"

• hide-for-variants "one" "or" "more" "variant" "names" "here"

Typically, the macro expressions on the show or hide tags would comprise a $(STAMP_VAR) macro (which will be a forced boolean) to make the visibility vary based on variant. The show-for-variants and hide-for-variants tags allow showing or hiding elements based purely on the name of the selected variant, rather than a stamp variable. The element will be shown for all variants not listed after hide-for-variants, or conversely hidden for all variants not listed after show-for-variants.

In the stamp grid layout, which is used on all self-service pages, the following options are available as stamp types:

• Stamp templates with no variants, but which include the for-self-service tag, where if conditionalized, the tag evaluates to true.

• Stamp templates with one or more variants, where the for-self-service tag is present and evaluates to true for just one of the variants.

• Stamp templates with the for-self-service tag present, with multiple variants for which the tag evaluates to true: each stamp variant for which the for-self-service tag evaluates to true will be displayed and will have its variant label (fallback: variant name) displayed beneath the stamp name (fallback: filename, minus extension).

(A for-self-service tag with no if= attribute always evaluates to true.)

In other words, all self-service-enabled stamp variants are shown, but the variant label is displayed only when it is needed to disambiguate multiple variants of the same stamp template.

There is a new macro $(IF <condition> <then> <else>).

If a property cannot be conditionalized using the if attribute, there might be other ways to unset it based on the variant.

• Date rollup: to turn off date rollup on a dimension, set the period to "d" and the span to "all".

• Style properties: a style property is not applied if either its property name or value evaluates to an empty string.

• For other properties, such as thresholds, use an empty string or "unset".

Create customized Macros in DivePort and reference them via $(MACRO myMacroName) (can even be the value of a stamp variable) to keep sizes, colors, and other attributes consistent between stamp types.

When a value is expected to be an integer or string (to allow macro expressions) or a Boolean or string (to allow macro expressions), Workbench does not enforce this type restriction. However, DivePort reports an error about the type of the value being wrong. For example,

num-items 5 //good

num-items "$(MACRO myNumber)" //good

num-items 1.5 //acceptable in Workbench, but DivePort reports an error for having a non-integer.

It is possible to create a macro loop, wherein a macro can never be resolved to a non-macro value. Avoid creating such loops by knowing the non-macro values to which your macro expressions resolve.

$(MEASURE_1), $(MEASURE_1_LABEL), and $(DIMENSION_1) cannot be used to conditionalize stamp options (multivalue, multidimension, etc.) or to conditionalize the for-self-service tag. They are disallowed because the Boolean values of these options are determined before measures and dimensions are chosen, so the names of measures and dimensions are not available at the time of macro evaluation.

$(MEASURE_1), $(MEASURE_1_LABEL), and $(DIMENSION_1) can be used in variant names, variable names, etc., but it is not recommended, as they are only evaluated in some cases (for example not in the stamp portlet configuration dialog) and thus can lead to unexpected results.

Be sure to use show-for-variants and hide-for-variants (with the plural s) even when listing only one variant. `show-for-variant "myVariant"` will not work.

To avoid mistakes outside of the variation system, dimension and multidimension cannot coexist within the options list. The same is true for no-value and multivalue. Therefore, a single stamp template cannot contain both a no value variant and a multivalue variant, and a single stamp template cannot contain a single-dimension variant and a multi-dimension variant. These options only determine the appearance of the configuration dialog. One could make a stamp render as if no values had been chosen, even if the multivalue option is activated.