24U Toolbox Plug-In 3.2 Syntax

Specification revision: 1, 2020-12-10



Hosting friendly functionality

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

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

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:

Toolbox_Version( { versionFormat } )

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

Parameters

versionFormatDefines the format of the returned version.

Parameter values for versionFormat

"short"To get just the version number. Default value.
"long"To get the plug-in name followed by its version number.
"platform"To get the platform the code is currently running on.
"autoupdate"To get autoupdate compatible (comparable) version number.

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.

Examples

Toolbox_Version( "long" )
This returns the plug-in name and its version. In this case it is "24U Toolbox Plug-In 3.0".

Toolbox_Version( "platform" )
Returns "Mac OS X", "iOS", "Linux" or "Windows" depending on the platform the plug-in is currently running.

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

SerialNumber Register given SerialNumber and return an error code.
EmailAddress Tries to activate with given email address and return an error code. Trial version is valid only after you confirm email
HashActivate a serial number with a hash received from 24U. Used for offline activation.
"Registration Window" Show the "Registration window" and return 0.
"About Window" Show the "About window" and return 0.
"Status" Return the actual registration state of the plugin: Demo, Demo expired, Trial, Trial Expired, Registered or Dead.
"Unregister" Unregister all serial numbers related to the product and return an error code. Note: after this trial version days wont come back.
"Info"Returns current plugin status and its registered serial numbers.
"ActivationChallenge"Returns generated challenge string. This string is sent to 24U.
"Purchase" ; webAddressOpens web browser with given webAddress. Given webAddress should point to 24U Store. This functionality is not implemented for FileMaker Server and Linux.

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.

Examples

Toolbox_Register( "TBX30I-BXMWC-VNW7W-L8AJS-3KGX3-VWG84" )
This function will register the iOS plug-in with serial number TBX30I-BXMWC-VNW7W-L8AJS-3KGX3-VWG84.

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.

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.

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

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.

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

Tells the plug-in to execute SQL command and returns the result.

Parameters

SQLCommandThe SQL command which should be executed.
fieldSeparatorOptional field separator. Only the first character is used. The default field separator is a "Tab".
recordSeparatorOptional record separator. Only the first character is used. The default record separator is a line break.

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. In the case of error, the function returns negative error code.

Examples

Toolbox_ExecuteSQL( "select * from FileMaker_Tables" )
Returns a list of FileMaker tables.

Toolbox_DoSystemScript( scriptText ; scriptInterpreter )

Tells the plug-in to launch the specified script in the system shell.

Note: Toolbox_DoSystemScript is not supported in iOS and Linux version.

Parameters

scriptTextThe text of the script that should be run.
scriptInterpreterThe interpreter that should run the script.

Possible values for scriptInterpreter

scriptInterpreterScript typeDescription and platform
"APPLE"Apple scriptThe scriptText is an AppleScript. Available on MAC OS X.
"BASH"Bash scriptThe scriptText is a Bash Script. Available on MAC OS X.
"PHP"PHP scriptThe scriptText is a PHP Script. Available on MAC OS X.
"BAT"Bat scriptThe scriptText is a bat text file. Available on Windows.
"VBS"Visual Basic scriptThe scriptText is a Visual Basic Script. Available on Windows.

Description

The function starts the script and waits until it finishes. Then it returns the text that has been printed on the standard output.

Result

Result of the script. It is usually the text that is printed by the script into the standard output. In the case of error, the function returns "?". Use Toolbox_Get( "lastError" ) to obtain the error code.

Examples

Toolbox_DoSystemScript( "DIR C:" ; "BAT" )
This executes specified BAT script that should list all directories and files in the root directory of disk C: on Windows.

Toolbox_DoSystemScript( "echo HELLO" ; "BASH" )
This executes specified BASH script that should write "HELLO" to the standard output. The function should return "HELLO".

Toolbox_DoSystemScript( "php C:\php.php" ; "BAT" )
This executes BAT script that runs PHP script on Windows (only if PHP is correctly installed in 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 in Linux version.

Parameters

scriptNameThe name of the script that should be executed. If the name is not valid, the function returns an error -50.
scriptParameterAny data that should be sent to the script as a parameter. No parameter is default.
delayOrTimeThe time interval after that the script should be executed, or TimeStamp value. In the first case use FileMaker number i.e. 1.8. Time is in [s]. Time must be a positive number. If the time delay for execution is longer than 1 day, a warning -1001 is generated, and the script is scheduled anyway. In the second case use FileMaker TimeStamp value.

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. On iOS it can take longer.
Note: This function doesn't work on FileMaker Server.

Examples

Toolbox_DoFileMakerScript( "Default Script" )
This tries to execute the script named "Default Script" instantly.

Toolbox_DoFileMakerScript( "Default Script" ; "105" )
This tries to execute the script named "Default Script" instantly. The script receives a parameter with value 105.

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.

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

hostIPThe source IP address.

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.

Examples

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

hostNameThe source hostname.

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.

Examples

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.

Examples

Toolbox_GetClientPublicIPAddress
Returns your public ip address.

Toolbox_GetSpecialWindows

Gets a list of opened special FileMaker windows.

Note: Toolbox_DoSystemScript is not supported in iOS and Linux version.

Description

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

Attention

This command is disabled on server.

Result

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

Examples

Toolbox_GetSpecialWindows
Returns "Data viewer" if it is opened.

Toolbox_GetPrinterNames

Gets a list of installed printers.

Note: Toolbox_DoSystemScript is not supported in iOS and 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.

Examples

Toolbox_GetPrinterNames
Returns the list of printers currently installed in the system.

Toolbox_GetDefaultPrinter

Gets the default printer.

Note: Toolbox_DoSystemScript is not supported in iOS and 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 "".

Examples

Toolbox_GetDefaultPrinter
Returns the name of default printer of the current session.

Toolbox_SetDefaultPrinter( printerName )

Sets specified printer as a default printer.

Note: Toolbox_DoSystemScript is not supported in iOS and Linux version.

Parameters

printerNameThe identifier of the printer which should be set as default.

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.

Examples

Toolbox_SetDefaultPrinter( "HP710" )
Sets a "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. All keyboard shortcuts are forgotten when FileMaker quits.

Note: Toolbox_DoSystemScript is not supported in iOS and Linux version.

Parameters

keyThe keyboard shortcut in format Modifier & " " & rawKey. Modifier can be: "", "shift", "ctrl", "alt", "super" or their combination like "shift alt" or "ctrl alt". The "super" key means Apple key on Mac or Windows key on Windows. RawKey can be any key from keyboard + some special keys: "F1" - "F13", "enter", "esc", "pageup", "pagedown", "up", "down", "left", "right", "delete", "backspace", "space", "tab". RawKey parameter is case insenstive.
scriptNameThe name of script which should be triggered.
scriptParameterThe optional script parameter.
scriptControlThis optional parameter tells FileMaker how to handle another runing scripts,when script specified in this command is triggered. Possible values are: "Halt", "Exit", "Resume", "Pause".

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 Mac OS X. Shortcuts will interfere with these functions.

This command is disabled on server.

Examples

Toolbox_SetScriptShortcut( "ctrl alt F1" ; "Default Script" )
This installs the script named "Default Script" for shortcut "ctrl+alt+F1". When this shortcut is pressed, the script will be triggered.

Toolbox_SetScriptShortcut( "ctrl alt F1" ; "" )
This removes all installed scripts for shortcut "ctrl+alt+F1".

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

textThe source text where to perform find.
searchPatternRegular expression defining what to find.

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 the case of error, the function returns "?". Use Toolbox_Get( "lastError" ) to obtain error code.

Examples

Toolbox_RegExp_PatternCount( "I was born in USA 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

textThe source text where to perform find & replace.
searchPatternRegular expression defining what to find.
replaceString1Text which will replace found string.
replaceString2 ...The next text to replace found string. The number of strings should be the same as the regular expression needs.

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 the case of error, the function returns "?". Use Toolbox_Get( "lastError" ) to obtain error code.

Examples

Toolbox_RegExp_Substitute( "I was born in USA 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 USA 10/12/2008.".

Toolbox_MergeText( text )

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

Note: Toolbox_MergeText is not supported in Linux version.

Parameters

textText which should be searched and merged. All <<fieldname>> parts are substituted by the real value of the fieldname. All <<$variable_name>> parts will be substituted by the real value of the variable.

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 the case of error, the function returns "?". Use Toolbox_Get( "lastError" ) to obtain error code.

Examples

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

valueFileMaker value which type you want to obtain.

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.

Examples

Toolbox_ValueType( "There are 5 records." )
Returns "Text" because input value type is FM text.

Toolbox_Get( selector )

This function returns Toolbox Plug-In internal parameters.

Parameters

selectorWhat parameter to get.

Possible values for selector

selectorDescription
"lastError"Returns the Plug-In last error.
"lastErrorMessage"Returns the Plug-In last error message.
"registrationWarning"The selector has been deprecated in favor of Toolbox_Register("Status").
"stderr"Returns standard error output of the last executed script. Supported are Bash and PHP.
"inlineDocumentation"Returns "on" or "off" based on status of inlineDocumentation in Plug-In. This selector doesn't work on FileMaker Server.

Description

Generic function to get various plug-in parameters.

Result

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

Examples

Toolbox_Get( "lastError" )
Returns last function error code or 0 if last function was performed properly.

Toolbox_Set( selector ; newValue )

This function sets Toolbox Plug-In internal parameters.

Parameters

selectorWhat parameter to set.

Possible values for selector

selectorDescription
"globalDieInterval"Global variable can be set to be automatically erased when their parent database file is closed. The plug-in uses polling mechanism to determine if the file has been closed (evaluating function DatabaseNames). This interval specifies how often is should check the file is closed. The default value is 60 seconds and you can specify even fraction of seconds to be perfectly accurate. However try to keep it as long as possible (ones of seconds at least). The polling requires system resources and calling this often will slow down the FileMaker Pro application.
"inlineDocumentation"Allows to turn off or on inlineDocumentation. Possible values are "on" or "off". This selector doesn't work on FileMaker Server.

Description

Generic function to get various plug-in parameters.

Result

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

Examples

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

keyUnique key to the dictionary of values. This key should be unique across all opened databases.
valueFileMaker field or variable. Field / variable type is also stored.
moreOptionsOptions to specify some special behavior for previous key-value combination.

Possible values for moreOptions parameter.

valuedescription
"dieOnClose"The current key-value combination will be erased when you close the current database.

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 the case of error, the function returns "?". Use Toolbox_Get( "lastError" ) to obtain the error code.

Examples

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.

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.

Toolbox_SetGlobal( "g_Picture" ; PictureField )
The plug-in will store content of PictureField into 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

keyUnique key to the dictionary of values. This key should be unique across all opened databases.

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 the case of error, the function returns "?". Use Toolbox_Get( "lastError" ) to obtain the error code.

Examples

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 time (now). 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.

Result

FileMaker Timestamp with current time.

Examples

Toolbox_GetTimestamp
Returns most accurate timestamp. In the time of writing this manual it was: 27.5.2011 17:27:03,873641 (the timestamp is formatted using current, Czech locale).

Toolbox_Encode( encoding ; text )

This function encodes text.

Note: Toolbox_Encode is not supported in Linux version.

Parameters

encodingThe encoding of the input text and the encoding of the result.
textThe input text to be encoded.

Possible values for encoding

encodingDescription
"UTF-8 to Base64"The encoding of the input text is assumed to be UTF-8 and the encoding of the result will be Base64.

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.

Examples

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

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

Toolbox_Decode( encoding ; text )

This function decodes text.

Note: Toolbox_Decode is not supported in Linux version.

Parameters

encodingThe encoding of the input text and the encoding of the result.
textThe input text to be decoded.

Possible values for encoding

encodingDescription
"Base64 to UTF-8"The encoding of the input text is assumed to be Base64 and the encoding of the result will be UTF-8.

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.

Examples

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:

Default values produce HTML tags compliant with HTML5 standard and CSS styles that are supported at least by Chrome, Firefox and Safari webbrowsers.
Two special characters < and > from input text are automatically replaced with HTML entities &lt; and &gt;
Encoding of text is not changed.
Several special characters from input text are automatically replaced by HTML entities or HTML tags as described in following table.
InputReplacement
<&lt;
>&gt;
&&amp;
non-breaking space - Char(160)&nbsp;
line break - Char(8232)<br/>

Parameters

ParameterDescriptionDelimiter characterValue for converting all supported Value for no convertingDefault valueExample
variableNameName of variable (that contains formatted text) given as string.
Formatted text inserted directly will not support alignment of paragraphs.
More about input formats.
This is the only required parameter.
n/an/an/an/aHello world2
tagsList of all text formattings that should be converted to HTML tags.
For default value, these HTML tags will be used in this order:
<p>, <b>, <i>, <u>, <s>, <mark>, <sup>, <sub>.
"all""""all""bold+underline=h1
underline=u
bold=strong"
classesList of all text formattings that should be converted to custom-named CSS classes. "all=somePrefix""""all=tbx""bold+italic=myImportantComments
bold=myBoldClass
italic=myCommentClass"
stylesList of all text formattings that should be converted into inline CSS styles.
"all""""all""condense
uppercase
lowercase"

Supported text formattings

BasicLining*SpacingLettersParagraph alignment**With value***
bold underline condense smallcaps left color
italic wordunderline extend uppercase center font
highlight doubleunderline superscriptlowercase right size
strikethrough subscript titlecase full

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

* Combination of (double)underlining and strikethrough can cause partial or wrong results in some webbrowsers.

** Paragraph alignment can't be combined with other text formattings 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")

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

Toolbox_GetAsHTML("Hello world2")

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 webbrowser 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 webbrowser similarly to this:

Hello world2

Example 3

Toolbox_GetAsHTML("Bold and underlined text"; "bold=strong"; "underline=myClass" ; "")

Only the <strong> tag will be created (2nd parameter) and there will be only one class for underlined text (3rd parameter), all other text formattings are discarded because 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 webbrowser similarly to this:

Bold and underlined text

Example 4

Toolbox_GetAsHTML("Green italic and underlined 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 formattings are 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 webbrowser similarly to this:

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 webbrowser similarly to this:

Green italic and important text

Example 6 - style ambiguity

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

Color, font and size text formattings are simplified so they do not require parameter. When one of these text formattings are 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 webbrowser similarly to this:

Colors: red + blue = purple

Example 7 - style ambiguity

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

In this case, color will 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 webbrowser similarly to this:

Colors: red + blue = purple

Example 8 - style ambiguity

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

In this case, color will 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 webbrowser 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 alligned 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.

Centered line.

Final line aligned to right.

Than 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>

That should look in webbrowser similarly to this (depending on available width and webviewer's support for old <center> tag):

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 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. The error codes are derived from MacErrors.h header file from Mac OS. If function fails it either returns "?" signaling error or it directly returns the error code. If it returns "?" you can use Toolbox_Get( "lastError" ) to obtain the code.

CodeDescription
0No error.All requested actions were successful.
-4Not implemented.The function is not implemented on this platform.
-50Parameter error.Wrong number, type, value or order of parameter(s). Please check parameters against the documantation again.
2400Unknown error.Unexpected (probably system related) error occured.
24001Demo mode expired.If you want to keep using the plug-in, you must register it or buy it for particular environment.
24002Product expired.Trial period is over. If you want to keep using the product, you must buy it for particular environment.
24003SN limit was met.The serial number is already registered on too many computers.
24004Product is dead.The product expired and cannot be used any more. Please download the new version from 24U Software.
24005Invalid serial number.Serial number you entered is not valid.
24006Activation failed.Activation failed probably due to some network error. Please, check your connection to the internet and try again later.
24007Deactivation failed.Deactivation failed probably due to some network error. Please, check your connection to the internet and try again later.
24008Unknown serial number.The given serial number cannot be used for the current product. It has been stored so that other product can try to use it.
24009Blacklisted serial number.The given serial number has been blacklisted and cannot be used anymore. Please, contact 24U Support if you need more information.
24010eSellerate engine not installed.This product uses eSellerate to validate user registration and purchases, but its installation failed. Please, reboot the computer or try again later.