insertunicodecharacterAdded by IBM on August 8, 2013 | Version 1 (Original)
|Allows you to insert Unicode control characters inside text strings. While this function allows you to insert any Unicode control character, it is most frequently used to insert control characters that ensure that bidirectional text is displayed correctly. This is needed when the required order of your text does not match the order specified by the Unicode Bidirectional Algorithm (UBA).
For example, a file path such as C:\mydir\FORMS\MYFORMS.XFDL (where capital letters indicate Right-To-Left text) renders as C:\mydir\MYFORMS.XFDL\FORMS according to UBA. To ensure that this file path renders correctly, you need to insert Unicode control characters before the delimiters. These control characters will then override the text directions assumed by UBA.
This function checks the text string to see if control characters already exist, to avoid inserting duplicate control characters.
This function can be written as part of an XFDL compute or XPath expression.
Table 1. insertunicodecharacter parameters
|reference||Reference string, literal string or XPath expression||a literal string or reference to the text that you want to apply the function to.|
|controlCharacter||string||16 bit Unicode control characters placed before each delimiter. these characters must be specified in UTF-16 hexadecimal format.
For example, 0x200E.
|delimiter||symbol or character||Special symbol or character that marks the beginning or end of a unit of data.
For example, forward slash (/).
Space separated lists of multiple delimeters are supported.
String containing formatted text.
The insertunicodecharacter function can be used in three ways:
- XFDL computes
- XPath expressions
- XForm binds
In the following example, assume that capital letters indicate Right-To-Left text. As you can see, the text string in the compute shows day/year/month. This is the direction that the Unicode Bidirectional Algorithm assumed that the text should take when it encountered the string 19/MAY/2007. The Unicode Bidirectional Algorithm parsed the 19 in a Left-To-Right direction, but switched to a Right-To-Left direction when it encountered the Right-To-Left text in MAY. The Right-To-Left direction continued when it reached 2007, which can be rendered as both Left-To-Right and Right-To-Left and therefore gives not strong directional cues to the Unicode Bidirectional Algorithm. As a result, the Unicode Bidirectional Algorithm places the year before the month.
With insertunicodecharacter, we can override the Unicode Bidirectional Algorithm so that the date is displayed in the correct order (MAY/19/2007) by inserting Left-To-Right Unicode control characters before the / delimiter.
The following example uses an XPath expression to call the insertunicodecharacter function.
<xforms:setvalue ref="instance('main')/field_contents" value="xfdl:
insertunicodecharacter("19/2007/MAY", 0x200E,'/' )">
The following example uses an XForms bind to call the insertunicodecharacter function:
calculate="xfdl: insertunicodecharacter("19/2007/MAY",0x200E,'/' )"/>