logo: Troi Text Plug-in for FileMaker

Troi Text Plug-in 4.5
for FileMaker Pro 16
USER GUIDE

November 2017







logo: Troi Plug-ins for FileMaker

Troi
Boliviastraat 11
2408 MX Alphen aan den Rijn
The Netherlands

You can visit the Troi web site at: www.troi.com

Troi Text Plug-in is copyright 1998-2017 of Troi Automatisering. All rights reserved.








Table of Contents


Installing plug-ins

Starting with FileMaker Pro 12 a plug-in can be installed directly from a container field. Installation is therefore very easy: just open the "All Text Examples.fmp12" example file and the startup script will install the plug-in for you. See also the EasyInstallTroiPlugins.fmp12 example file which contains the actual plug-in and install script.

TIP You can check which plug-ins you have loaded by going to the plug-in preferences: choose Preferences from the Edit menu, and then choose Plug-ins.

You can now open the file "All Text Examples.fmp12" to see how to use the plug-in's functions. There is also a function and script step reference available.


If you have problems

This user guide tries to give you all the information necessary to use this plug-in. So if you have a problem please read this user guide first. You can also visit our support web page:

            www.troi.com/support

This page contains FAQ's (Frequently Asked Questions), help on registration and much more. If that doesn't help you can get free support by email. Send your questions to support@troi.com with a full explanation of the problem. Also give as much relevant information (version of the plug-in, which platform, version of the operating system, version of FileMaker Pro) as possible. Note that due to spam we have to filter incoming email. It might happen that non-spam email is filtered out too. If you have sent an email and you don't get an answer, try to send another email, slightly differently formulated and include the word "FileMaker" in the body text.

If you find any mistakes in this manual or have a suggestion please let us know. We appreciate your feedback!

TIP You can get more information on returned error codes from the OSErrrs database on our web site. This free FileMaker database lists all error codes for Windows and Mac OS!


What can this plug-in do?

Troi Text Plug-in is a very powerful tool for dealing efficiently with text in your FileMaker Pro database. All from within FileMaker you can:

  • create combinational sets from 2 text fields:
    • get all lines that are the same
    • get all lines that differ
    • and other combinations
  • get (unique) lines and sort words and lines
  • make a text sum from a related file that updates without a script
  • parse XML Text
  • check spelling via calculations
  • and more...

Software requirements

System requirements for Mac OS

Mac OS X 10.7 (Lion), OS X 10.8 (Mountain Lion), OS X 10.9 (Mavericks), OS X 10.10 (Yosemite), OS X 10.11 (El Capitan), macOS 10.12 (Sierra), macOS 10.13 (High Sierra).

NOTE Troi Text Plug-in 4.5 will probably run on Mac OS X 10.6.8 (Snow Leopard), but we have not tested this and no longer provide support for this.

System requirements for Windows

Windows 7 on Intel-compatible computer 1 GHz or faster
Windows 8, Windows 8.1
Windows 10 including Creators Update

FileMaker Pro requirements

FileMaker Pro 12 or FileMaker Pro Advanced 12.
FileMaker Pro 13 or FileMaker Pro Advanced 13.
FileMaker Pro 14 or FileMaker Pro Advanced 14.
FileMaker Pro 15 or FileMaker Pro Advanced 15.
FileMaker Pro 16 or FileMaker Pro Advanced 16.

FileMaker Server requirements

FileMaker Server 12 , 13, 14, 15 or 16.
FileMaker Server Advanced 12, 13, 14, 15 or 16.

You can use FileMaker Server 12-16 to serve databases that use functions of Troi Text Plug-in (client-side): you need to have the plug-in installed at the clients that use these functions.

Troi Text Plug-in can also be used by FileMaker Server as a server-side plug-in or as a plug-in used by the web publishing engine. To use Troi Plug-ins as a server-side or web-side plug-in you need to purchase a special Server/Web license. More information can be found in the download or on our web site.


Getting started

Using external functions

Troi Text Plug-in adds new functions to the standard functions that are available in FileMaker Pro. The functions added by a plug-in are called external functions. You can see those extra functions for all plug-ins at the top right of the Specify Calculation box:

External functions in Specify Calculation box

You use special syntax with external functions: FunctionName ( parameter1 ; parameter 2 ) where FunctionName is the name of an external function. A function can have zero or more parameters. Each parameter is separated by a semi-colon. Plug-ins don't work directly after installation. To access a plug-in's function, you need to add the calls to the function in a calculation, for example in a text calculation in Define Fields or in a script in Script Workspace (formaly called ScriptMaker).

Where to add the external functions?

External functions for this plug-in can be used in a calculation field when you are defining fields (choose Define Database from the File menu). Also the plug-in's functions can be used in a script step using a calculation, for example in a Set Field script step.

IMPORTANT The SumText functions have to be used in a specific way, to create the desired effect. See the section on SumText functions for the specifics on this.

Using script steps

Starting with FileMaker 16 plug-ins can also add script steps. You can select these script steps in the script steps pane in Script Workspace, or you can begin typing the script step name, then choose the script step from the list that appears. The script steps expand the possible actions you can perform with FileMaker Pro.

Script steps in Script Workspace screenshot of Troi File Plug-in script step

NOTE only steps that perform an action have been added as a script step. Functions that have no side effects (like for example TrText_ANDText) are only available as an external function.

Simple example

We start with a simple example to get you going. Say you have a database Pages.fmp12, with a text field called myText. You want to list al unique words from myText. Go to Define Fields and define this calculation:

  myUniqueWords	Calculation = TrText_UniqueWords ( "-Unused" ; myText )

Put the newly created calculation field on the layout.

If the contents of myText is "An ape is an ape, a rose is a rose" myUniqueWords will contain:

	An 
	Ape 
	Is
	A 
	Rose

Please take a close look at the included example files, as they provide a great starting point. From there you can move on, using the functions of the plug-in as building blocks. Together they give you powerful text tools.

You can use globals or variables

With the release of FileMaker Pro 8 and later it is possible to use variables in calculations. Our example files in the download now both use global fields and variables to pass parameters and store the results of a plug-in function.

As this release of Troi Text is intended for FileMaker Pro 12 and higher, we continue to move the scripts to use variables wherever possible. Note that not all examples are using variables yet.

All plug-in functions work with variables just fine. For example if you have this script step

  Set Field [ myResultField ; TrText_UniqueWords ( "-Unused" ; myText ) ]

With variables you can alternatively use:

  Set Variable [ $myResult ; TrText_UniqueWords ( "-Unused" ; myText ) ]

The main advantage of variables is that you don't need to define global fields that clutter your database definitions. The variables can stay local to the script.


Using SumText functions

Note: FileMaker Pro 8.5 introduced a new List (...) function, which is similar to the SumText functionality of Troi Text Plug-in. As this function is native to FileMaker it is best to use it for all FileMaker Pro 8.5 only 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.

What SumText can do

The purpose of the three SumText functions is to get the concatenation of all the text of a text field in a related file. The 3 functions (TrText_SumTextStart, TrText_SumTextCalc and TrText_SumTextResult) work together to achieve this result. Before describing how to define SumText fields we give you two examples of what is possible:

Example 1

Say you have a file "Companies.fmp12" holding company information and "Person.fmp12" holding names and data of Persons. Companies.fmp12 has a relation "Contacts" that relates all the contact persons of a company. So for company UFP you might have the following related contact persons:

ID Name
1 Jean-Luc Picard
2 Lt. Commander Worf
3 Geordy LaForge

With the SumText functions it is possible to define a field that captures all contact persons in one field. As a separator we use ", ". So in the file "Companies.fmp12" you can define a sumtext field "All contacts" that has the following contents:

"Jean-Luc Picard, Lt. Commander Worf, Geordy LaForge"

And if someone creates a new contact person, say "Dr. Pulaski", the field is automatically (without running a script) updated to:

"Jean-Luc Picard, Lt. Commander Worf, Geordy LaForge, Dr. Pulaski"

The contents of this field will always reflect the current data of the related file.

Example 2

Using the same files and relations as in Example 1, but now in Contacts there is a third field called Favorites:

ID Name Favorites
1 Jean-Luc Picard Earl Grey Tea
2 Lt. Commander Worf NaPlah
3 Geordy LaForge Twinkies
4 Dr. Pulaski Ice Cream
5 Dr. Crusher Earl Grey Tea

With the SumText functions it is possible to define a field that captures all the favorites of the contact persons in one field. This time the separator is a return "¶". In the file "Companies.fmp12" you define a sumtext field "All Favorites" that has the following contents:

Earl Grey Tea ¶
NaPlah ¶
Twinkies ¶
Ice Cream ¶
Earl Grey Tea

In a script you can easily copy this list of favorites to a global "gFavorites", and then use this as a multikey to find all of the related favorites.

Defining SumText Functions

These are the steps to make SumText work:

1- In your related file define a calculation field.

Go to "File, Manage, Database, Fields" and create a new calculation field. Here this field is named "cSumTextCalc". Use the "TrText_SumTextCalc" function in the calculation, like this:

  cSumTextCalc = TrText_SumTextCalc ( TextField )

Here "TextField" is the name of the field you want to sum. This new calculation will do the actual concatenation. Use a new field for each SumText calculation instance that will call from the main table.

IMPORTANT Make sure you make this field both unstored and a number, otherwise SumText won't work!

2- In the main file define a field for the SumText result.

Use the following calculation:

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

In this calculation the function TrText_SumTextStart signals the plug-in to start summing. It takes a separator as parameter. The part Sum(RelationName::cSumTextCalc) makes FileMaker call all related fields and finally TrText_SumTextResult signals to the plug-in that all has been summed and the result can be returned.

NOTE You no longer need to use a different sumTextInstanceID, please leave the sumTextInstanceID parameter empty. See the SumText.fmp12 example file which uses these calculations.

You can also use this sumtext calculation in a Set Field script step or any other calculation in the main file.

Why this way?

You might say, why not make this simply one function like:

  TrText_SumText (RelationName::TextField )

This would be easier, but this is not possible with the current plug-in implementation of FileMaker.


Function and script step reference

For a description of all External Functions and External Script Steps added by Troi Text Plug-in please see the separate Reference.fmp12 file. For each function and script step you will find:

  • the correct syntax
  • the parameters/options to be used
  • the returned result
  • special considerations
  • an example usage

The same information is also available as online help on Troi's web site.

You can easily consult the online help directly from FileMaker, by clicking the Help button (the small question mark button) next to the function description in the functions pane or the script step description in the script steps pane.