Data placeholder

From SpinetiX Support Wiki

Jump to: navigation, search

This page is related to Data feeds and data-driven widgets.

Description

Data placeholders are used to describe the mapping between the data retrieved from a data source and the layers composing the layout of a data-driven widget.

A data placeholder is a special notation having, in its simplest form, a double-pair of square brackets around the name of the field from where the data is taken - for instance [[title]], [[description]], [[enclosure]], [[pubDate]] etc.

When the data-driven widget is running, each instance of a data placeholder like [[title]] is dynamically replaced by the content existing in the "title" field (for example the title of an RSS feed item) retrieved from the data source.

Syntax

A data placeholder can be described using the following syntax:

[[field|locale>format?condition]]

where only the field element is required, the others being optional and introduced by a predefined separator. Each of the optional elements can be used only one time and the order must be respected. There are no spaces and everything is enclosed within a double-pair of square brackets.

More details about each syntax element:

  • field
    The column from where values are taken to replace this data placeholder. Make sure to enter the exact column name - when in doubt, check out the feed results within the "Feed Test" dialog; fields names are displayed as column headers.
    Starting with Elementi 2016, this can also be a formula or a literal, and can contain special characters. Spaces can be used with text layers, but not within media layers.
  • >format
    The dates, times, and numbers can be formatted according to the selected locale, by using the closing angle bracket sign (>), followed by a date/time format or a number format, depending on the filed type. Some examples: [[birthday>MEDIUM_DATE]], [[weight>#.##]] (formats the data as a number with two decimals), [[humidity>%]] (formats the data as a percentage), [[price|fr_FR>$]] (formats the data as a monetary value in euros).
  • ?condition
    Starting with Elementi 2016, the data placeholder can be displayed or not, depending on the result of a condition, introduced by the question mark sign (?). For example [[stock?stock>0]] displays the "stock" field only if it is positive.

New in Elementi 2016

Elementi 2016 introduces new syntax elements for data placeholder descriptor: field name escaping, formulas, conditions and literals. Also, the locale descriptor has been extended to allow changing the default calendar and / or the numeral system associated with the selected locale.

Also, starting with Elementi 2016, if the "format" element is missing, then there is an automatic formatting applied on fields that are natively numbers (>DECIMAL) or dates (>MEDIUM_DATETIME) - this could slightly change the behavior of existing projects, in the sense that the thousand separator might appear and the dates displayed in a different form than entered.


Here is an example of the new syntax usage:

[[date|fr_FR>dd-MM-yy?x>0]] formats the "date" field as a French date using a specific date pattern, but displays it only when the value of the corresponding "x" field is positive.

Field name escaping

The name of some fields might contain special characters that would cause the field's name to be misinterpreted when those special characters are not properly escaped. This includes the following characters: ] (closing square bracket), ' (single quote), " (double quote), = (equal sign), | (vertical bar), > (closing angle bracket), and ? (question mark).

To escape special characters in the field name, put a backslash sign (\) just before the special character. To include the backslash sign itself, simply put it twice (\\).

For example [[dad\'s car]] is now a valid reference to a field name.

Note Note:
Spaces can be used with text layers, but not within media layers.

Formulas

Instead of a field name, it is possible to specify a formula, introduced by the = sign, which can combine one or more of the data feed fields into a new number or string. For example, if the data feed has two fields named 'quantity' and 'price', the following formula displays the total price computed as quantity multiplied by price: [[=quantity*price]].

Formulas and format can be combined, so you can display the total price with two decimals using [[=quantity*price>#.##]].

The formulas must strictly obey the syntax of JavaScript expressions that yield a value, and have access to the full library of JavaScript mathematical functions and String functions. For example, if a data feed for right triangles has two fields "a" and "b" then [[=Math.sqrt(a*a+b*b)]] displays the hypotenuse using the Pythagorean theorem.

When using formulas, all the fields' names must start with a letter, underscore (_), or dollar sign ($). Subsequent characters can also be digits (0–9). If a field's name is not valid in JavaScript, for instance a reserved keyword like "function", then you must prefix it with the dollar sign ($) and replace any forbidden character with underscore (_).

In some advanced cases, they may be an ambiguity due to the fact that the | and > signs, that separate the formula part from the formatting part, can also appear inside JavaScript expressions - in such cases, the ambiguity must be resolved by putting the formula inside a pair of parentheses. For example: [[=(a>10?2*a:3*a)>#.##]] displays, with two decimals, the value of "a" field, multiplied by 2 or 3 depending on "a" value being greater than 10 or not - the first > sign is used as a comparison operator in the formula and the second > sign as the formula / format separator.

Fields that contain a decimal number in the form of a string as a result of the parsing process, are converted to a number before the formula is evaluated. To access a field as a string, you can prefix the field name with a $ (dollar sign). For example: [[=$price.substr(0,1)]] returns the first character of the "price" field, even if it could be interpreted as a decimal number. This is especially important when using the + (plus) operator. For example, if "a" field contains the value "1" and "b" field contains the value "2", then [[=a+b]] is evaluated as "3", while [[=$a+$b]] is evaluated as "12".

Conditions

The data placeholder can be displayed or not, depending on the result of a condition, introduced by the question mark sign (?). The conditional expression must be a JavaScript expression that yields a Boolean value; if it evaluates to true, the data placeholder is displayed, otherwise the placeholder is omitted. For example [[stock?stock>0]] displays the "stock" field only if it is positive.

The condition can be combined with other syntax elements, yet it must always be the last one to be used. Note also that the field(s) used in the condition can be different than the one being actually displayed - for example: [[price>#.##?stock>0]].

To access a field as a string, you can prefix the field name with a $ (dollar sign), just as with formulas. Also, if the field name is a reserved JavaScript keyword (e.g., case, class, default etc.), then it must be prefixed with a $.

Conditionals are most useful when used in a group of mutually exclusive conditions, for example: [[stock?stock>0]][['out of stock'?stock<=0]] displays either the "stock" field, if its value is positive, or the literal string "out of stock" otherwise.

Another useful application of the conditional part of data placeholders is to apply different text formatting, such as font color or style, based on some conditions. Do this by repeating the same placeholder, but with different conditional parts, and applying a different text format for each; only the placeholder matching the condition is displayed, whereas the non-matching ones are hidden. For example [[price?price>0]][[price?price<0]][[price?price==0]] displays the valued of "price" field either in red, green, or white, depending on its sign.

Literals

Because of the new possibilities offered by conditions, literal values have been introduced. A literal is simply the text to display at the location the placeholder instead of the name of a field. Literals are placed between pairs of matching quotes or double quotes. They only make sense in combination with a condition.
For example: [['up'?change>0]][['down'?change<0]] will display either 'up' or 'down' depending on the value of the 'change' field.

If the literal must contain quotes or double quotes, there are two possibilities:

  • Use the other type of quote to delimit the literal, for example: [["it's up"?change>0]] uses double quotes around the literal so that there is no ambiguity due to the presence of the single quote inside.
  • Double the quote to signify it is to be included literally and not a delimiting quote, for example: [['it''s up'?change>0]].

Locale extension

The locale descriptor can now contain two parts:

  • the usual locale representation as Unicode tag, which is a string composed of two or three parts: a language subtag and a region subtag, plus an optional script subtag - for example, en_US for US English (default locale), zh_Hans_CN for mainland China, and fr_CH for the French speaking part of Switzerland.
  • a second part introduced by -u, allowing to change the default calendar (with -u-ca) and / or the numeral system (with -u-nu) associated with the selected locale, in accordance with BCP47.

Some examples:

[[date|en_US-u-ca-buddhist-nu-jpan]] formats a date using the English US locale, using the Buddhist calendar and Japanese numerals.
[[created|-u-nu-roman>y]] formats the "created" date as a copyright text containing only the year written in Roman numerals.


Note Note: If the first part is missing, then the widget locale is used; if the second part is missing then the default calendar for the locale's region is used, respectively the default numeral system for the locale's language.


Calendars

The following calendars are supported:

  • -u-ca-gregorian
    This is the “proleptic Gregorian calendar”, the native date system in JavaScript and ISO8601, equivalent to the Gregorian calendar for all dates after its introduction on October 15th, 1582 and simply extending it for dates before that day, even though it was of course not in use.
    The following fields are defined:
    • ‘G’ (era) is either AD (Anno Domini/Common era) or BC (Before Christ/Before common era),
    • ‘y’ (year) is always > 0, so year zero is actually 1 BC (and it is a leap year…),
    • ‘u’ (extended year) is y for AD, -y + 1 for BC, so for year zero, u = 0,
    • ‘U’ is not defined,
    • ‘r’ (related Gregorian year) is of course equal to ‘u’.
  • -u-ca-buddhist
    This is the “Thai solar calendar” as used officially in Thailand. It is defined as a fixed offset of +543 years to the Gregorian calendar, thus the current year is 2559. It defines the following fields:
    • ‘G’ (era) is BE (Buddhist Era). The Thai solar calendar is never used for dates before 544 BC (year of the death of Gautama Buddha)
    • ‘y’ is the year in the Buddhist era (year 1 is 544 BC)
    • ‘u’ is defined as ‘r’ + 543
    All other fields are identical to the Gregorian calendar
  • -u-ca-chinese
    This is the “Chinese lunisolar calendar”. The same algorithms as in jSignage.Astronomy.js and the Sun and moon widgets are used for computing the position of the sun and the moon and uses the traditional 60-year cycle. It defines the following fields:
    • ‘G’ (era) is numeric, defined so that year 1 of era 1 is 2637 BC, then increments by one every 60 years
    • ‘y’ (year) is the year in the current cycle, from 1 to 60
    • ‘U’ (cyclic year name) is the name of the year in the current cycle
    • ‘u’ (extended year) is r + 2697, meaning extended year 0 is 2698 BC, start of the reign of the Yellow emperor
    • ‘M’ is the lunar month number starting at 1 at new year. There are 13 months during leap years, 12 during normal year. The leap month is indicated by suffixing its number with ‘b’ or its name with ‘bis’.
    • ‘d’ (day) is the number of days since the new moon starting at 1
    • ‘r’ is the Gregorian year for the date
  • -u-ca-coptic
    This is the “Coptic calendar” as used in Egypt and by Coptic churches. It defines the following fields:
    • ‘G’ (era) is AM (Anno Martyrum) or BAM (Before Anno Martyrum)
    • ‘y’(year) is based on the Diocletian era, so year 1 is 284 AD. Leap year are every 4 years without exception
    • ‘U’ is not defined
    • ‘u’ (extended year) is y for AM, -y + 1 for BAM
    • ‘M’ is the month from 1 to 13
    • ‘d’ is the day of the month. The first 12 months are 30 days each, the 13th month has either 5 or 6 days depending on leap year
    • ‘r’ is the Gregorian year for the date. Because the Coptic calendar drifts with regard to the Gregorian calendar in its handling of leap years there is no fixed offset
  • -u-ca-dangi
    This is the “Korean lunisolar calendar”. It is identical to the Chinese calendar with the exception that ‘u’ is r + 2332, meaning extended year 0 is 2333 BC, year of the foundation of the Gojoseon (ancient Korean kingdom). It has no relationship with the Juche or North Korean calendar.
  • -u-ca-ethiopic
    This is the “Ethiopian calendar” as used in Ethiopia. It is identical to the Coptic calendar for the day and month, but there is 276 year fixed offset due to the use of the Incarnation Era, where year 1 is 9 AD. ‘G’ is EE or BEE.
  • -u-ca-hebrew
    This is the “Hebrew lunisolar calendar”. It defines the following fields:
    • ‘G’ (era) is AM (Anno Mundi)
    • ‘y’ is based on the anno mundi era where year 1 is 3761 BC
    • ‘u’ is equal to ‘y’. The calendar is not used for dates before 1 AM
    • ‘U’ is not defined
    • ‘M’ is the month from 1 to 13. Regular year have 12 months, leap years have 13 months. New year begins with month #8 (Nisan). On leap years the additional month is #6 (Adar I, 30 days long). On regular years, there is no month #6.
    • ‘d’ is the day of the month, the number of days in each month is fixed to either 29 or 30 depending on the month. Because days start at sunset in the Hebrew calendar, there is some ambiguity when converting from Gregorian dates. We use the date at noon on the corresponding Gregorian day.
  • -u-ca-indian
    This is the “Indian national calendar”, the civil official calendar of India. It is not equivalent to any of the numerous traditional calendars also in use in India. It has a fixed offset of -78 years with regards to the Gregorian calendar due to use of the Saka era. ‘G’ is ‘Saka’. New year is on March 21th in the corresponding Gregorian calendar if it is a Gregorian leap year, on March 22nd otherwise.
  • -u-ca-islamic-civil and -u-ca-islamic-tbla
    These are “tabular Islamic calendars” using a simple calculation based on the observation that the average lunar year has 354 11/30 days. Thus it uses alternating months of 30 and 29 days, and adds an additional day at the end of the year to the last month (30 instead of 29) for 11 years of each 30-year cycle. The two versions differ only by the epoch (day 1) of the calendar, which is the date of Hijri, of either July 16th 622 AD for the ‘civil’ or July 15th 622 AD for the ‘tbla’ variant. Both variants have been used by Islamic astronomers since the middle age, but neither will exactly match observations of the moon, so there is a shift of +/- 1 day with observation based dates. To account for this the Islamic calendar widgets allows the user to introduce the observation offset manually.
    • ‘G’ (era) is AH (Anno Hegirae). The Islamic calendar is not used for dates before Hijri
    • ‘y’ is the lunar year. Because it is not a solar calendar, it shifts every year with regards to the Gregorian calendar
    • ‘M’ is the lunar month. There are always 12 months in a year.
    • ‘d’ is the day of the month. Odd months have 30 days, even months have 29 days, except month 12 on leap years which has 30 days
  • -u-ca-islamic-umalqura
    This is “Saudi Arabia's Umm al-Qura calendar” which uses the official Umm al-Qura precomputed table of lunation dates. The current version contains lunation dates for years in the range 1896 AD to 2124 AD. Fields are identical to the tabular calendars, but month durations do not follow a fixed cyclic pattern, being based instead on astronomical prediction of new moons.
  • -u-ca-japanese
    This is the “Japanese calendar” as currently used in Japan. It is an extension of the Gregorian calendar with the following fields:
    • ‘G’ (era) is the name of the emperor reigning at that date. By nature, the current version contains era data only for the current era, i.e. “Heisei” which started on Jan 8th 1989, plus historical data up to the Taika era (645 AD – 650 AD). The Japanese calendar is not used for dates prior to the Taika era.
    • ‘y’ (year) is the year since the start of the reign of the emperor, starting at 1
    All other fields, including ‘u’ (extended year) are identical to the Gregorian calendar.
  • -u-ca-persian
    This is the “Solar Hijri calendar” as used officially in Iran and Afghanistan. It is not identical to the ancient Persian calendar. The version used in the HMP is a predictive approximation of the observation based calendar, using a fixed 33-year cycle with 8 leap years. It defines the following fields:
    • ‘G’ (era) is AP (Hijri)
    • ‘y’ (year) is the solar year in the Hijri era, with fixed 622 year offset to the Gregorian year. The Persian new year day is the vernal equinox, usually on March 21st or March 20th in the Gregorian calendar
    • ‘M’ is the month. There are always 12 months in a year
    • ‘d’ is the day of the month. Months 1 to 6 are 31 days each, months 7 to 11 are 30 days each, month 12 is 29 days on regular years or 30 days on leap years
  • -u-ca-roc
    This is the “Minguo calendar” as used officially in Taiwan. It is defined as a fixed offset of -1911 years to the Gregorian calendar, thus the current year is 105. It defines the following fields:
    • ‘G’ (era) is either ‘Minguo’ starting 1912 AD or ‘Before R.O.C.’
    • ‘y’ is the year in the republican era. Year 1 is 1912 AD, year of founding of the Republic of China
    • ‘u’ is defined as ‘r’ – 1911
    All other fields are identical to the Gregorian calendar.


Numeral systems

The following numeral systems are supported:

  • All decimal systems in the CLDR database using the BCP47 code.
  • -u-nu-roman
    Roman numerals using upper case, in the most common IV variant (the other one being IIII). For example, 2016 => MMXVI. Only valid for integers in the range [0, 9999].
  • -u-nu-romanlow
    Same as -u-nu-roman but with lower case. For example 2016 = mmxvi. Only valid for integers in the range [0, 9999].
  • -u-nu-grek
    Greek numerals using upper case. For example 2016 = ͵ΒΙΣΤʹ. Only valid for integers in the range [1, 9999].
  • -u-nu-greklow
    Same as -u-nu-grek but with lower case. For example 2016 = ͵βιϛʹ. Only valid for integers in the range [1, 9999].
  • -u-nu-hebr
    Hebrew numerals. For example 2016 = בט״ז. Only valid for strictly positive integers. Due to the way javascript handles numbers as double precision floating point, there is a practical limit to 2^53-1 (~9e15) for the largest integer that can be represented.
  • -u-nu-hans
    Chinese spell-out numerals, using simplified Chinese characters. For example 2016 = 二千零一十六. Only valid for numbers in the range [-1e18+1,1e18-1], but otherwise fractional and negative numbers are allowed. This is not the decimal system using the same characters, for which the code is -u-nu-hanidec
  • -u-nu-hansfin
    A variant of -u-nu-hans used for accounting because it is much harder to modify the numbers by adding a stroke. For example 2016 = 贰仟零壹拾陆
  • -u-nu-hanidays
    A variant of -u-nu-hans using dedicated characters for 20, 30 and 40. Usage is typically for day of the month in dates. For example: 25 = 廿五. Only valid for integers in the range [1, 49].
  • -u-nu-hantfin
    A variant of -u-nu-hant used for accounting. For example 2016 = 貳仟零壹拾陸.
  • -u-nu-jpan
    Japanese spell-out numerals. For example 2016 = 二千十六.Only valid for numbers in the range [-1e18+1,1e18-1], but otherwise fractional and negative numbers are allowed.
  • -u-nu-jpanfin
    A variant of -u-nu-jpan used for accounting. For example 2016 = 弐千拾六.
Retrieved from "https://support.spinetix.com/w/index.php?title=Data_placeholder&oldid=17461"
This page was last modified on 28 June 2021, at 11:38.