Promotic
WikipediaLinkedInYoutubeTwitterFacebook

Macro expression $.text

This macro expression represents the string read from a text file. The text file is in XML format, in UTF-8 character encoding and it is possible to store multiple texts in it. Each text can be entered in differnt nation language. With this macro it is possible to easily create an application that can be switched into other languages while running (See also: How to create an application using different national languages). The macro is useful also in case of a single language application, if the texts of the application are located in one (or more) file(s).

This macro expression loads the selected text from the file accordig to its identifier and than according to the language:

- In local application: the language of the text is choosen according to the current setting of the Pm.RtLang property (according to the specified Main language of runtime configurator).
- For Web clients: the language of the Web component is choosen according to the language defined in the configurator PmWeb > Web > Default language. If the Web component is registered to PmWebLang object, then the language is choosen according to the selected Web URL address.
 
The $.text macro expression can be used, for example, for setting the configurators PmiButton > Button > Text PmPanel > Panel > Panel title and many others.
 
Syntax:

$.text("idFile","idText")

- idFile = the type of the XML file
- idText = user identifier of the text in this file

Obsolete syntax of macro expression: $text:idFile.idText

 
The type of the XML file can be:
$.text("sys","idText") - system file text_sys.xml placed in the PROMOTIC folder (e.g. c:/pm/text_sys.xml). This file is supplied together with the PROMOTIC system and some general texts can be found in it. It can also be used as an example of creating user texts (but don't put your own texts into this file).

Note: There is another file by text_sys.xml named text_rt0.xml, containing more system texts. Do not use this file as a text source, because the texts located here are a subject of change (it is not guaranteed, that the new PROMOTIC versions will contain these texts)

 
$.text("app","idText") - user file text_app.xml is placed in Your application folder (e.g. d:/PmProj/Application/text_app.xml).
 
$.text("appXX","idText") - user file, for example text_appL1.xml (if XX=L1). It is only a generalization of the previous type in order to have the possibility to place more user files in the application folder.
 
The format of the XML file "text_XXX.xml" Tip: The XML file can be created and edited by using the configuration window, that can be opened from the menu "Options > Localized texts manager".

There is only 1 tag <pmtext> in the XML file, there is the required number of <txtid> subtags with id attribute in this tag. The value of this attribute is the user identifier of required text. There are <txt> tags with lang attribute in this tag, identifying the language version. The lang attribute may containt, for example, this value: en (English), de (German) ... For complete list see How to create an application using different national languages.

Example of the file content (the file does not have to include all stated language versions):

<?xml version="1.0" encoding="utf-8"?>
<pmtext>
...
<txtid id="id10">
  <txt lang="en">User text to set</txt>
  <txt lang="de">Aplikationstext zum Einstellen</txt>
  <txt lang="ru">Техт аппликации к наладке</txt>
  <txt lang="pl">Tekst użytkownika do wprowadzenia</txt>
  <txt lang="cs">Aplikační text k nastavení</txt>
  <txt lang="sk">Aplikačný text k nastaveniu</txt>
</txtid>
...
</pmtext>
 
Example of getting system localized text:
$.text("sys","day1")
The text identified as "day1" is saved in a file "text_sys.xml" in the PROMOTIC installation folder. The result of such procedure is having the text "Monday" for English, "Montag" for German language, etc.
Example of getting application localized text:
$.text("app","id10")
The author of the application created a file "text_app.xml" in the application folder. There is the <txtid id="id10"> tag in that file and the <txt> subtag that corresponds to the current language version (e.g. en).
Example of obtaining the system text by using the item parameter (nDay):
$.text("sys",$.join("day",$.par("nDay")))
 
Another option to get the localized text is to use Pm.EvalMacro or #pragma variable.
Configuration items in extended value editor:
Select localized textOpens the Localized texts manager window
XML file typeDefines text source file type, i.e. 1st parameter of the $.text() macro expression.
Text identifierDefines the identifier of desired text, i.e. 2nd parameter of the $.text() macro expression.
© MICROSYS, spol. s r. o.Tavičská 845/21 703 00 Ostrava-Vítkovice