Calculation Macro

...

Section

title	Parameters
intro-text	The macro is configured by the following parameters.

Section

title	Doctype(s)

Transclusion

document	Display Table Macro
ids	Doctype(s)

Transclusion

taget-heading-level	*
document	Display Table Macro
ids	Space Keys

Transclusion

taget-heading-level	*
document	Display Table Macro
ids	Where

Section

title	Sort By

Transclusion

document	Sort By Property
ids	Sort By

Section

title	Identifier

Unique identifier of the rendered content.

projectdoc-transclusion-macro

taget-heading-level	*
document	Display Table Macro
ids	Exclude Self

projectdoc-section

title	Max Hit Count

If checked excludes this document from the query result.

Transclusion

taget-heading-level	*
document	Display Table Macro
ids	Restrict to immediate Children

Section

title	Render individual Results

If checked there is a data attribute added to the rendered element for each line result.

If not checked only the data attributes provided by default are added.

Data Attribute		Description
`data-projectdoc-result-count`	Provided by Default	The size of the result set. Note that the count of formulas may be smaller than this number if documents in that set do not provide all values required for the Document Formula.
`data-projectdoc-result-...-N`	Requires value of true	The infix for this attribute name (`...`) is derived from the name of the formula that created it. The 1-based index of the document that provided the values for it.
`data-projectdoc-finalresult-...`	Provided by Default	The final result of the formula with a derived name of the formula is used as a suffix.

If no Document Formula is specified, then no individual results will be calculated and therefore not added.

Section

title	CSS Classes

List of HTML class names to be added to the rendered HTML element.

Section

title	Render

Controls the rendering of the calculated value.

The following values for this parameter are valid.

Parameter Value Description

first The value calculated by the first formula is rendered (default).

none

Nothing is rendered as text, but the element with the data elements still is.

Choose this option if all calculated values are rendered at different locations down the document.

last

The value calculated by the last formula is rendered.

Choose this option if your formula requires the result of prior defined formulas

Transclusion

taget-heading-level	*
document	Display Table Macro
ids	Render no hits as blank

Section

title	No Result Text

Text to be rendered if no result is available. This overrides the default text.

Section Index

select	Name, Short Description, Data Type\|, Since\|
render-counter-column	true

Section Compiler by Reference

ref	Defined Parameters
render-classes	parameters-sections, section-compiler-by-reference, parameters
force-show	true
ids	-Description, Details
extract-short-desc	true

...

Section

title	Macro Body

The body contains the set of formula specifications to calculate values. Each specification of a formula contain a

Name,
the Format,
the Document Formula,
the Result Formula,
the Input Mapping, and
the Output Mapping.

The elements of the specification are provided in any order within the cells of a table.

Name

Format

Document Formula

Result Formula

Input Mapping

Output Mapping

...

Section

title	Name

Identifies the formula and the calculated result.

Section

title	Format

The format used to run the calculations of the formulas. The format is also used to translate the calculated value of the Document Formula and the input value to the Result Formula. Per default the format is also used to parse the input value for the Input Mapping and the output value of the Output Mapping, but only if the column is specified left of the mapping columns.

The format to parse the input value or to format the output value can be specified with the mapping columns (see below).

The value is a valid number format in Java and defaults to decimal.

Valid values are integer, decimal, currency, and anything that can be parsed by DecimalFormat.

Caution Box

title	Format applied to Formulas

Note that the format will be applied to the Document Formula (right column) and the Result Formula (left column) in case the Format column is specified left of them.

Section

title	Document Formula

The formula applied to calculate from each document in the result set.

Use placeholders, like ${Document_Propery_Name} to select values from the documents in the result set.

Example Box

title	Examples for Line Formula

Code Block

language	text
title	Calculating story points

${Story Points} * ${Story Weight}

Code Block

language	text
title	Add up the team sizes

${Team Size}

The Document Formula may also access the result of formulas specified in a line prior to this one. Also the results of formulas in Calculation Macros already processed can be accessed.

Example Box

title	Example to reference the Result of a previous Macro

The following example access the result value of a formula named a-formula-name within the Calculation Macro identified by my-macro-id.

Code Block

language	text

${my-macro-id.a-formula-name}

The following example shows the use of a reference with the Result Formula.

The following example shows the use of a reference with the Document Formula (the source table is unchanged from the previous example):

The formula name of the reference may be qualified as shown in Result Formula.

Section

title	Result Formula

The formula to be applied to the result of the Document Formulas.

The formula may contain placeholders to values of the document that contains the macro.

The formula may use the placeholders ${SUM}, ${PROD}, ${COUNT}, ${MIN}, and ${MAX}. Formulas may use values calculated by formulas defined in a line before it.

${LIT}

Placeholder	Description
The literal value of the result calculated by the Document Formula.	`${SUM}`	The sum of values calculated by the Document Formula.
`${PROD}`	The product of values calculated by the Document Formula.
`${MIN}`	The minimum value calculated by the Document Formula.
`${MAX}`	The maximum value calculated by the Document Formula.
`${COUNT}`	The count of documents that provided a value for the Document Formula. For instance if a document does not apply properties for all values of the Document Formula, it does neither contribute to the sum nor to the count.
`${`name-of-formula`}`	Where name-of-formula stands for the name of a formula that has been define above the formula that wants to use it. The value is referenced that is calculated after the output mapping.
`${`name-of-formula`_LIT}`	The literal value calculated by the formula named name-of-formula. Useful if the calculated value is rendered in an HTML element without value or if the output mapping maps the result values to an array of values. If there is no Output Mapping defined, then the values of `${`name-of-formula`}` and `${`name-of-formula`_LIT}` are identical.
`${`name-of-formula`_SUM}`	The sum value calculated by the formula named name-of-formula.
`${`name-of-formula`_PROD}`	The product value calculated by the formula named name-of-formula.
`${`name-of-formula`_MIN}`	The minimum value calculated by the Document Formula of name-of-formula.
`${`name-of-formula`_MAX}`	The maximum value calculated by the Document Formula of name-of-formula.
`${`name-of-formula`_COUNT}`	The count value calculated by the formula named name-of-formula.

Example Box

title	Examples for Aggregate Formula

Code Block

language	text
title	Use the sum

${SUM}

Code Block

language	text
title	Use the average

${SUM}/${COUNT}

Section

title	Input Mapping

A two-column table to map an input to be applied to a value read from the documents.

This allows to translate text to double values. The mapping is applied to the documents of the result set and the document that contains the macro.

The first column contains the value in its normalized rendered form. The second value is the numeric value to replace that rendered form.

Example Box

title	Example configuration for the Input Mapping

Input Mapping

Good	2
Great	4
Top Notch	8

Example Box

title	Example configuration for the Input Mapping with a specific Format

This is currently not used. We may allow in a future version to have ranges for the input mapping. In this case the value from the document will be parsed with the format specified here. Currently the input mapping is just matching the string value.

Input Mapping

percent

20%	0.2
40%	0.4
50%	0.5

Section

title	Output Mapping

A two-column table to map a double result value to a textual value, such as the Status Macro. The mapping is applied to the final result of the Result Formula.

The first column allows single numeric values and ranges of the format:

Code Block

language	text
title	Range format

D MIN ; MAX D

Token Description

D

The delimiter D may be either [ or ].

If [ is specified for
- the start value, then the start value is included.
- the end value, then the end value is excluded.
If ] is specified for
- the start value, then the start value is excluded.
- the end value, then the end value included.

MIN

The minimum value of the range.

If omitted, the minimum value of the range is the absolute minimum value. Any value smaller than MAX is accepted.

MAX

The maximum value of the range.

If omitted, the maximum value of the range is the absolute maximum value. Any value greater than MIN is accepted.

The defined mappings are processed from top to bottom. The first matching rule provided the representation.

Where one space is shown in the format above there may be any number of spaces, including zero spaces.

Example Box

title	Range examples

Code Block

language	text
title	Every value greater than or equal to 10 and smaller than or equal to 30 is accepted

[10;30]

Code Block

language	text
title	Any number smaller than or equal to 30 is accepted

[;30]

Code Block

language	text
title	The number must be exactly 30 - both representations are correct

30

[30;30]

Code Block

language	text
title	Every value greater than 10 is accepted

]10;]

Example Box

title	Example configuration for the Output Mapping

Output Mapping

[;10]

Status


colour	Grey
title	Good

]10;20]

Status


colour	Blue
title	Great

]20;]

Status

colour	Green
title	Top notch!

Example Box

title	Example configuration for the Output Mapping with specific Format

This example adds the placeholder for the Literal Value of the result. The value is referenced with the placeholder ${LIT}. The label has the suffix (${LIT}) in the following example.

Output Mapping

percent

[;10%]

Status


colour	Grey
title	Good (${LIT})

]10%;20%]

Status


colour	Blue
title	Great (${LIT})

]20%;]

Status


colour	Green
title	Top notch! (${LIT})

Caution Box

title	Uppercase Issue

The Status Macro is unfortunately altering the input label to upper case. Therefore only properties with uppercase names can be referenced with this macro.

...

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java

Incubator

Add-ons for Confluence

Tools

Support

Team

Legal

Versions Compared

Old Version 21

New Version 22

Key

About

Keep up-to-date!

Powered by