Template strings

Template strings are simple templating functions for creating generating value of properties. Format is {function:arg1,arg2,...}

Function arguments are dividing by comma

Templating of special characters and security

Since Dynamic App version 7.7.8 and 8.1.2 the approach to escaping user input HTML content has changed. This was necessary due to a security precautions against of Cross Site Scripting attack.

It is important, that implementator should always know how to configure user inputs in a secure way, especially when using templating values. The user of the application should never have a possibility to write HTML code in some attribute to display his own content. All such attempts will be now on automatically escaped as HTML entities.

This change in the default Dynamic App behavior leads to necessary manual updates in the configuration. Now it is necessary to use special template string functions on such places, where an implementator knows he can afford to use some special chars or strings. This is usually a case of templating href attributes, using ‘&’ in section titles, or markdown contents.

New template string function:

• {char:arg} This function ensures correct display of given special character (<, >, &, ”, ’) in case of using them directly in the configuration property. If the special characters are used in resources, {tr:} or {trCFL:} functions take care about them. There is no need to use {char:} function there. Example: {char:&}

Testing

Each implementation module has function templating which can be invoked from developer console in browser. Navigate to element in DOM element panel and in console write $0.templating(TESTING_TEMPLATED_STRING) e.g. $0.templating('{tr:badLoginPassword}').

The dataContext is automatically taken from module when using the templating function but implementator can also specify it. $0.templating(TESTING_TEMPLATED_STRING, DATA_CONTEXT).

Also in debug mode it is available the template string calculator for instant testing of template strings. You can find it at the bottom of debugger dialog.

Functions

Available functions that can be used in templated strings:

get

{get:arg1}

• returns value of datacontext
• arg1: it should start with #, hashtag represents dataContext object(e.g. entity). Then path to property. Property should be primitive type (e.g. description column of codelist attribute)
• examples:
  • {get:#at_base_samo_object__c_state.c_state__description} {get:#at_base_defect__name}
  • {get:#type} returns featuretype id - FTID (e.g. ft_mntMaintenanceNorm)
  • {get:#id} returns feature id - FID (e.g. 200039)
  • {get:#FullId} returns FTID/FID (e.g. ft_mntMaintenanceNorm/200039)
  • {get:#at_mntMntWork__mntNorm_sid.sid} used with featureRefAttributes, returns related feature's SID (e.g. 200039)

getDate

{getDate:getArg, formatArg}

• returns date type datacontext property in specified date format
• getArg: it should start with #, hashtag represents dataContext object(e.g. entity). Then path to property. Property should be primitive type (e.g. Description column of codelist attribute)
• formatArg: date format (see more at https://momentjs.com/docs/#/parsing/string-format/), default is L
• example: {getDate:#at_base_defect__detection_date,DD.MM.YYYY HH:mm:ss}

getDateRange

{getDateRange:from,to,delimiter,format}

• returns date range in specified format with delimiter. Returns empty string when the range does not have both boundries.
• from: it should start with #, hashtag represents dataContext object(e.g. entity). Then path to property. Property should be primitive type (e.g. Description column of codelist attribute)
• to: it should start with #, hashtag represents dataContext object(e.g. entity). Then path to property. Property should be primitive type (e.g. Description column of codelist attribute)
• delimiter: (optional) delimiter for the range - default is ' - '
• format: (optional) date format (see more at https://momentjs.com/docs/#/parsing/string-format/), default is L
• example: {getDateRange:#plannedDateStart,#plannedDateEnd, - ,DD.MM.YYYY HH:mm:ss}

getFirst

{getFirst:arg1,arg2,arg3,...}

• returns first non empty argument. Each argument is evaluated the same way as {get:}.
• example: {getFirst:{getDate:#dueDate},{getDateRange:#plannedDateStart,#plannedDateEnd, - }}

getCountOrFirst

{getCountOrFirst:arg1,arg2,arg3,...}

• returns first non empty argument or returns count of not empty ones.
• example: {getCountOrFirst:{iconFlag:{get:#isWater},water},{iconFlag:{get:#isGas},gas}}

lsGet

{lsGet:key,mode,path}

• returns value of path property in datacontext stored in key property in browser local storage. If mode is set to json, the value will be parsed as JSON.
• example: {lsGet:globalFilter,json,organizationUnit.id}

now

{now:formatArg}

• returns current moment in defined format
• formatArg: date format (see more at https://momentjs.com/docs/#/parsing/string-format/), default is timestamp (x)
• examples:
  • {now:}, {now:x} returns current timestamp
  • {now:L} returns date (in local format) (e.g. "24.12.2018")
  • {now:MMMM} returns month (in local format) (e.g. "December")

today

{today:}

• returns timestamp of current day with removed time
• example: {today:}

prettyTime

{prettyTime:arg}

• returns pretty print time in format '1d 1h 1m'
• example: {prettyTime:#expectedDuration}

user

{user:arg1}

• returns property of user object of logged in user.
• arg1: it should start with #, hashtag represents user object. Then path to property. Property should be primitive type (e.g. Description column of codelist attribute)
• example:
  • {user:#id} returns user ID
  • {user:#login} returns user's username
  • {user:#firstName} returns user's first Name
  • {user:#lastName} returns user's last Name
  • {user:#email} returns user's email
  • {user:#street} {user:#streetNumber}, {user:#city} {user:#zip} returns user's adress (can be also used separately)

hasAnyApplicationRole

{hasAnyApplicationRole:arg1, ...}

• returns true/false if user has at least one of given application roles.
• arg1: name of the application role in format APPLICATION_NAME.ROLE_NAME
• example:
  • {hasAnyApplicationRole:SAMO.USER,SAMO.OPERATOR} returns true/false

hasAllApplicationRoles

{hasAllApplicationRoles:arg1, ...}

• returns true/false if user has all of the given application roles.
• arg1: name of the application role in format APPLICATION_NAME.ROLE_NAME
• example:
  • {hasAllApplicationRoles:SAMO.USER,SAMO.OPERATOR} returns true/false

tr

{tr:resourceIdArg, varArg1, varArg2, ...}

• returns localizes string with possibility of filling variables from datacontextvrati lokalizovany string s moznostou dosadzovania premennych z dataContextu
• resourceIdArg: resource identification (object notifiction)
• varArgs: list of datacontext variables, they should start with #, hashtag represents dataContext object(e.g. entity). Then path to property. Property should be primitive type (e.g. description column of codelist attribute)

trCFL

{trCFL:resourceIdArg, varArg1, varArg2, ...}

• returns the same result as {tr:} function but the first letter is capitalized.

lang

{lang:}

• returns current language identification, e. g. en.
• example: {lang:}

urlArg

{urlArg:arg1}

• returns value of url argument with id arg1
• example: {urlArg:entityId}

serviceUrl

{serviceUrl:serviceGroup,service,actionID}

• returns whole service url
• serviceGroup: service group
• service: service name
• actionID: action name
• waitOnIndex: (optional) true if action should wait for business server to index before sending a response
• example:
  • {serviceUrl:cuzk,nahlizeniDoKN,vratLink}
  • {serviceUrl:ap_group,ft_request,createReqAndApplicant,true}

proxyUrl

{proxyUrl:path}

• returns whole proxy url
• path: path starting with proxy name
• example: {proxyUrl:/features/ft_SOME_TYPE/FT_SOME_ID}

resourceUrl

{resourceUrl:path}

• returns URL path to given resource file
• path: path starting in resources folder
• example: {resourceUrl:icons/files/txt.svg}

isEntityInStates

{isEntityInStates:stateArg1, stateArg2,...}

• returns true or false, if dataContexts represents bussines entity in specified states
• stateArgs: list of true values states

entityTitle

{entityTitle:}

• if datacontext represents entity, it returns templated 'titleString' metadata property

entitySubTitle

{entitySubTitle:}

• if datacontext represents entity, it returns templated 'subTitleString' metadata property

entityDescription

{entityDescription:}

• if datacontext represents entity, it returns templated 'descriptionString' metadata property

entityType

{entityType:#type}

• if datacontext represents entity, it returns 'title' metadata property or LIDS entity name

entityColor

{entityColor:}

• returns entity color according to entity metadata (coloring object) of entity type
• can be used only in entity modules (e. g. samo-entity-properties-detail)
• example: {entityColor:}

entityIcon

{entityIcon:}

• if datacontext represents entity, it returns 'mainIcon' metadata property

entityMapIcon

{entityMapIcon:}

• if datacontext represents entity, it returns 'mapIcon' metadata property

label

{label:labelColor, templatedContent [, iconId, iconTooltip [, iconPrefix]]}

• returns value of templatedContent with injected icon and background styled according to color
• labelColor: color for label background, can be set via hex value (# is optional), or rgba value (values splitted by ;). Text color will be computed automatically (black or white) if the color is defined by hex value or rgba value
• templatedContent: template string with content of label
• iconId: (optional) icon ID to display specific icon element at the label beginning
• iconTooltip: (optional) icon tooltip (simple or templated string)
• iconPrefix: (optional) iconset ID, default 'samo-icons'
• examples:
  • {label:red,NEW}
  • {label:#ff0000,{get:#at_boProject__name},check,{tr:checked},samo-icons-navigation}
  • {label:rgb(255;0;0),{icon:close}{get:#at_boProject__name},check,{tr:checked},samo-icons-navigation}
  • {label:{entityColor:},{get:#at_boSamo__c_state_public.ca_state_public__description}}

labelFlag

{labelFlag:condition, labelColor, templatedContent [, iconId, iconTooltip [, iconPrefix]]}

• returns label only if condition is logical true or has value
• condition: expression for icon display
• labelColor: color for label background, can be set via hex value (# is optional), or rgba value (values splitted by ;). Text color will be computed automatically (black or white) if the color is defined by hex value or rgba value
• templatedContent: template string with content of label, if templatedContent returns null then nothing to display
• iconId: (optional) icon ID to display specific icon element at the label beginning
• iconTooltip: (optional) icon tooltip (simple or templated string)
• iconPrefix: (optional) iconset ID, default 'samo-icons'
• examples:
  • {labelFlag:{notEmpty:#at_boProject__name},rgb(255;0;0),{icon:check,{tr:checked},samo-icons-navigation}{get:#at_boProject__name},check,{tr:checked},samo-icons-navigation}
  • {labelFlag:{notEmpty:#at_boSamo__c_state_public},{entityColor:},{get:#at_boSamo__c_state_public.ca_state_public__description}}

icon

{icon:iconId, iconTooltip [, iconPrefix]}

• returns icon
• iconId: icon ID
• iconTooltip: icon tooltip (simple or templated string)
• iconPrefix: (optional) iconset ID, default 'samo-icons'
• example: {icon:check,{tr:checked},samo-icons-navigation}

iconFlag

{iconFlag:condition, iconId, iconTooltip [, iconPrefix]}

• returns icon only if condition is logical true or has value
• condition: expression for icon display
• iconId: icon ID
• iconTooltip: icon tooltip (simple or templated string)
• iconPrefix: (optional) iconset ID, default 'samo-icons'
• examples:
  • {iconFlag:{get:#attachmentsCount},attachment,{tr:hasAttachments},samo-icons-file}
  • {iconFlag:{isGreaterOrEqual:#at_boProject__year,2019},star,{tr:createdIn2019AndLater}}

array

{array:arg1,arg2,arg3,...}

• creates array from arguments. This methods filters empty values (null/undefined/"").
• exmaple: {array:#at_fr1,#at_fr2}

mapArray

{mapArray:array,prop1,prop2,...}

• creates new array from given array of objects with specific properties only. When more than one property is given the method returns array of objects.
• array - array of objects
• prop1 - property that should be mapped out from the array
• prop2 - (optional) another property to map
• propX - (optional) another property to map ...
• exmaple: {mapArray:#entities,sid} - creates array of sids from array of entities

join

{join:arrayArg,joinDividerArg}

• returns all values of array divided by specified divider.
• arrayArg: array in datacontext. it should start with #, hashtag represents dataContext object (e.g. entity). Then path to property. Property should be primitive type (e.g. description column of codelist attribute)
• joinDividerArg: (optional) divider string - default is ,
• exmaple: {join:#ids, } (note: divider is space ' ')

split

{split:stringArg,delimiter}

• returns array of strings divided by delimiter.
• stringArg: string with delimiters or another template string
• delimiter: (optional) delimiter string - default is ,
• exmaples:
  • {split:#att_stringWithDelimiters} (note: delimiter is ,)
  • {split:#att_stringWithDelimiters,|}

length

{length:arg}

• returns length of string or array.

indexOf

{indexOf:arg,character}

• returns the first index at which a given character can be found in the string, or -1 if it is not present
• examples:
  • at_string="my_code"
  • {indexOf:#at_string,c} - returns 3 (m is on 0 index)

subString

{subString:arg,start,end}

• returns the part of the string between the start and end indexes
• examples:
  • at_string="my_code"
  • {subString:#at_string,{indexOf:#at_string,c},5} - returns co
  • {subString:#at_string,{indexOf:#at_string,c}} - returns code
  • {subString:#at_string,{indexOf:#at_string,W},5} - returns my_co
  • {subString:#at_string,3,5} - returns co
  • {subString:#at_string,3} - returns code
  • {subString:#at_string,0,3} - returns my_co
  • {subString:#at_string,-1,3} - returns my_co

getLinkElement

{getLinkElement:hrefArg, textArg, targetArg}

• generates link from specified parameters
• hrefArg: address
• textArg: text of link
• targetArg: name of window where address will be opened, blank or _blank refers to New Tab in browser
• example: {getLinkElement:{get:#at_boProject__elakUrl},{get:#at_boProject__elakUrl},blank}

isEqual

{isEqual:arg1, arg2}

• returns true if arguments are equal
• arg1: path in dataContext starting with # character or another template string
• arg2: value to compare or another template string
• exmaples:
  • {isEqual:#at_boProject__year,} (comparing to empty (null or undefined) value)
  • {isEqual:{get:#at_boProject__year},1990}
  • {isEqual:#at_boProject__year,{getDate:#createDate,YYYY}}

isNotEqual

{isNotEqual:arg1, arg2}

• returns true if arguments are not equal
• arg1: path in dataContext starting with # character or another template string
• arg2: value to compare or another template string

isGreater

{isGreater:arg1, arg2}

• returns true if arg1 is greater then arg2
• arg1: path in dataContext starting with # character or another template string
• arg2: value to compare or another template string

isGreaterOrEqual

{isGreaterOrEqual:arg1, arg2}

• returns true if arg1 is greater or equal then arg2
• arg1: path in dataContext starting with # character or another template string
• arg2: value to compare or another template string

isLess

{isLess:arg1, arg2}

• returns true if arg1 is less then arg2
• arg1: path in dataContext starting with # character or another template string
• arg2: value to compare or another template string

isLessOrEqual

{isLessOrEqual:arg1, arg2}

• returns true if arg1 is less or equal then arg2
• arg1: path in dataContext starting with # character or another template string
• arg2: value to compare or another template string

and

{and:arg1, arg2}

• returns true if both arguments return true
• example: {and:{isLessOrEqual:#at_base_samo_object__description,4},{isGreaterOrEqual:#at_base_samo_object__description,2}}

not

{not:arg1}

• returns negation of argument

empty

{empty:arg1}

• returns true if given argument is null/undefined/or has zero length

notEmpty

{notEmpty:arg1}

• returns true if given argument is not null/undefined/or has zero length

or

{or:arg1, arg2}

• returns true if one of arguments return true

progress

{progress:arg1}

• creates progress bar widget. The arg1 is templated string and must be between 0 and 100 (included).

randomNumber

{randomNumber:[arg1[, arg2]]}

• returns pseudorandom integer between arg1 (default 0) and arg2 (default 100). Recommended only for testing purposes.

calculate

{calculate:arg}

• returns arg as evaluated mathematical expression. the argument must match special regexp to ensure that the input is correct mathematical expression.
• example: {calculate:{get:#at_length}*{get:#at_count}}

formatNumber

{formatNumber:arg}

• returns arg as formatted number by current language
• examples:
  • {formatNumber:83943839439}
  • {formatNumber:#created}
  • {formatNumber:{get:#at_length}}

toFixed

{toFixed:arg,precision}

• returns rounded number using precision for fixed-point notation. Precision is set to 0 by default
• examples:
  • {toFixed:#at_number} - returns an integer
  • {toFixed:#at_number,2} - returns a number with 2 decimal places

sessionStorage

{sessionStorage:key}

• returns normalized value of sessionStorage item with 'key'.
• example: {sessionStorage:someStorageKey}

dateAdd

{dateAdd:date,value,key}

• returns date with added time
• 'key' options:

  Key	Shorthand
  years	y
  quarters	Q
  months	M
  weeks	w
  days	d
  hours	h
  minutes	m
  seconds	s
  milliseconds	ms

• example: {dateAdd:#at_date,2,weeks}
• example: {dateAdd:#at_date,10} - days are default

dateDiff

{dateDiff:firstDate,secondDate [,key,absoluteNumber]}

• returns number that is difference between the first date and the second date using the key as unit of measurement. If absoluteNumber is set to true, then returned number is absolute. Key is 'days' by default and absoluteNumber is false by default. Note that if you want to return absolute number, you must specify the key!
• 'key' options:

  Key	Shorthand
  years	y
  months	M
  weeks	w
  days	d
  hours	h
  minutes	m
  seconds	s
  milliseconds	ms

• example: {dateDiff:#at_dateStart,{today:}}
• example: {dateDiff:#at_dateStart,#at_dateEnd}
• example: {dateDiff:#at_dateStart,#at_dateEnd,years}
• example: {dateDiff:#at_dateStart,#at_dateEnd,days,true}

dateSubtract

{dateSubtract:date,value,key}

• returns date with subtracted time
• 'key' options:

  Key	Shorthand
  years	y
  quarters	Q
  months	M
  weeks	w
  days	d
  hours	h
  minutes	m
  seconds	s
  milliseconds	ms

• example: {dateSubtract:#at_date,2,weeks}
• example: {dateSubtract:#at_date,10} - days are default

dateStartOf

{dateStartOf:date,key}

• returns first date of 'key' value.
• 'key' options:

  Key	Explanation
  year	set to January 1st with time 00:00:00 from 'date' value
  month	set to the 1st day 00:00:00 of the month from 'date'
  quarter	set to the beginning of the 'date' quarter - 1st day of months, 00:00:00
  week	set to the 1st day 00:00:00 of the week from 'date'
  isoWeek	set to the 1st day 00:00:00 of the week from 'date' according to ISO 8601
  day	set to 00:00:00 for 'date'
  date	set to 00:00:00 for 'date'
  hour	set whole hour from 'date' with 0 mins, 0 secs and 0 ms
  minute	set whole hour with minutes from 'date' with 0 secs and 0 ms

• example: {dateStartOf:#at_date,year} returns 01/01/YYYY 00:00:00 where YYYY is year from 'date'
• example: {dateStartOf:#at_date} - day is default

dateEndOf

{dateEndOf:date,key}

• returns last date of the 'key' value.
• 'key' options:

  Key	Explanation
  year	set to the last day of the year from 'date' with time 23:59:59
  month	set to the last day of the month from 'date' with time 23:59:59
  quarter	set to the end of the date quarter - last day of months, 23:59:59
  week	set to the last day of the week from 'date'
  isoWeek	set to the last day of the week from 'date' according to ISO 8601
  day	set to 23:59:59 for 'date'
  date	set to 23:59:59 for 'date'
  hour	set whole hour from 'date' with 59 mins, 59 secs
  minute	set whole hour with minutes from 'date' with 59 secs

• example: {dateEndOf:#at_date,year} - returns 31/12/YYYY 23:59:59 where YYYY is year from 'date'
• example: {dateEndOf:#at_date} - day is default

if

{if:condition,then,else}

• this functions represents basic if statement, it returns value from then or else according to condition

  Key	Explanation
  condition	expression for if statement (templateString)
  then	string or templateString
  else	string or templateString

• example: {if:{empty:#at_entityDesc},yes,no} - if attribute is empty, return 'yes' value
• example: {if:{isEqual:#at_someId,1234},yes,no} - if attribute is equal to '1234', return 'yes' value
• example: {if:{isNotEqual:#at_someId,1234},{get:#at_mainDesc},{get:#at_secondaryDesc}} - if attribute is not equal to '1234', return attribute value

char

{char:arg}

• returns defined character in case of usage special characters (<, >, &, ”, ’) in strings. Without using this function the character would be escaped as HTML entity. Use this function when special characters are not defined in resources and are directly used in configuration properties (for example 'title' property or 'href' property where '&' can be used, etc.)
• example: {char:&} - returns '&'

lowerCase

{lowerCase:arg}

• returns argument in lower case
• example: {lowerCase:TOLOWERCASE} - returns 'tolowercase'
• example: {lowerCase:#at_attributeWithVariousText} - returns 'varioustext'

upperCase

{upperCase:arg}

• returns argument in upper case
• example: {upperCase:touppercase} - returns 'TOUPPERCASE'
• example: {upperCase:{get:#at_attributeWithVariousText}} - returns 'VARIOUSTEXT'

version

{version:}

• returns current version of Dynamic App