24U Toolbox Plug-In 3.2 Syntax

Hosting friendly functionality

In order for plugin function to work on the server you have to create a config file on server and set the read permission to everyone:

For webdirect you also need to create /opt/FileMaker/FileMaker Server/Data/Documents/ folder with appropriate permissions.

Toolbox plugin functions won’t work on server in these cases:

• File 24uPluginsAllowedFunctions.txt doesn’t exist
• Plugin doesn’t have permission to read 24uPluginsAllowedFunctions.txt
• The record in the file 24uPluginsAllowedFunctions.txt with the database name and the list of allowed function doesn’t exist

Toolbox plugin won’t work on secondary machine if /opt/FileMaker/FileMaker Server/Data/Documents/ folder doesn’t exist.

Format of 24uPluginsAllowedFunctions.txt file

Every line represent one database, first is the name of the database (with suffix .fmp12) followed by tabulator and then function names separated by ‘|’ (vertical bar).

Or name of the database (with suffix .fmp12) followed by tabulator and then the word “any” if you want to allow all the plugin functions. You can find template of 24uPluginsAllowedFunctions.txt in Examples.

Example

In following example: * Solution MyFileMakerDatabaseOnServer.fmp12 is allowed to use all the 24U plugin functions * Solution MyOtherFileMakerDatabaseOnServer.fmp12 is allowed to use functions Toolbox_Set, Toolbox_GetNameForIP and Toolbox_GetGlobal. Calling function other than those 3 will fail

MyFileMakerDatabaseOnServer.fmp12   any

MyOtherFileMakerDatabaseOnServer.fmp12  Toolbox_Set|Toolbox_GetNameForIP|Toolbox_GetGlobal

Registered Script Steps

• Toolbox Set
• Toolbox ExecuteSQL
• Toolbox DoFileMakerScript
• Toolbox DoSystemScript
• Toolbox SetDefaultPrinter
• Toolbox Register
• Toolbox SetScriptShortcut
• Toolbox SetGlobal

Registered Calculation Functions

• Toolbox_Version( { versionFormat } )
• Toolbox_Register ( selector )
• Toolbox_ExecuteSQL( SQLCommand { ; fieldSeparator { ; recordSeparator } } )
• Toolbox_DoSystemScript( scriptText ; scriptInterpreter { ; waitForResult { ; timeout } } )
• Toolbox_DoFileMakerScript( scriptName { ; scriptParameter } { ; delayOrTime } )
• Toolbox_GetNameForIP( hostIP )
• Toolbox_GetIPforName( hostName )
• Toolbox_GetClientPublicIPAddress
• Toolbox_GetSpecialWindows
• Toolbox_GetPrinterNames
• Toolbox_GetDefaultPrinter
• Toolbox_SetDefaultPrinter( printerName )
• Toolbox_SetScriptShortcut( key ; scriptName { ; scriptParameter } { ; scriptControl } )
• Toolbox_RegExp_PatternCount( text ; searchPattern )
• Toolbox_RegExp_Substitute( text ; searchPattern ; replaceString1 { ; replaceString2 … } )
• Toolbox_RegExp_Match( text ; searchPattern { ; flag } } )
• Toolbox_MergeText( text )
• Toolbox_ValueType( value )
• Toolbox_Get( selector { ; scriptId } )
• Toolbox_Set( selector ; newValue )
• Toolbox_SetGlobal( key ; value { ; moreOptions } )
• Toolbox_GetGlobal( key )
• Toolbox_Encode( encoding ; text )
• Toolbox_Decode( encoding ; text )
• Toolbox_GetAsHTML( variableName { ; tags { ; classes { ; styles } } } )

Function Description with Examples

Toolbox_Version( { versionFormat } )

Returns version string of the active 24U Toolbox Plug-In, formatted as requested by the parameter.

Parameters

Parameter values for versionFormat

Description

This function is very important and its output format is uniform in all 24U Plug-Ins. You should call this function every time you need to check if the Plug-In is properly installed to the FileMaker Pro. Even if the Plug-In is not registered (or badly registered) this function should work. Calling this function in the startup script of your solution is recommended.

Result

Returns requested version format or platform. If this function returns “?” then the Plug-In is not properly installed or FileMaker cannot load and activate it for some reason.

Example 1

Toolbox_Version( "long" )

This returns the Plug-In name and its version. In this case it is “24U Toolbox Plug-In 3.0”.

Example 2

Toolbox_Version( "platform" )

Returns “macOS”, “Linux” or “Windows” depending on the platform the Plug-In is currently running.

Example 3

Toolbox_Version( "autoupdate" )

Returns “01010300” for the Plug-In version 1.1.3.

Toolbox_Register ( selector )

Provides special functionality to operate with plugin serial numbers.

Parameter values for selector

Description

Use this function to register or unregister 24U Toolbox Plug-In, to get information about current registration state, or to invoke GUI providing basic registration information and purchase capabilities.

Result

Returns zero or error code depending on the selector.

Example 1

Toolbox_Register( "TBX25C016-BXMW-VNW7-L8AJ-3KGX-VWG8" )

This function will register the Plug-In with client serial number TBX25C016-BXMW-VNW7-L8AJ-3KGX-VWG8 for 16 users.

Example 2

Toolbox_Register( "user@mail.com" )

In case you do not have a serial number, but you want to try the Plug-In out, use the string with your email address as selector.

Example 3

Toolbox_Register( "unregister" )

This function will unregister every serial number related to 24U Toolbox Plug-In.

Example 4

Toolbox_Register( "About window" )

Similar to opening FileMaker preferences, navigating to the Plug-Ins tab and double-clicking on 24U Toolbox Plug-In.

Note: All serial numbers here are only for demonstration purposes. They will not work in the Plug-In.

Functions without registration check

These functions do not need to be registered, because of the performance benefit:

• Toolbox_GetTimestamp
• Toolbox_ValueType
• Toolbox_ExecuteSQL
• Toolbox_Register
• Toolbox_Version
• Toolbox_Get

Toolbox_ExecuteSQL( SQLCommand { ; fieldSeparator { ; recordSeparator } } )

Tells the Plug-In to execute SQL command and returns the result.

Parameters

Description

This command tries to execute SQL command and returns the result. If an array of multiple records is a result of the command, it is returned as tab delimited text with records separated by returns, unless custom separators are specified.

Result

The function returns the result of the SQL Command.

Examples

Toolbox_ExecuteSQL( "select * from FileMaker_Tables" )

Returns a list of FileMaker tables.

Toolbox_DoSystemScript( scriptText ; scriptInterpreter { ; waitForResult { ; timeout } } )

Tells the Plug-In to launch the specified script in the system shell.

Parameters

Possible values for ‘scriptInterpreter’

Possible values for ‘waitForResult’

Description

The function executes the script.

Result

Returns either the standard output (and error) of the script (“wait”) or the scriptId (“dontWait”). In the case of Plug-In error (such as wrong parameters), the function returns “?”. Use Toolbox_Get( “lastError” ) to obtain the error code.

Example 1

Toolbox_DoSystemScript( "DIR C:" ; "BAT" )

This executes specified BAT script that lists all directories and files in the root directory of disk C: on Windows.

Example 2

Toolbox_DoSystemScript( "echo HELLO" ; "BASH" )

This executes specified BASH script and returns “HELLO”.

Example 3

Toolbox_DoSystemScript( "echo started; sleep 10; echo done" ; "BASH" ; "dontWait" )

This runs a BASH script asynchronously and returns a process id. Remember this id to track output of the script with Toolbox_Get.

Example 4

Toolbox_DoSystemScript( "echo started; sleep 10; echo done" ; "BASH" ; "wait" ; 2.5 )  &  ¶  & 
Toolbox_Get( "lastErrorMessage" )

This will return “? ¶ Timeout Error” after 2.5 seconds. (Depending on the region of your FileMaker installation, you may need to write the decimal as 2,5 instead.)

Example 5

Toolbox_DoSystemScript( "php C:\php.php" ; "BAT" )

This executes BAT script that runs PHP script on Windows (only if PHP is correctly installed in the system).

Toolbox_DoFileMakerScript( scriptName { ; scriptParameter } { ; delayOrTime } )

Tells the Plug-In to launch the FileMaker script. Note: FileMaker scripts cannot be performed on FileMaker Server.

Note: Toolbox_DoFileMakerScript is not supported on Linux version.

Parameters

Description

This command tries to schedule or launch the FileMaker script. If delayOrTime parameter is not specified, the script should run immediately.

Result

The function returns 0 if it managed to execute or schedule the script. In the case of error, the function returns negative error code.

Attention

The Toolbox Plug-In cannot remember scheduled scripts if FileMaker is restarted.

Note: Scheduled FileMaker scripts are called only when FileMaker is in IDLE state. Therefore, FileMaker script execution can be further delayed if FileMaker is busy. Note: This function doesn’t work on FileMaker Server.

Example 1

Toolbox_DoFileMakerScript( "Default Script" )

This tries to execute the script named “Default Script” instantly.

Example 2

Toolbox_DoFileMakerScript( "Default Script" ; "105" )

This tries to execute the script named “Default Script” instantly. The script receives a parameter with value 105.

Example 3

Toolbox_DoFileMakerScript( "Default Script" ; "230" ; 10.5 )

This tries to schedule the script named “Default Script”. The script receives a parameter with value 230. The script will be executed 10.5 seconds after this command being executed.

Example 4

Toolbox_DoFileMakerScript( "Default Script" ; "50" ; GetAsTimestamp( "3/10/2012 11:30 AM" ))

This tries to schedule the script named “Default Script”. The script receives a parameter with value 50. The script will be executed 3/10/2012 at 11:30 AM.

Toolbox_GetNameForIP( hostIP )

Gets hostname for the given IP.

Parameters

Description

Uses DNS service of the operating system to obtain the name for the given IP.

Result

The function returns a hostname. In the case of error, the function returns negative error code.

Example

Toolbox_GetNameForIP( "209.85.149.99" )

Returns DNS record for IP Address 209.85.149.99.

Toolbox_GetIPforName( hostName )

Gets IP for the given hostname.

Parameters

Description

Uses DNS service of the operating system to obtain the IP for the given name.

Result

The function returns host IP. In the case of error, the function returns negative error code.

Example

Toolbox_GetIPforName( "www.24u.cz" )

Returns an IP Address for hostname “www.24u.cz”.

Toolbox_GetClientPublicIPAddress

Gets your public ip address.

Description

This command tries to get your internet public ip address. If you are not behind NAT the returned address is the same as the address from your network interface. Otherwise, it returns the address of frontmost NAT in your network.

Result

The function returns your public ip address. In the case of error, the function returns negative error code.

Attention

If this command does not work in your system it may be due wrong firewall setting. Please enable two-way communication for your FileMaker Pro in your firewall setting to get this command to work.

Example

Toolbox_GetClientPublicIPAddress

Returns your public ip address.

Toolbox_GetSpecialWindows

Gets a list of opened special FileMaker windows.

Note: Toolbox_GetSpecialWindows is disabled on server.

Description

This command tries to get a list of special FileMaker windows such as “Data Viewer” and “Script Debugger” etc.

Result

The function returns a value list of the special FileMaker windows delimited by the line break.

Example

Toolbox_GetSpecialWindows

Returns “Data viewer” if it is opened.

Toolbox_GetPrinterNames

Gets a list of installed printers.

Note: Toolbox_GetPrinterNames is not supported on Linux version.

Description

This command tries to get a list of printers currently installed in the system.

Result

The function returns the list of printers currently installed in the system. The printer names are delimited by line break.

Example

Toolbox_GetPrinterNames

Returns the list of printers currently installed in the system.

Toolbox_GetDefaultPrinter

Gets the default printer.

Note: Toolbox_GetDefaultPrinter is not supported on Linux version.

Description

This command gets the name of default printer currently used in the system.

Result

The function returns the name of default printer of the current session. If no printer is set as default, the function returns ““.

Example

Toolbox_GetDefaultPrinter

Returns the name of default printer of the current session.

Toolbox_SetDefaultPrinter( printerName )

Sets the specified printer as a default printer.

Note: Toolbox_SetDefaultPrinter is not supported on Linux.

Parameters

Description

This command sets the printer described in printerName parameter as a default printer in the system.

Result

The function returns the name of the printer which was actually set. In the case of error, the function returns “?”. Use Toolbox_Get( “lastError” ) to obtain error code.

Note

Use Toolbox_GetPrinterNames to obtain the list of printers and choose one line as a parameter for this function.

Example

Toolbox_SetDefaultPrinter( "HP710" )

Sets “HP710” as a new default printer for the system or returns “?” if “HP710” cannot be the default one.

Toolbox_SetScriptShortcut( key ; scriptName { ; scriptParameter } { ; scriptControl } )

Assigns a keyboard shortcut for script. Only one script can be assigned to a given shortcut. All keyboard shortcuts are forgotten when FileMaker quits.

Note: Toolbox_SetScriptShortcut cannot be used with FileMaker Server.

Parameters

Description

Assigns a keyboard shortcut for script. All keyboard shortcuts are forgotten when FileMaker quits.

Result

The function returns 0 if event is successfully installed or uninstalled. In case of error the function returns negative error code.

Attention

Keys “F8” - “F13” are usually reserved for system functions on macOS. Shortcuts will interfere with these functions.

Example 1

Toolbox_SetScriptShortcut( "ctrl alt F1" ; "Default Script" )

This installs the script named “Default Script” for a shortcut “ctrl+alt+F1”. When this shortcut is pressed, the script will be triggered.

Example 2

Toolbox_SetScriptShortcut( "ctrl alt F1" ; "" )

This uninstalls any script for a shortcut “ctrl+alt+F1”.

Example 3

Toolbox_SetScriptShortcut( "" ; "" )

This removes all installed scripts for all previously inserted shortcuts.

Toolbox_RegExp_PatternCount( text ; searchPattern )

Finds a defined regular expression pattern in the text and returns the number of occurrences.

Parameters

Description

This function will find a defined regular expression pattern in the text and returns the number of occurrences. Text in “searchPattern” parameter can be styled. If so the function will become style sensitive.

Result

The function return the number of occurrences found. In the case of error, the function returns “?”. Use Toolbox_Get( “lastError” ) to obtain error code.

Example

Toolbox_RegExp_PatternCount( "I was born in the USA on 12/02/1973." ; "([0-9]{1,2})[./-]([0-9]{1,2})[./-]([0-9]{2}|[0-9]{4})" )

Returns 1 because there is one date in the string.

Toolbox_RegExp_Substitute( text ; searchPattern ; replaceString1 { ; replaceString2 … } )

Finds and replaces pattern in specified text.

Parameters

Description

This function finds and replaces found text. Text in “searchPattern” parameter can be styled. If so the function will become style sensitive.

Result

The function returns text with replaced patterns. In the case of error, the function returns “?”. Use Toolbox_Get( “lastError” ) to obtain error code.

Example

Toolbox_RegExp_Substitute( "I was born in the USA on 12/02/1973." ; "([0-9]{1,2})[./-]([0-9]{1,2})[./-]([0-9]{2}|[0-9]{4})" ; "10" ; "12" ; "2008" )

Returns "I was born in the USA 10/12/2008.".

Toolbox_RegExp_Match( text ; searchPattern { ; flag } )

Provides a PCRE compatible regular expression match.

Parameters

Description

This function looks for regular expression matches using the provided search pattern.

Result

For each match, it returns the match itself, plus every capturing group for the given match (if any). The format depends on flag:

In case of error, the function returns “?”. Use Toolbox_Get( "lastError" ) to obtain the error code.

Example 1

Toolbox_RegExp_Match( "The answer is 42." ; "[0-9]{1,}")

Returns

[
    "42"
]

Example 2

Toolbox_RegExp_Match( "Hello world!" ; "(?i)[AEIOUY]" ; "matchAll")

Here, we used the “(?i)” option to ignore case. This returns

[
    [
        "e"
    ],
    [
        "o"
    ],
    [
        "o"
    ]
]

Example 3

Toolbox_RegExp_Match( 
  "I was born in the USA on 12/02/1973. I moved to East Timor on 28-11-94." ; 
  "([0-9]{1,2})[./-]([0-9]{1,2})[./-]([0-9]{4}|[0-9]{2})" ; 
  "matchFirst"
)

Returns

[
    "12/02/1973",
    "12",
    "02",
    "1973"
]

Example 4

Toolbox_RegExp_Match( 
  "I was born in the USA on 12/02/1973. I moved to East Timor on 28-11-94." ; 
  "([0-9]{1,2})[./-]([0-9]{1,2})[./-]([0-9]{4}|[0-9]{2})" ; 
  "matchAll"
)

Returns

[
    [
        "12/02/1973",
        "12",
        "02",
        "1973"
    ],
    [
        "28-11-94",
        "28",
        "11",
        "94"
    ]
]

Toolbox_MergeText( text )

This function finds values in the FileMaker text and replaces them by their values.

Note: Toolbox_MergeText is not supported on Linux version.

Parameters

Description

This function finds values in the FileMaker text and replaces them by their values. All values are calculated only once. If the value contains the style this style is used. Otherwise, the original style is preserved.

Result

The function returns merged text. In the case of error, the function returns “?”. Use Toolbox_Get( “lastError” ) to obtain error code.

Example

Toolbox_MergeText( "There are <<NumberField>> records." )

If the field named NumberField contains number 5 it returns "There are 5 records.".

Toolbox_ValueType( value )

This function returns the type of its parameter.

Parameters

Description

The function determines the type of its parameter. It can be FileMaker Text, Number, Date, Time, Timestamp or Container. This can be useful when you need precisely control script or custom function which is dependent on parameter type.

Result

The function always return FileMaker text and never fails. It can return “Text”, “Number”, “Date”, “Time”, “Timestamp”, “Container” or “” for unknown type.

Example

Toolbox_ValueType( "There are 5 records." )

Returns “Text” because input value type is FM text.

Toolbox_Get( selector { ; scriptId } )

This function returns Toolbox Plug-In internal parameters.

Parameters

Possible values for selector

Description

Generic function to get various Plug-In parameters.

Result

The function returns a value specified by the selector. In the case of error, the function returns “?”. Use Toolbox_Get( “lastError” ) to obtain error code. Toolbox_Get( “lastError” ) never fails. In case of Toolbox_Get( "scriptInfo" ; scriptId ), the return value is a JSON object:

{
  "error" : "[script error]",
  "output" : "[script output]",
  "status" : "[script status]"
}

The following table lists every script status and explains its meaning.

Example 1

Toolbox_Get( "lastError" )

Returns the last function error code, or 0 if the last function was performed properly.

Example 2

Suppose 18037 is a script Id which was returned by

 Toolbox_DoSystemScript(
   "echo foo; make sandwich; echo bar" ;
   "bash" ; 
   "dontWait"
)

Then calling

Toolbox_Get("scriptInfo" ; 18037)

will return an output such as:

{
    "error": "make: *** No rule to make target `sandwich'.  Stop.\n",
    "output": "foo\nbar\n",
    "status": "finished"
}

To parse this JSON, you can use the native FileMaker function JSONGetElement. For example:

Let ( [
    info = Toolbox_Get("scriptInfo" ; 18037)
  ];
  "STATUS¶======¶" & JSONGetElement(info ; "status")  & "¶¶" &
  "OUTPUT¶======¶" & JSONGetElement(info ; "output")  & "¶¶" &
  "ERROR¶======¶" & JSONGetElement(info ; "error") 
)

returns:

STATUS
======
finished

OUTPUT
======
foo
bar


ERROR
======
make: *** No rule to make target `sandwich'.  Stop.

Toolbox_Set( selector ; newValue )

This function sets Toolbox Plug-In internal parameters.

Parameters

Possible values for selector

Description

Generic function to get various Plug-In parameters.

Result

The function returns state of required parameter. In the case of error, the function returns “?”. Use Toolbox_Get( “lastError” ) to obtain error code.

Example

Toolbox_Set( "globalDieInterval" ; 9.5 )

Sets parameter “globalDieInterval” to 9.5 seconds.

Toolbox_SetGlobal( key ; value { ; moreOptions } )

Stores global value which can be read on any database.

Parameters

Possible values for moreOptions parameter.

Description

Use this function to store global value which can be obtained by Toolbox_GetGlobal( key ) in any opened database. If “dieOnClose” is not specified the key-value combination will live until the FileMaker application is closed. Specifying the “dieOnClose” parameter will cause the Plug-In will periodically check if the database file is opened (the Plug-In will use Get( FileName ) and DatabaseNames functions from FileMaker calculation engine) and erase key-value combination if the database has been closed. The Plug-In is not able to distinguish between two different databases with the same name.

To manually delete value stored under a key call Toolbox_SetGlobal( key ; “” ). To manually delete all global values call Toolbox_SetGlobal( “” ; “” ).

Result

The function returns the actual value which has been set under the key. In the case of error, the function returns “?”. Use Toolbox_Get( “lastError” ) to obtain the error code.

Example 1

Toolbox_SetGlobal( "g_UserContext" ; "user-defined-context-1" )

This will set value “user-defined-context-1” under the key “g_UserContext”. It can be read by calling Toolbox_GetGlobal( “g_UserContext” ) in any opened solution.

Example 2

Toolbox_SetGlobal( "g_UserContext" ; "user-defined-context-1" ; "dieOnClose" )

This will set value “user-defined-context-1” under the key “g_UserContext”. It can be read by calling Toolbox_GetGlobal( “g_UserContext” ) in any opened solution. If the database file, where Toolbox_SetGlobal has been called, is closed, the value “user-defined-context-1” will be reset to ““. There is the maximum time interval between file closing and value erasing. This interval can be set by Toolbox_Set(”globalDieInterval” ; newInterval ) and by default it is set to 60 seconds.

Example 3

Toolbox_SetGlobal( "g_Picture" ; PictureField )

The Plug-In will store content of PictureField into the global dictionary under the key “g_Picture”. This container can be loaded any time from any opened solution until the FileMaker application is closed or value reset.

Toolbox_GetGlobal( key )

Loads global value previously stored by Toolbox_SetGlobal.

Parameters

Description

Use this function to load global value previously stored by Toolbox_SetGlobal.

Result

The function returns the actual value for key. If the key has not been specified the function returns ““. In the case of error, the function returns”?“. Use Toolbox_Get(”lastError” ) to obtain the error code.

Example

Toolbox_GetGlobal( "g_UserContext" )

The function returns actual value of global key “g_UserContext”.

Toolbox_GetTimestamp

Basic function for time measurement.

Description

This function uses most precise functions of the operating system to obtain current (local) time. It creates a FileMaker timestamp which contains fractions of seconds so it can be used to measure time with more accuracy than one second. The function is also very fast: its execution time is approx. 30 µs long. **Note: Unlike all other Plug-In functions, Toolbox_GetTimestamp does not set lastError and lastErrorMessage (which can be obtained with Toolbox_Get). This is due to performance reasons.

Result

FileMaker Timestamp with current (local) time.

Example

Toolbox_GetTimestamp

Returns accurate timestamp in the following format: 14.10.2025 11:41:16,971122.

Toolbox_Encode( encoding ; text )

This function encodes text using a method specified by encoding.

Note: Toolbox_Encode is not supported on Linux version.

Parameters

Possible values for encoding

Description

This function encodes given input text to specified encoding. For decoding see Toolbox_Decode.

Result

The function returns encoded input text. In the case of an error, the function returns “?”. Use Toolbox_Get( “lastError” ) to obtain the error code. Also note, that empty input text may not be well-defined for various encodings.

Example 1

Toolbox_Encode("UTF-8 to Base64" ; "Text to be encoded.")

Returns “VGV4dCB0byBiZSBlbmNvZGVkLg==”.

Example 2

Toolbox_Encode("UTF-8 to Base64" ; "")

Returns ““.

Toolbox_Decode( encoding ; text )

This function decodes text.

Note: Toolbox_Decode is not supported on Linux version.

Parameters

Possible values for encoding

Description

This function decodes given input text to specified encoding. For encoding see Toolbox_Encode.

Result

The function returns decoded input text. In the case of an error, the function returns “?”. Use Toolbox_Get( “lastError” ) to obtain the error code. Also note, that empty input text may not be well-defined for various encodings.

Example

Toolbox_Decode("Base64 to UTF-8" ; "QmFzZTY0IGVuY29kZWQgdGV4dC4=")

Returns "Base64 encoded text.".

Toolbox_GetAsHTML( variableName { ; tags { ; classes { ; styles } } } )

This function converts rich-text to HTML with CSS. Converting works in 4 stages: * First, the HTML tags are determined based on tags parameter, * than the remaining unused formatting is converted to CSS classes as defined in classes parameter, * than the remaining unused formatting is converted to inline CSS styles based on styles parameter, * other unused formatting is not used for output styling.

Default values produce HTML tags compliant with HTML5 standard and CSS styles that are supported at least by Chrome, Firefox and Safari web browsers.

Two special characters < and > from input text are automatically replaced with HTML entities < and >

Text encoding remains unchanged.

Several special characters from input text are automatically replaced by HTML entities or HTML tags as described in the following table.

Parameters

Supported text formatting

Unsupported text formatting: line spacing, vertical alignment (top, center, bottom).

• Combination of (double)underlining and strikethrough can cause partial or wrong results in some web browsers.

** Paragraph alignment can’t be combined with other text formatting in tags, classes or style parameters (using the + delimiter).

*** Color, font and size cannot be further parametrized, please see examples below on how to use them.

Supported variableName types

Toolbox_GetAsHTML("$myTextVariable")

• Variable name given as string (inside quotes) produces the best results including paragraphs and text alignment.

Toolbox_GetAsHTML(Let($ToolboxInput=solution::textField;"$ToolboxInput"))

• Text field on input is stored inside local variable $ToolboxInput and then passed to the plugin. This is equivalent to the previous one, so this also supports paragraphs and text alignment.

Toolbox_GetAsHTML("Hello world2")

• Text inserted directly will produce HTML with line breaks, but it will not contain paragraphs and text alignment.

Result

The function returns decoded input text. In the case of an error, the function returns “?”. Use Toolbox_Get( “lastError” ) to obtain the error code.

Example 1

Toolbox_GetAsHTML("$ToolboxInput")

All transformations are enabled and as much as possible text formatting is preserved.

If variable $ToolboxInput contains “Bold and underlined text” than the result will be:

<p><b>Bold</b> and <u>underlined</u> text</p>

That should look in web browser similarly to this:

Bold and underlined text

Example 2

Toolbox_GetAsHTML("Hello world2" ; "all" ; "" ; "all")

All transformations are enabled except creating CSS classes. The result will be:

<span style="color:#ff2712;">Hello</span><b> world</b><b><sup>2</sup></b>

That should look in web browser similarly to this:

Hello world²

Example 3

Toolbox_GetAsHTML("Bold and underlined text" ; "all" ; "" ; "all")

Only the &ltstrong> tag will be created (2nd parameter) and there will be only one class for underlined text (3rd parameter), all other text formatting is discarded because of forbidden inline styling in the last parameter. The result will be:

<style type="text/css">
.myClass { text-decoration:underline; }
</style>
<strong>Bold</strong> and <span class="myClass">underlined</span> text

That should look in web browser similarly to this:

.myClass { text-decoration:underline; }

Bold and underlined text

Example 4

Toolbox_GetAsHTML("Green italic and important text." ; "" ; "underline+bold=myImportantClass" ; "color")

No tag will be created (2nd parameter) and there will be only one class for both underlined and bold text (3rd parameter), color will be the only inlined css style, other formatting is discarded. The result will be:

<style type="text/css">
.myImportantClass { font-weight:bold;text-decoration:underline; }
</style>
<span style="color:#66b132;">Green italic</span> and <span class="myImportantClass">important</span> text.

That should look in web browser similarly to this:

.myImportantClass { font-weight:bold;text-decoration:underline; }

Green italic and important text.

Example 5 - simple reformatting

Toolbox_GetAsHTML("Green italic and underlined text." ; "bold=i" ; "" ; "")

Italic HTML tag will be used for bold text and all other formatting is discarded. HTML tags are not styled to match the original appearance. The result will be:

Green italic and <i>important</i> text

That should look in web browser similarly to this:

Green italic and important text

Example 6 - style ambiguity

Toolbox_GetAsHTML("Colors: red + blue = purple" ; "" ; "color=myColorClass" ; "")

Toolbox_GetAsHTML("Colors: red + blue = purple" ; "bold=i" ; "" ; "")

Color, font and size text formatting is simplified so that it does not require any parameter. When some text formatting is used in tags parameter, the actual value of the style is discarded. You can preserve the value by using the classes or the styles parameter. Result of this example will be:

Colors: <u>red</u> + <u>blue</u> = <u>purple</u>

That should look in web browser similarly to this:

Colors: red + blue = purple

Example 7 - style ambiguity

Toolbox_GetAsHTML("Colors: red + blue = purple" ; "bold=i" ; "" ; "")

In this case, color will be styled using classes with given prefix. The result will be:

<style type="text/css">
.myColorClass { color: #ff0000; }
.myColorClass1 { color: #0000ff; }
.myColorClass2 { color: #800080; }
</style>
Colors: <span class="myColorClass">red</span> + <span class="myColorClass1">blue</span> = <span class="myColorClass2">purple</span>

That should look in web browser similarly to this:

Colors: red + blue = purple

Example 8 - style ambiguity

Toolbox_GetAsHTML("Colors: red + blue = purple" ; "" ; "" ; "all")

In this case, color will be styled using inline styles. The result will be:

Colors: <span style="color:#ff0000;">red</span> + <span style="color:#0000ff;">blue</span> = <span style="color:#800080;">purple</span>

That should look in web browser similarly to this:

Colors: red + blue = purple

Example 9 - more lines of text

Toolbox_GetAsHTML( "$ToolboxInput" ; "center=center" ; "right=myRightAlignClass")

Default HTML tag for paragraph is <p> and this one will be used for the first (left aligned) paragraph here.

Centered text is forced to use deprecated <center> tag and CSS class myRightAlignClass will be used for all right aligned text.

Inline css styles will be used for all other supported styling because of missing 4th parameter that defaults to “all”.

Assuming variable $ToolboxInput is containing this text:

First line with some formatted text.

Final line aligned to right.

Then the result will be:

<style type="text/css">
.myRightAlignClass { text-align:right; }
</style>
<p>First line with some <span style="font-weight:bold">formatted</span> text.</p>
<center>Centered line.</center>
<p class="myRightAlignClass">Final line aligned to right.</p>

First line with some formatted text.

Final line aligned to right.

.myRightAlignClass { text-align:right; }

First line with some formatted text.

Centered line. Final line aligned to right.

Example 10 - complete HTML page

Base64Decode ( 
  Toolbox_Encode ( 
    "UTF-8 to Base64" ; 
    "<!DOCTYPE html><html><head><meta charset=\"UTF-8\"><title>Hello world</title></head><body>" & Toolbox_GetAsHTML ( $myStyledText ) & "</body></html>" 
  )  ; 
  "helloworld.html" 
)

This example produces complete HTML page from variable $myStyledText and returns it as a container. You should see a file named “helloworld.html” by setting the result of this example into a container field.

You can save the file on a disk by selecting “Export Field Contents…” from field’s context menu, or you can set the container to be saved on a disk by making the field external in field’s storage options.

Error Codes Table

Here is the list of all error codes which can be returned from the Plug-In. Whenever a function returns “?”, it signals an error. Use Toolbox_Get( "lastError" ) to obtain the error code and Toolbox_Get( "lastErrorMessage" ) to obtain additional error description.