YOUSEFUL / FILEMAKER

Getting started with Youseful plug-ins

This first exercise uses Youseful Text. You need Windows x64, FileMaker Pro, YsflText.fmx64, and a practice database you can edit. No other plug-in or external account is required.

1. Install the plug-in

In FileMaker, open Edit > Settings > Plug-Ins and click Reveal Plug-in Folder. Older releases label Settings as Preferences. Close FileMaker, copy YsflText.fmx64 into that folder, restart FileMaker, and enable YsflText in the Plug-Ins tab. These controls are described in Claris plug-in settings.

For the current user and FileMaker version, the usual Windows destination is %LOCALAPPDATA%\FileMaker\FileMaker Pro\<version>\Extensions\. Claris installation guidance describes the version-specific folder. Use the folder revealed by your own FileMaker installation.

When upgrading, remove the previous version of that product from all loaded Extensions locations before installing its replacement. See Upgrade notes.

2. Confirm that FileMaker can call it

Create a script named Youseful - First calculation with these two steps:

Set Variable [ $version ; Value: YsflTx_Version ]
Show Custom Dialog [ "Youseful Text" ; $version ]

Run it. This build returns YsflText v.1.0.0.

Set Variable takes a variable name and a calculation for its Value, as explained in Claris Set Variable. Create each script step in the editor, then put the shown expression in its calculation dialog. Pasting a whole script block into a calculation will not work.

For read-only calculations you can also use Tools > Data Viewer > Watch when advanced tools and your access privileges permit it. See Claris Data Viewer. Use scripts for operations that write files, send mail, change settings or display dialogs; watch expressions can evaluate more than once.

3. Run a useful calculation

Replace the two steps with:

Set Variable [ $clean ; Value: YsflTx_Collapse ( "  Youseful   Software  " ) ]
Show Custom Dialog [ "Cleaned text" ; $clean ]

Expected result: Youseful Software.

4. Capture errors before another call

This deliberately invalid pattern demonstrates error handling:

Set Variable [ $result ; Value: YsflTx_RegexMatch ( "abc" ; "[" ) ]
Set Variable [ $errorCode ; Value: YsflTx_LastError ]
Set Variable [ $errorText ; Value: YsflTx_LastErrorText ]
If [ $errorCode <> 0 ]
    Show Custom Dialog [ "Pattern error" ; $errorText ]
End If

Expected: a regex error, code 1003. The wording may include the pattern location. Most operational functions clear the plug-in's previous error when they start. Save the result and error information immediately; HTTP status and other getters can also clear the error. File and Query have additional conventions described in their guides.

Reading the examples

; separates calculation parameters. Optional parameters can be left off the end; use "" to keep a position when supplying a later parameter.
¶ inside a FileMaker string represents a paragraph separator. Many functions accept lists or options separated by it.
Backslashes in FileMaker string literals are escaped. The native path C:\Data\report.txt is written as "C:\\Data\\report.txt" in a calculation. Youseful File's PathJoin and SpecialFolder can build paths without literals.
$name is a script variable. Demo::Result means a field named Result in the Demo table occurrence. Create fields only when a tutorial asks for them.
A container result belongs in a container field, not a text field.
Run the steps in order. Configure/default settings and runtime globals can affect later calls until reset or FileMaker exits.

Continue with the Text tutorial, or choose another tutorial.