Troi Text Plug-in FMP6 conversion note

overview | download | details | comments | buy-it

This document discusses the conversion of function calls from FileMaker Pro 6.

Text Plug-in 4.1 is FileMaker 7 native

Troi Text Plug-in 2.7 was the first version to use the FileMaker 7 syntax or API (Application Program Interface) to do its work. Later versions also use the FileMaker 7 Native API.

NOTE The API is the same for FileMaker Pro 7 through 15.

NOTE Below we will discuss Troi Text Plug-in 2.8, but this also applies to later versions with a higher number, like version 4.1.

To make use of the new API you have to make sure the calls to the plug-in are done the right way. Below are some considerations when converting to Troi Text Plug-in 2.8.

New function syntax

The plug-in functions have a different syntax compared to the FileMaker Pro 6 plug-in.

For example the ANDText function has this syntax in the classic API:

External("TrText-ANDText", TextA & "<trsep>" & TextB)

The syntax in the new native API looks like this:

TrText_ANDText( switches ; TextA ; TextB )

Note that functions look like a real function call, no longer a call to External(). Also a hyphen "-" is no longer allowed, so the hyphens have changed to underscores "_" instead. Note too that parameters don't have to be concatenated with a separator. Instead use a semicolon ";" to separate the parameters. For future enhancements we have added a new first parameter: switches.
Below is an example how this function would appear in ScriptMaker:

Set Field [textField ,
              TrText_ANDText( "-ReturnAtEnd" ; TextA ; TextB) ]

TIP Function names are no longer case sensitive and will change to the correct case after you close the "Specify Calculation" dialog box.

Multiple parameters and new switches

As seen from the syntax, plug-in functions now can have multiple parameters. To make this plug-in more consistent, most functions now have a switches parameter as the first parameter. This makes enhancing the plug-in in the future easier.

TIP Switches are not case sensitive.

Omitting optional parameters

It is now possible to have optional parameters, although Text Plug-in currently does not have a function that allows optional parameters. But in general, when you omit an optional parameter be sure to add an extra semicolon after the last one, otherwise FileMaker will show an alert that there are too few parameters in this function. For example, taken from our File Plug-in, below we omitted the 3rd parameter at the end (initialfolder). This is the correct way to do this:

Set Field [theFile,
          TrFile_SelectFileDialog("-Unused" ; "Select a file" ; )]

New parameter limits

The plug-in functions now have a size limit of 1 Gb per parameter (up from the total of 64000 character limit for all parameters in FileMaker 6). The Troi Text Plug-in 2.8 can handle those bigger parameters, however, displaying the results in FileMaker 7 or 8 can take a long time.

Converting the function call from FileMaker 6

When converting FileMaker does not change the plug-in call. So after conversion you need to do this manually. Here are the global steps:

• remove the External(" at the beginning
• in the function name: change - to _ and remove spaces, add a ( at the end.
• change the name of the function (in some cases)
• add as first parameter: "-Unused" ( if no switch parameter is there)
• split the remaining parameters: separate each with a ;

Let's for example take this Text Plug-in 2.1.6 call:

External("TrText-SortLines", SortOptions & "|" & TextField )

This needs to be changed to this Text Plug-in 2.8 call:

TrText_SortLines ( SortOptions ; TextField )

TIP Just copy script or steps from the example files, they are all in the Text Plug-in 2.8 format!

Specific functions notes

Check your calls to the SumText functions

FileMaker 7 evaluates calculations different than FileMaker 6. It also short-circuits calculations, meaning that FileMaker is computing only what is needed to determine the result. To make things more complicated, FileMaker 8.0v1 had a bug which made SumText work incorrectly!

Conversion of SumText

With the the release of the update of FileMaker Pro 8.0v2 the original syntax of the SumText calculation is now again working properly. As the original syntax is more general we strongly recommend to use this syntax. Below you'll find the recommended syntax.

TIP FileMaker Pro 8.5 has a new List(...) function, which is similar to the SumText functionality of Troi Text Plug-in. As this new function is native to FileMaker it is best to use it for all FileMaker Pro 8.5 and later deployments. If, however, you deploy your solution on a mixed FileMaker 8.5, 8 and/or 7 platform, the SumText function can still be used.

Conversion of SumText from FileMaker 6

To make SumText work you must change a calculation as follows.

In the related table

If for example you previously had this calculation:

cSumTextCalc = External("TrText-SumTextCalc", Food )

You need to change it in FileMaker 8 to:

cSumTextCalc = TrText_SumTextCalc( Food )

TIP Make sure the calculation result is an unstored number and that the checkbox "Do not evaluate if all referenced field are empty" is checked.

In the main table

If you previously had this SumText calculation:

External("TrText-SumTextResult", External("TrText-SumTextStart" , "¶" ) & Sum(RelationName::cSumTextCalc))

You need to change it in FileMaker 7 and FileMaker 8 to:

SumTextResult = Left( TrText_SumTextStart( "¶") & Sum(RelationName::cSumTextCalc) ; 0 ) & TrText_SumTextResult( "" )

This will ensure that the plug-in gets called in the right order.

TIP Don't forget that the dash ("-") has changed to an underscore ("_") in the function names of FileMaker 8 functions.

See also the example files of Troi Text 2.8.1 (or later) which have this modification applied.

Conversion of SumText from FileMaker 7 to FileMaker 8

With the the release of the update of FileMaker Pro 8.0v2 the original syntax of the SumText calculation is now again working properly. So if you have the native SumText syntax for FileMaker Pro 7 it should also work in FileMaker Pro 8.0v2 or later.
For completeness: The recommended original syntax looks like this:

1) In your related file define a calculation field.

cSumTextCalc = TrText_SumTextCalc( TextField )

2) In the main file define a field for the SumText result:

SumTextResult = Left( TrText_SumTextStart( "¶") & Sum(RelationName::cSumTextCalc) ; 0 ) & TrText_SumTextResult( "" )

Please look at the example files where they are implemented like this.

If you previously converted your function calls for FileMaker Pro 8

It is recommended that you convert back to the original syntax of the SumText calculation.
See the SumText.fp7 example file which uses the best way to implement it.
Also please note:

• You no longer need to use a different sumTextInstanceID, please leave the sumTextInstanceID parameter empty.
• You no longer need to use a different field in the related table for each SumText occurrence.