Start page / Template development / Template syntax / Data types / Number

Number data type

Value range of the Number data type

The Number data type represents numbers. These include both integers as well as floating-point numbers, e.g. java.math.BigInteger, java.lang.Long, etc. With the help of numbers, in FirstSpirit 4.0 it is possible to formulate a large number of arithmetic expressions, e.g.

  • Addition
  • Subtraction
  • Multiplication
  • Division
  • Division with remainder (modulo)

For further information on this topic, see Arithmetic Expressions.

For further information on the Number data type, see Sun API documentation: java.lang.Number

Definition using the standard input components

Different input components can be defined in the form area of a page or section template. These form elements can then be used to insert the actual editorial contents into the page. The Standard input components supported by FirstSpirit return different data types.

The following standard input components return an object of data type Number:

Then, with the help of a $CMS_VALUE(...)$ instruction, methods can then be applied to this object:

$CMS_VALUE(IDENTIFIER.METHOD)$

Under IDENTIFIER, the resultname parameter, defined in the input component, must be specified.

Methods on Number objects

The table below lists all methods which can be invoked on objects of data type Number.

The object is generated by the following form objects:
CMS_INPUT_NUMBER
Method name Return type Brief description Available since
byteValue byte
compareTo(Number) int
compareTo(Object) int
div(BigInteger) BigDecimal
div(BigDecimal) BigDecimal
div(Number) BigDecimal
doubleValue double
equals(BigDecimal) boolean
equals(Number) boolean
equals(Object) boolean
floatValue float
format(String) String Formatting numbers
getClass Class Class of the invoking object
humanReadable(String) String Delivering file sizes (integer)
humanReadable(String, String) String Formatting file sizes
intValue int
isCase(BigDecimal) boolean
isCase(Number) boolean
isCase(Object) boolean
isNull boolean Checks whether an expression is null (zero)
longValue long
minus(BigInteger) BigDecimal
minus(BigDecimal) BigDecimal
minus(Double) BigDecimal
minus(Number) BigDecimal
modulo(BigInteger) BigInteger
modulo(Short) long
modulo(Long) long
modulo(Integer) long
modulo(Byte) long
mult(BigInteger) BigDecimal
mult(BigDecimal) BigDecimal
mult(Number) BigDecimal
plus(BigInteger) BigDecimal
plus(BigDecimal) BigDecimal
plus(Number) BigDecimal
print void
set(String, Object) Object
shortValue short
toJSON String Convert to a JSON-compatible string representation including necessary quotes and escaping for immediate use. Handles Maps, Collections, Arrays, Numbers, Strings, Boolean, Date, and JsonElement. A date instance will be converted to an ISO-8601 formatted date string. Any object other than above will be converted using its 'toString()' value. 5.2.11
toNumber Number
toString String
type String

byteValue

Method name Return type Available since
byteValue byte

compareTo(Number)

Method name Return type Available since
compareTo(Number) int

compareTo(Object)

Method name Return type Available since
compareTo(Object) int

div(BigInteger)

Method name Return type Available since
div(BigInteger) BigDecimal

div(BigDecimal)

Method name Return type Available since
div(BigDecimal) BigDecimal

div(Number)

Method name Return type Available since
div(Number) BigDecimal

doubleValue

Method name Return type Available since
doubleValue double

equals(BigDecimal)

Method name Return type Available since
equals(BigDecimal) boolean

equals(Number)

Method name Return type Available since
equals(Number) boolean

equals(Object)

Method name Return type Available since
equals(Object) boolean

floatValue

Method name Return type Available since
floatValue float

format(String)

Using the method format(String) numbers can be output with a specific format, defined by the template developer.

For this purpose, formatting patterns are used which are also used for the parameter format in the input component CMS_INPUT_NUMBER.

In addition to the options for formatting numbers in the input component CMS_INPUT_NUMBER, the method format(string) can be used to output numbers in other ways, too.

1) Outputting language-specific currency signs

The symbol ¤ (unicode: #00a4) can be used for this.

Example:

$CMS_VALUE(22.format("0 ¤").convert2)$

As the symbol ¤ is not contained in all character sets and it will possibly not be displayed correctly by the browser, the method .convert2() is used (see data type String). The output is (depending on the selected project language) for example 22 € for German or 22 £ for English.

The symbol ¤ can also be set twice, i.e. ¤¤ (unicode: #00a4#00a4). This will lead to the output of international currency signs (e.g. EUR for German or GBP for English).

2) Outputting per cent and per mille signs

The symbols % and are used for this purpose. The number will be multiplied by 100 when % is used, and multiplied with 1000 when is used.

$CMS_VALUE(0.22.format("0 %"))$

or

$CMS_VALUE(0.002.format("0 ‰").convert2)$

The output is 22 % or 2 ‰.

3) Outputting individual text

Individual text can be output, escaped by single inverted commas ':

$CMS_VALUE(123.format("0 'Yen'"))$

Output: 123 Yen

If one single inverted comma is to be output, '' (two inverted commas) must be set.

4) Different formatting for positive and negative figures

The semicolon ; can be used to define different formatting patterns for positive and negative numbers. The part on the left hand side of the semicolon defines the formatting pattern for positive, the part on the right hand side defines the formatting pattern for negative figures. The pattern must be identical for positive and negative figures. The formatting pattern may only vary in those symbols which are before or behind the figure, represented by null/s or symbol/s #. Otherwise the definition on the left hand side will be used for positive and negative figures.

Example:

$CMS_SET(result, 2 - 4)$
Case 1: $CMS_VALUE(result.format("#,##0.00;(#,##0.00)"))$
Case 2: $CMS_VALUE(result.format("0.00;-0.00 ¤").convert2)$

In this example the variable result has the value "-2", the output is thus (2.00) in the first case, -2.00 £ in the second case. If the variable had a positive value, e.g. "2", the output would be 2.00 in both cases.

Important For further information see java.text.DecimalFormat.

Using ChoiceFormat

Using ChoiceFormat a specific format can be applied to a set of numbers.

For this purpose $CMS_SET(...)$ can be used to define a list of pairs with keys and values. The key must be a number, the value contains the text. Key and value must be separated by "#", the key-value-pairs are separated by "|", for example:

$CMS_SET(myVariable, "1.0#Sun|2.0#Mon|3.0#Tue|4.0#Wed|5.0#Thur|6.0#Fri|7.0#Sat")$

This list can be output by using $CMS_FOR(...)$ and $CMS_VALUE(...)$ as well as "choice=", for example:

$CMS_FOR(i, [1..7])$
$CMS_VALUE(i + " -> " + i.format("choice=" + myVariable))$ <br>
$CMS_END_FOR$

The output looks like this:

1 -> Sun 
2 -> Mon
3 -> Tue
4 -> Wed
5 -> Thur
6 -> Fri
7 -> Sat

ChoiceFormat can be also used for language-specific outputs, for example:

Language DE: $CMS_VALUE(12.format("choice=1#Jan|2#Feb|3#Mrz|4#Apr|5#Mai|6#Jun|7#Jul|8#Aug|9#Sep|10#Okt|11#Nov|12#Dez"))$ <br>
Language EN: $CMS_VALUE(12.format("choice=1#Jan|2#Feb|3#Mar|4#Apr|5#May|6#Jun|7#Jul|8#Aug|9#Sep|10#Oct|11#Nov|12#Dec"))$

Output:

Language DE: Dez 
Language EN: Dec
Method name Return type Available since
format(String) String

getClass

The .getClass() (in Bean syntax: .class) method returns the class of the invoking object (cf. java.lang.Class).

Invocation:

$CMS_VALUE(myString.class)$
$CMS_VALUE(myString.getClass())$

Output:

java.lang.String
Method name Return type Available since
getClass Class

humanReadable(String)

Using the method humanReadable(String) file sizes, e.g. of media, can be output as integer in a special unit for improving readability. The use of this method is only reasonable in combination with the function ref(...) and the method size.

In comparison to the method humanReadable(String, String)(see below) using the method humanReadable(String) can only be used to define the unit of the file (i.e. comparable to the 1st string of the method humanReadable(String, String). The format given by the 2nd string of the method humanReadable(String, String)) is by default "0 {U}". Here, 0 is the wildcard for the integral file size and {U} ist the wildcard for the unit. For an example please see below.

You can decide if you want to deliver the unit of the file size in binary interpretation (in powers of 2) or decimal interpretation (in powers of 10) by using humanReadable(String) (cf. also IEC Norm 60027-2):

  • Binary representation:
    • 1 Kibibyte (KiB) equates to 210 Byte = 1024 Byte
    • 1 Mebibyte (KiB) equates to 220 Byte = 1.048.576 Byte
    • 1 Gibibyte (GiB) equates to 230 Byte = 1.073.741.824 Byte
    • ...
  • Decimal representation (SI prefixes):
    • 1 Kilobyte (kB) equates to 103 Byte = 1.000 Byte
    • 1 Megabyte (MB) equates to 106 Byte = 1.000.000 Byte
    • 1 Gigabyte (GB) equates to 109 Byte = 1.000.000.000 Byte
    • ...

For delivering the file size in binary representation the following values are available for the different units:

KiB, MiB, GiB, TiB, PiB, EiB, ZiB and YiB

In addition, ** can be used as wildcard to deliver the file size in the greatest possible unit.

For delivering the file size in decimal representation the following values are available for the different units:

kB, MB, GB, TB, PB, EB, ZB and YB

In addition, * can be used as wildcard to deliver the file size in the greatest possible unit.

Example:

$CMS_VALUE(ref(media:"REFERENCENAME").size.humanReadable("*"))$

The file size of the medium with the reference name REFERENCENAME will be output in this example in the greatest possible unit in decimal representation.

Completed by the default format string the equivalent as humanReadable(String, String) (see below) is:

$CMS_VALUE(ref(media:"REFERENCENAME").size.humanReadable("*", "0 {U}"))$

Decimals will be rounded up or down because only integers can be output by this method.
The size of a file with 2572.31 kB will be output for example as follows if the following units are specified:

  • if kb is specified as unit: "2572 kB"
  • if MB is specified as unit: "3 MB"
  • if GB is specified as unit: "0 GB"
  • if * is specified as unit: "3 MB"

Important If you do not want to deliver rounded file sizes please use the method humanReadable(String, String) (see below).
Method name Return type Available since
humanReadable(String) String

humanReadable(String, String)

Using the method humanReadable(String, String) you can output formatted file sizes, e.g. of media, to improve readability. The use of this method is only reasonable in combination with the function ref(...) and the method .size.

For using this method, a format must be defined in addition to a desired unit for file sizes, whereas first the unit and then the format must be given, separated by a comma.

1st string – Unit: For the unit you can choose if you want to output it in binary representation (in powers of 2) or in decimal representation (in powers of 10). You can use the same units as for the method humanReadable(String) (see above), including the wildcards * and **. Unlike in the case of humanReadable(String) the unit will not be output automatically. It must be defined in the second string:

2nd string – Format: For the format you can use the already known patterns for formatting numbers (see format parameter of CMS_INPUT_NUMBER). If less decimal places are defined than the file size actually has, the file size will be rounded up or down to the defined number of decimal places.
By default, only the file size will be output. If you want to output the unit you must specify it in addition to the format. Every text can be used for this and, depending on the use case, even units in binary and decimal representation can be combined.
Use the wildcard {U} to output the unit flexibly. It will be replaced by the unit specified in the first string. If in the first string * or ** are used, set {U} in the second string to make sure that the correct unit will be delivered automatically.

Examples:

1) Use this syntax to output the size of the medium with the reference name REFERENCENAME rounded to two decimal places in MB:

$CMS_VALUE(ref(media:"REFERENCENAME").size.humanReadable("MB","0.00 MB"))$

or

$CMS_VALUE(ref(media:"REFERENCENAME").size.humanReadable("MB","0.00 {U}"))$

2) Use this syntax to output the size of the medium with the reference name REFERENCENAME rounded to two decimal places in the greatest possible unit:

$CMS_VALUE(ref(media:"REFERENCENAME").size.humanReadable("*",".00 {U}"))$ 

3) Use this syntax to output the size of the medium with the reference name REFERENCENAME in KiB but with the unit "kB":

$CMS_VALUE(ref(media:"REFERENCENAME").size.humanReadable("KiB","0.0 kB"))$ 

The size of a file with 2572.31 kB will be output for example as follows if the following string combinations are used:

  • if ("kB","0 kB") is specified: "2572 kB"
  • if ("kB",",000 kB") is specified: "2.572 kB"
  • if ("*",".0000 {U}) is specified: "2,5723 MB"
  • if ("MB","0.0 MB") is specified: "2,6 MB"
  • if ("MB","0.00 MB") is specified: "2,57 MB"
  • if ("GB","0.0 GB") is specified: "0,00 GB"
  • if ("GB","0.00 GB") is specified: "0,003 GB"

Method name Return type Available since
humanReadable(String, String) String

intValue

Method name Return type Available since
intValue int

isCase(BigDecimal)

Method name Return type Available since
isCase(BigDecimal) boolean

isCase(Number)

Method name Return type Available since
isCase(Number) boolean

isCase(Object)

Method name Return type Available since
isCase(Object) boolean

isNull

The .isNull() (in Bean syntax: .isNull) method checks whether an expression or object is null , e.g. storeElement.isNull(). In the case of objects with complex values or objects, the object decides when it is null. The data type DomElement for example always contains an empty document, thus it is never null. For this reason, checking an empty DOM editor input component by using the method .isNull() returns the value false, whereas checking the component with .isEmpty() would return the value true.

The method .isNull() returns a Boolean value as the check result. true is the check result if the expression or object is null and false if not.

Method name Return type Available since
isNull boolean

longValue

Method name Return type Available since
longValue long

minus(BigInteger)

Method name Return type Available since
minus(BigInteger) BigDecimal

minus(BigDecimal)

Method name Return type Available since
minus(BigDecimal) BigDecimal

minus(Double)

Method name Return type Available since
minus(Double) BigDecimal

minus(Number)

Method name Return type Available since
minus(Number) BigDecimal

modulo(BigInteger)

Method name Return type Available since
modulo(BigInteger) BigInteger

modulo(Short)

Method name Return type Available since
modulo(Short) long

modulo(Long)

Method name Return type Available since
modulo(Long) long

modulo(Integer)

Method name Return type Available since
modulo(Integer) long

modulo(Byte)

Method name Return type Available since
modulo(Byte) long

mult(BigInteger)

Method name Return type Available since
mult(BigInteger) BigDecimal

mult(BigDecimal)

Method name Return type Available since
mult(BigDecimal) BigDecimal

mult(Number)

Method name Return type Available since
mult(Number) BigDecimal

plus(BigInteger)

Method name Return type Available since
plus(BigInteger) BigDecimal

plus(BigDecimal)

Method name Return type Available since
plus(BigDecimal) BigDecimal

plus(Number)

Method name Return type Available since
plus(Number) BigDecimal

print

Method name Return type Available since
print void

set(String, Object)

Method name Return type Available since
set(String, Object) Object

shortValue

Method name Return type Available since
shortValue short

toJSON

Convert to a JSON-compatible string representation including necessary quotes and escaping for immediate use. Handles Maps, Collections, Arrays, Numbers, Strings, Boolean, Date, and JsonElement. A date instance will be converted to an ISO-8601 formatted date string. Any object other than above will be converted using its 'toString()' value.
Method name Return type Available since
toJSON String 5.2.11

toNumber

Method name Return type Available since
toNumber Number

toString

Method name Return type Available since
toString String

type

Method name Return type Available since
type String

© 2005 - 2023 Crownpeak Technology GmbH | All rights reserved. | FirstSpirit 2023.12 | Data privacy